Merge branch 'main' into copilot/add-auto-completion-support

Author: crypto-vincent

docs/guide/02_commands.md

@@ -87,7 +87,7 @@ const authenticatedDeploy = commandChained(
           long: "token",
           type: type("secret"),
           description: "API token",
-          defaultIfNotSpecified: function () {
+          fallbackValueIfAbsent: function () {
             const t = process.env.API_TOKEN;
             if (!t) throw new Error("API_TOKEN env var is required");
             return t;

docs/guide/03_options.md

@@ -44,24 +44,24 @@ const output = optionSingleValue({
   short: "o",
   type: typePath(),
   description: "Output directory",
-  defaultIfNotSpecified: () => "dist/",
+  fallbackValueIfAbsent: () => "dist/",
 });
 // --output dist/   →  "dist/"
 // --output=dist/   →  "dist/"
 // -o dist/         →  "dist/"
 // (absent)         →  "dist/"
 ```
 
-| Parameter               | Type                  | Description                                                                  |
-| ----------------------- | --------------------- | ---------------------------------------------------------------------------- |
-| `long`                  | `string`              | Long option name                                                             |
-| `short`                 | `string?`             | Short option name                                                            |
-| `type`                  | `Type<Value>`         | Decoder for the value                                                        |
-| `description`           | `string?`             | Help text                                                                    |
-| `hint`                  | `string?`             | Short note in parentheses                                                    |
-| `defaultIfNotSpecified` | `() => Value`         | Value when option is absent — **throw** to make it required                  |
-| `valueIfNothingInlined` | `() => Value?`        | Value when option is present but has no inline value (e.g. `--output` alone) |
-| `aliases`               | `{ longs?, shorts? }` | Additional names                                                             |
+| Parameter                  | Type                  | Description                                                                  |
+| -------------------------- | --------------------- | ---------------------------------------------------------------------------- |
+| `long`                     | `string`              | Long option name                                                             |
+| `short`                    | `string?`             | Short option name                                                            |
+| `type`                     | `Type<Value>`         | Decoder for the value                                                        |
+| `description`              | `string?`             | Help text                                                                    |
+| `hint`                     | `string?`             | Short note in parentheses                                                    |
+| `fallbackValueIfAbsent`    | `() => Value`         | Value when option is absent — **throw** to make it required                  |
+| `impliedValueIfNotInlined` | `() => Value?`        | Value when option is present but has no inline value (e.g. `--output` alone) |
+| `aliases`                  | `{ longs?, shorts? }` | Additional names                                                             |
 
 ## `optionRepeatable` — collect multiple values
 

docs/guide/06_run_as_cli.md

@@ -68,7 +68,7 @@ const rootCmd = commandWithSubcommands(
           long: "db",
           type: typeUrl(),
           description: "Database URL",
-          defaultIfNotSpecified: () => new URL("postgres://localhost/mydb"),
+          fallbackValueIfAbsent: () => new URL("postgres://localhost/mydb"),
         }),
       },
       positionals: [],

src/lib/Command.ts

@@ -146,12 +146,11 @@ export function command<Context, Result>(
         const operationDecoder = operation.consumeAndMakeDecoder(readerArgs);
         const endPositional = readerArgs.consumePositional();
         if (endPositional !== undefined) {
-          throw new TypoError(
-            new TypoText(
-              new TypoString(`Unexpected argument: `),
-              new TypoString(`"${endPositional}"`, typoStyleQuote),
-            ),
-          );
+          const errorText = new TypoText();
+          errorText.push(new TypoString(`Unexpected argument: `));
+          errorText.push(new TypoString(`"${endPositional}"`, typoStyleQuote));
+          errorText.push(new TypoString(`.`));
+          throw new TypoError(errorText);
         }
         return {
           generateUsage: () => generateUsageLeaf(information, operation),
@@ -376,9 +375,7 @@ function generateUsageLeaf(
 ): UsageCommand {
   const { positionals, options } = operation.generateUsage();
   return {
-    segments: positionals.map((positional) => ({
-      positional: positional.label,
-    })),
+    segments: positionals.map((p) => ({ positional: p.label })),
     information,
     positionals,
     subcommands: [],