feat(12): add Command.createArgument

.codex/config.toml

@@ -1,5 +1,5 @@
-model = "gpt-5.5"
-review_model = "gpt-5.5"
+model = "gpt-5.3-codex"
+review_model = "gpt-5.3-codex"
 model_provider = "openai"
 
 approval_policy = "untrusted"

docs/en/v0/api/command/create.md

@@ -4,15 +4,15 @@ prev:
   text: "execOptions"
   link: "/en/v0/api/command/execOptions"
 next:
-  text: "createBooleanOption"
-  link: "/en/v0/api/command/createBooleanOption"
-description: "Creates a CLI command with a name, optional options/subject, and an execute handler."
+  text: "createArgument"
+  link: "/en/v0/api/command/createArgument"
+description: "Creates a CLI command with a name, optional options/subjects, and an execute handler."
 ---
 
 # create
 
 `create` declares a CLI command.
-You provide a name and an execute function, and you can also add options, a subject for positional arguments, or child commands.
+You provide a name and an execute function, and you can also add options, positional arguments, or child commands.
 
 ## Example
 
@@ -31,12 +31,12 @@ function create(
 
 function create<
   GenericOptions extends readonly Option[],
-  GenericSubject extends Subject
+  GenericSubjects extends Subjects
 >(
   name: string,
-  params: CreateCommandParams<GenericOptions, GenericSubject>,
+  params: CreateCommandParams<GenericOptions, GenericSubjects>,
   execute: (
-    params: CreateCommandExecuteParams<GenericOptions, GenericSubject>
+    params: CreateCommandExecuteParams<GenericOptions, GenericSubjects>
   ) => MaybePromise<void>
 ): Command
 ```
@@ -47,8 +47,8 @@ function create<
 - `params` (`CreateCommandParams`, optional) : command configuration.
 - `params.description` (`string`, optional) : help description.
 - `params.options` (`Option[]`, optional) : option parsers.
-- `params.subject` (`Subject | Command[]`, optional) : parser-like contract for positional data or sub-commands list.
-- `execute` : command handler. Receives typed `options` and, when present, a typed `subject`.
+- `params.subjects` (`Argument[] | Command[]`, optional) : either a list of positional arguments built with [`createArgument`](/en/v0/api/command/createArgument), or a list of child commands.
+- `execute` : command handler. Receives typed `options` and, when positional arguments are declared, typed `args`.
 
 ## Return value
 
@@ -66,5 +66,6 @@ function create<
 ## See also
 
 - [`exec`](/en/v0/api/command/exec) - Runs a root command from process arguments.
+- [`createArgument`](/en/v0/api/command/createArgument) - Builds a positional argument used in `subjects`.
 - [`createOption`](/en/v0/api/command/createOption) - Builds a single-value option.
 - [`createArrayOption`](/en/v0/api/command/createArrayOption) - Builds an array option.

docs/en/v0/api/command/createArgument.md

@@ -0,0 +1,72 @@
+---
+outline: [2, 3]
+prev:
+  text: "create"
+  link: "/en/v0/api/command/create"
+next:
+  text: "createBooleanOption"
+  link: "/en/v0/api/command/createBooleanOption"
+description: "Creates a positional argument parser for command subjects."
+---
+
+# createArgument
+
+Creates a positional argument parser to use in command `subjects`.
+
+## Example
+
+```ts twoslash
+// @version: 0
+<!--@include: @/examples/v0/api/command/createArgument/main.ts-->
+```
+
+## Syntax
+
+```typescript
+function createArgument<
+  GenericName extends string,
+  GenericSpec extends EligibleSpec
+>(
+  name: GenericName,
+  spec: GenericSpec,
+  params?: {
+    description?: string
+    optional?: false
+  }
+): Argument<GenericName, EligibleSpecOutput<GenericSpec>>
+
+function createArgument<
+  GenericName extends string,
+  GenericSpec extends EligibleSpec
+>(
+  name: GenericName,
+  spec: GenericSpec,
+  params?: {
+    description?: string
+    optional: boolean
+  }
+): Argument<GenericName, EligibleSpecOutput<GenericSpec> | undefined>
+```
+
+## Parameters
+
+- `name` (`string`) : argument key exposed in `args`.
+- `spec` (`EligibleSpec`) : parser/clean spec used to parse and validate the received positional value.
+- `params` (optional) : argument metadata.
+- `params.description` (`string`, optional) : help description.
+- `params.optional` (`boolean`, default `false`) : allows the argument to be omitted.
+
+## Return value
+
+- `Argument` : argument definition to place inside `subjects` in [`create`](/en/v0/api/command/create) or [`exec`](/en/v0/api/command/exec).
+
+## Notes
+
+- Positional arguments are consumed in declaration order.
+- In execute handlers, parsed values are available as `args.<name>`.
+- Use only `EligibleSpec` values (primitive-like specs, literals, unions, pipes/transforms, file, clean specs).
+
+## See also
+
+- [`create`](/en/v0/api/command/create) - Builds a command node using `subjects`.
+- [`exec`](/en/v0/api/command/exec) - Runs a root command from process arguments.

docs/en/v0/api/command/createArrayOption.md

@@ -25,11 +25,11 @@ Creates an option that parses a delimited list into a typed array.
 ```typescript
 function createArrayOption<
   GenericName extends string,
-  GenericContract extends EligibleContract,
+  GenericSpec extends EligibleSpec,
   GenericMinValues extends number
 >(
   name: GenericName,
-  contract: GenericContract,
+  spec: GenericSpec,
   params: {
     description?: string
     aliases?: readonly string[]
@@ -41,18 +41,18 @@ function createArrayOption<
 ): Option<
   GenericName,
   [
-    ...A.CreateTuple<ComputeOptionContract<GenericContract>, GenericMinValues>,
-    ...ComputeOptionContract<GenericContract>[]
+    ...A.CreateTuple<ComputeOptionSpec<GenericSpec>, GenericMinValues>,
+    ...ComputeOptionSpec<GenericSpec>[]
   ]
 >
 
 function createArrayOption<
   GenericName extends string,
-  GenericContract extends EligibleContract,
+  GenericSpec extends EligibleSpec,
   GenericMinValues extends number
 >(
   name: GenericName,
-  contract: GenericContract,
+  spec: GenericSpec,
   params?: {
     description?: string
     aliases?: readonly string[]
@@ -63,8 +63,8 @@ function createArrayOption<
 ): Option<
   GenericName,
   | [
-      ...A.CreateTuple<ComputeOptionContract<GenericContract>, GenericMinValues>,
-      ...ComputeOptionContract<GenericContract>[]
+      ...A.CreateTuple<ComputeOptionSpec<GenericSpec>, GenericMinValues>,
+      ...ComputeOptionSpec<GenericSpec>[]
     ]
   | undefined
 >
@@ -73,7 +73,7 @@ function createArrayOption<
 ## Parameters
 
 - `name` (`string`) : option name used as `--name`.
-- `contract` (`EligibleContract`) : parser or clean contract for each array element.
+- `spec` (`EligibleSpec`) : parser or clean spec for each array element.
 - `params` (optional) : option metadata and array constraints.
 - `params.required` (`true`, optional) : throws when option is missing.
 - `params.min` (`number`, optional) : minimum number of values.

docs/en/v0/api/command/createBooleanOption.md

@@ -1,8 +1,8 @@
 ---
 outline: [2, 3]
 prev:
-  text: "create"
-  link: "/en/v0/api/command/create"
+  text: "createArgument"
+  link: "/en/v0/api/command/createArgument"
 next:
   text: "createOption"
   link: "/en/v0/api/command/createOption"

docs/en/v0/api/command/createOption.md

@@ -25,11 +25,11 @@ Creates an option with a single parsed value from a DataParser or clean contract
 ```typescript
 function createOption<
   GenericName extends string,
-  GenericContract extends EligibleContract,
-  GenericOutput extends ComputeOptionContract<GenericContract> = ComputeOptionContract<GenericContract>
+  GenericSpec extends EligibleSpec,
+  GenericOutput extends ComputeOptionSpec<GenericSpec> = ComputeOptionSpec<GenericSpec>
 >(
   name: GenericName,
-  contract: GenericContract,
+  spec: GenericSpec,
   params: {
     description?: string
     aliases?: readonly string[]
@@ -39,11 +39,11 @@ function createOption<
 
 function createOption<
   GenericName extends string,
-  GenericContract extends EligibleContract,
-  GenericOutput extends ComputeOptionContract<GenericContract> = ComputeOptionContract<GenericContract>
+  GenericSpec extends EligibleSpec,
+  GenericOutput extends ComputeOptionSpec<GenericSpec> = ComputeOptionSpec<GenericSpec>
 >(
   name: GenericName,
-  contract: GenericContract,
+  spec: GenericSpec,
   params?: {
     description?: string
     aliases?: readonly string[]
@@ -54,7 +54,7 @@ function createOption<
 ## Parameters
 
 - `name` (`string`) : option name used as `--name`.
-- `contract` (`EligibleContract`) : parser or clean contract used to validate/transform the value.
+- `spec` (`EligibleSpec`) : parser or clean spec used to validate/transform the value.
 - `params` (optional) : option metadata and requirement behavior.
 - `params.required` (`true`, optional) : throws when option is missing.
 - `params.description` (`string`, optional) : help description.

docs/en/v0/api/command/exec.md

@@ -31,11 +31,11 @@ function exec(
 
 function exec<
   GenericOptions extends readonly Option[],
-  GenericSubject extends Subject
+  GenericSubjects extends Subjects
 >(
-  params: CreateCommandParams<GenericOptions, GenericSubject>,
+  params: CreateCommandParams<GenericOptions, GenericSubjects>,
   execute: (
-    params: CreateCommandExecuteParams<GenericOptions, GenericSubject>
+    params: CreateCommandExecuteParams<GenericOptions, GenericSubjects>
   ) => MaybePromise<void>
 ): Promise<void>
 ```
@@ -46,8 +46,8 @@ function exec<
 - `params` (`CreateCommandParams`) : command configuration for root.
 - `params.description` (`string`, optional) : displayed in help output.
 - `params.options` (`Option[]`, optional) : option definitions parsed before execute.
-- `params.subject` (`Subject | Command[]`, optional) : DataParser subject or sub-command list.
-- `execute` (overload 2) : receives typed `options` and optional typed `subject`.
+- `params.subjects` (`Argument[] | Command[]`, optional) : positional arguments list or sub-command list.
+- `execute` (overload 2) : receives typed `options` and optional typed `args`.
 
 ## Return value
 
@@ -72,6 +72,7 @@ function exec<
 ## See also
 
 - [`create`](/en/v0/api/command/create) - Builds a command node.
+- [`createArgument`](/en/v0/api/command/createArgument) - Builds positional arguments used in `subjects`.
 - [`createBooleanOption`](/en/v0/api/command/createBooleanOption) - Builds a boolean flag option.
 - [`createOption`](/en/v0/api/command/createOption) - Builds a single-value option.
 - [`createArrayOption`](/en/v0/api/command/createArrayOption) - Builds an array option.

docs/en/v0/api/command/index.md

@@ -11,7 +11,7 @@ next:
 
 # Command
 
-CLI command utilities to compose command trees, parse options/subjects, render help, and execute handlers.
+CLI command utilities to compose command trees, parse options/arguments, render help, and execute handlers.
 
 ## How to import?
 
@@ -34,7 +34,10 @@ only parses options from process arguments.
 ## Command builder
 
 ### [`create`](/en/v0/api/command/create)
-creates a command with optional description, options, and subject.
+creates a command with optional description, options, and subjects.
+
+### [`createArgument`](/en/v0/api/command/createArgument)
+creates a positional argument parser used in command `subjects`.
 
 ## Option builders
 

docs/en/v0/guide/command.md

@@ -17,10 +17,10 @@ The `command` feature helps you write CLIs that are simple to call and solid to
 A command is made of three parts:
 
 - options, such as `--port 3000` or `--verbose`;
-- a subject, meaning the positional arguments after options;
+- subjects, meaning either positional arguments after options, or subcommands;
 - a handler, called only when parsing succeeds.
 
-Options and subjects rely on `DataParser` from `@duplojs/utils`. This turns CLI input, which always starts as text, into typed domain values.
+Options and arguments rely on `DataParser` from `@duplojs/utils`. This turns CLI input, which always starts as text, into typed domain values.
 
 ## A First Command
 
@@ -29,7 +29,7 @@ Options and subjects rely on `DataParser` from `@duplojs/utils`. This turns CLI
 <!--@include: @/examples/v0/guide/command/firstCommand.ts-->
 ```
 
-Here, `exec` creates the root command. The `DP.tuple([DP.string(), DP.string()])` subject requires two positional arguments: the searched pattern and the file to inspect.
+Here, `exec` creates the root command. The `subjects` list declares two positional arguments (`pattern` and `filePath`), and parsed values are exposed as `args.pattern` and `args.filePath`.
 
 <TerminalBlock title="grep-like">
 <span class="terminal-line terminal-info">$ grep-like "TODO" ./src/index.ts --ignore-case</span>
@@ -53,7 +53,7 @@ The type of `options.type` becomes `"file" | "directory"`. If the received value
 
 ## Understand Errors
 
-When parsing fails, `exec` prints an interpreted error and exits with code `1`. The error shows the command, the failing option or subject, the received value, and what was expected.
+When parsing fails, `exec` prints an interpreted error and exits with code `1`. The error shows the command path, the failing option/argument, the received value, and what was expected.
 
 <TerminalBlock title="find-like">
 <span class="terminal-line terminal-info">$ find-like --type socket</span>
@@ -69,7 +69,7 @@ This is useful for internal tools: you can keep strict contracts without writing
 
 ## Subcommands
 
-For a CLI with several actions, create commands with `SC.create`, then pass them as the subject of a parent command.
+For a CLI with several actions, create commands with `SC.create`, then pass them as `subjects` of a parent command.
 
 ```ts twoslash
 // @version: 0
@@ -81,7 +81,7 @@ For a CLI with several actions, create commands with `SC.create`, then pass them
 install typescript without prompt
 </TerminalBlock>
 
-Each subcommand can have its own description, options, subject, and handler. Help follows the command tree.
+Each subcommand can have its own description, options, argument subjects, and handler. Help follows the command tree.
 
 ## Generated Help
 
@@ -90,23 +90,24 @@ Each subcommand can have its own description, options, subject, and handler. Hel
 <TerminalBlock title="apt-like">
 <span class="terminal-line terminal-info">$ apt-like --help</span>
 <span class="terminal-line"></span>
-<span class="terminal-line"><span class="terminal-key">NAME:</span>root</span>
+<span class="terminal-line"><span class="terminal-key">COMMAND:</span> root</span>
 <span class="terminal-line terminal-indent-1"><span class="terminal-key">DESCRIPTION:</span></span>
 <span class="terminal-line terminal-indent-1">Package manager</span>
-<span class="terminal-line terminal-indent-1"><span class="terminal-key">NAME:</span>install</span>
+<span class="terminal-line terminal-indent-1"><span class="terminal-key">COMMAND:</span> install</span>
 <span class="terminal-line terminal-indent-2"><span class="terminal-key">DESCRIPTION:</span></span>
 <span class="terminal-line terminal-indent-2">Install a package</span>
 <span class="terminal-line terminal-indent-2"><span class="terminal-key">OPTIONS:</span></span>
 <span class="terminal-line terminal-indent-2">- <span class="terminal-info">yes:</span> -y, --yes</span>
 <span class="terminal-line terminal-indent-3">Answer yes to prompts</span>
-<span class="terminal-line terminal-indent-2"><span class="terminal-key">SUBJECT:</span>&lt;string&gt;</span>
+<span class="terminal-line terminal-indent-2"><span class="terminal-key">ARGUMENTS:</span> &lt;packageName&gt;</span>
+<span class="terminal-line terminal-indent-2">- <span class="terminal-info">packageName:</span> string</span>
 </TerminalBlock>
 
 This makes command and option descriptions important: they become the embedded documentation of your tool.
 
 ## Lightweight Version With execOptions
 
-When your script has no subcommands and no positional subject, `execOptions` is enough. It only parses process options and returns a typed object.
+When your script has no subcommands and no positional argument, `execOptions` is enough. It only parses process options and returns a typed object.
 
 ```ts twoslash
 // @version: 0