Proposal: first-class task arguments (schema/validation/help) + argument-based branching

[ubugeeei]

Problem

vp run supports passing extra args after the task name (they are forwarded to the task command), but Vite Tasks does not appear to provide a first-class mechanism to:

• declare an argument schema (types/choices/default/help/env),
• validate arguments,
• generate --help for a task,
• and/or expose argument values to the task definition in a structured way so tasks can branch predictably.

This makes common patterns (deploy targets, feature flags, region selection, dry-run, etc.) rely on ad-hoc shell parsing and reduces discoverability.

Evidence (primary)

• Vite+ docs: extra args after the task name are passed to the task command.
  (see vp run docs)
• Plan implementation: extra_args are appended only to the last &&-split command (pass-through model), not parsed/typed.
• Task config schema appears command-centric and doesn’t show an args/usage-like field.

Use cases

• deploy <env> where env is one of dev|staging|prod (typed choices)
• --region, --dry-run, --verbose with defaults and validation
• Better UX: vp run deploy --help to show a task-specific help screen
• Avoid duplicating many similar tasks just to vary a parameter

Proposed behavior (Unspecified syntax; proposal is conceptual)

Allow task definitions to optionally declare an argument schema, e.g. (example only):

• positional args with enum choices
• flags and options with types, defaults, help text, and env fallbacks

Then, at runtime:

• validate inputs before execution
• expose parsed values to the task as env vars (MVP) or templating variables (future)
• generate task-level help (vp run <task> --help), without breaking existing pass-through

Backward compatibility

• If a task has no arg schema, behavior remains exactly the same (current pass-through).
• If a schema exists, only then enable validation/help/env injection.
• Preserve -- semantics (Unspecified; needs design) to avoid collisions between runner flags and task flags.

Minimal implementation suggestion (MVP)

1. Add optional args/usage metadata to the task schema (no runtime behavior yet).
2. Parse task args for tasks that opt in; inject values into env as VP_ARG_<name> (or similar).
3. Implement --help generation from the schema for opt-in tasks.
4. Later: allow templating/branching semantics based on parsed args.

Prior art

• mise task arguments + usage schema + help + env injection + templated branching:
  https://mise.jdx.dev/tasks/task-arguments.html
• just recipe parameters (arguments as first-class):
  https://just.systems/man/en/recipe-parameters.html

[branchseer]

The env var injection approach makes sense for MVP. One concern: if the task declares an arg schema, vp run deploy --help would need to show the task's help instead of passing --help through to the underlying command. How do you see that being disambiguated?