docs: add RFC for task listing without no-intractive (--no-interactive and --json flags)

[kazupon]

About details, see docs/listing.md

[ubugeeei]

I want an alias for -l, and also.

So that AI and others can understand it, I’d like vp run --help to display a message saying “use --list to see the list of tasks.”

[ubugeeei]

Alternative:

Implement vp ls to list all vp environments, including tasks.
mise has an ls command:
https://mise.jdx.dev/cli/ls.html

(Though this might be more of a Vite+ issue than a Vite Task issue.)

[kazupon]

I want an alias for -l, and also.

So that AI and others can understand it, I’d like vp run --help to display a message saying “use --list to see the list of tasks.”

I've just updated for docs/listing.md

The -l alias is handy because it reduces the number of types. I’ve also made sure that the --help output explicitly explains this so that AI can detect it!

Implement vp ls to list all vp environments, including tasks.
mise has an ls command:
https://mise.jdx.dev/cli/ls.html

I’m concerned that the new ls command will add to the number of commands in Vite+, which means users will have to learn more commands (cognitive load).

Personally, I don’t think it’s necessary.

[TheAlexLichter]

Ideally we auto-detect the agent and print that by default (or generally in non-interactive mode)

[kazupon]

Thank you for your feedback!

Ideally auto-detecting the agent and adapting stdout accordingly would be great, but I can't see how to implement it reliably, there's no standardized way to detect which agent (Claude Code, Cursor, Copilot, Cline, etc.) is running, and each uses different environment variables (or none at all) 😅
We'd also need to keep adding detection logic as new agents appear.

For now, --list / --json as explicit flags feels like the pragmatic approach.
If a standard for agent detection emerges in the future, we can revisit auto-detection then.

[TheAlexLichter]

We can use isAgent from std-env

[kazupon]

Nice!
I didn't know about std-env's agent detection 🙈

That changes things. With this, when an agent is detected and vp run is executed, we could default to non-tractive output.

[branchseer]

Suggested change

	"package": null,
	"packageName": "",

Internally, we treat a package.json file without a name field as if the name is an empty string. Tasks within these packages can be matched with #task.

Also, every package is allowed to have an empty name, not just the workspace root.

[kazupon]

It makes sense to use an empty string since it's easier to handle!

[kazupon]

Related: voidzero-dev/vite-plus#1182 (comment). Would be nice if the --json output also included task dependency edges, not just a flat list of tasks.

One thing to think about: we need a unique identifier for tasks to represent the graph. Some approaches:

1. Incrementing number or random UUID. Unstable across runs and not readable.
2. package_name#task_name. Package name can be empty or not unique across the workspace.
3. package_path + task_name. Readable and unique, but needs a separator. Almost all characters are valid in Unix paths, so \0 is the only one guaranteed not to appear. It is valid in JSON.

For option 3, two ways to handle the separator:

• Use path#task_name when there's no # in the path (which is almost always the case). Fall back to \0 when there is.
• Always use \0. Consistent but a bit unconventional.

Edit: Come to think about it, these are really two features: one is listing available tasks before specifying which to run, and the other is showing the execution plan (with dependency edges) after the tasks to run have been determined.

I had the same thought 😅

I was planning to propose a --graph option as well, but started with --list first since it's simpler and self-contained.

Once --list lands, --graph (showing the execution plan with dependency edges after task resolution) would be a natural follow-up.

[branchseer]

The flat list is already implemented when the stdin is non-interactive (as is the case for AI agents). You can try it with echo '' | vp run. So --list doesn't seem necessary.

Our current flat list implementation is slightly different from the proposed one: tasks in the current package (detected with cwd) don't have the package# prefix, whereas tasks in other packages always have: they are consistent with what you'd type after vp run.

[branchseer]

Thanks for working on this!

The flat list already shows up when stdin is non-interactive, which covers AI agents out of the box. So rather than --list, we'd like to go with --no-interactive. It forces that same flat list even from a TTY, without introducing a new output format. This is also consistent with other subcommands like vp create which already have --no-interactive.

--json is great though. That's genuinely new and useful, so feel free to go ahead with that.

We'll skip AI agent detection since piped stdin already handles it naturally.

[kazupon]

Sounds good, I'll go with --no-interactive + --json.

I initially thought --no-interactive is a bit long to type, but since the primary use case is AI agents (where commands are generated programmatically rather than typed by hand), that's not really a concern.
Makes sense.

[kazupon]

I changed the title of this PR.
This PR focuses on the RFC.
I plan to handle the implementation in a separate PR.