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

まず vp run のドキュメント、プランにおける extra_args のパススルー動作、タスク設定スキーマを確認します。最初に、未指定の引数構文、検証、ヘルプ、および -- のセマンティクスを解決します。未設定時のパススルー動作を維持し、オプトインするタスクの利用体験を定義する合意済みの設計ができれば完了です。

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