@kjanat/dreamcli 3.0.1 → 4.0.0-rc.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (137) hide show
  1. package/CHANGELOG.md +962 -1
  2. package/README.md +7 -3
  3. package/dist/core/cli/builtins.d.mts +47 -0
  4. package/dist/core/cli/builtins.mjs +135 -0
  5. package/dist/core/cli/compiled.d.mts +29 -0
  6. package/dist/core/cli/compiled.mjs +76 -0
  7. package/dist/core/cli/dispatch.d.mts +9 -85
  8. package/dist/core/cli/help-links.d.mts +2 -14
  9. package/dist/core/cli/index.d.mts +282 -101
  10. package/dist/core/cli/index.mjs +497 -264
  11. package/dist/core/cli/planner.d.mts +13 -86
  12. package/dist/core/cli/planner.mjs +47 -30
  13. package/dist/core/cli/plugin.d.mts +1 -1
  14. package/dist/core/cli/propagate.mjs +1 -1
  15. package/dist/core/cli/reserved-flags.d.mts +1 -0
  16. package/dist/core/cli/reserved-flags.mjs +158 -0
  17. package/dist/core/cli/root-help.d.mts +1 -47
  18. package/dist/core/cli/root-help.mjs +37 -47
  19. package/dist/core/cli/root-output-flags.d.mts +1 -0
  20. package/dist/core/cli/root-output-flags.mjs +169 -0
  21. package/dist/core/cli/root-surface.d.mts +1 -68
  22. package/dist/core/cli/root-surface.mjs +2 -2
  23. package/dist/core/cli/runtime-preflight.d.mts +1 -199
  24. package/dist/core/cli/runtime-preflight.mjs +67 -17
  25. package/dist/core/completion/index.d.mts +2 -2
  26. package/dist/core/completion/shells/bash.d.mts +0 -1
  27. package/dist/core/completion/shells/bash.mjs +2 -1
  28. package/dist/core/completion/shells/fish.d.mts +0 -1
  29. package/dist/core/completion/shells/fish.mjs +2 -1
  30. package/dist/core/completion/shells/powershell.d.mts +0 -1
  31. package/dist/core/completion/shells/powershell.mjs +2 -1
  32. package/dist/core/completion/shells/shared.d.mts +3 -114
  33. package/dist/core/completion/shells/shared.mjs +9 -39
  34. package/dist/core/completion/shells/zsh.d.mts +0 -1
  35. package/dist/core/completion/shells/zsh.mjs +2 -1
  36. package/dist/core/config/index.d.mts +3 -3
  37. package/dist/core/config/index.mjs +2 -2
  38. package/dist/core/config/package-json.d.mts +2 -33
  39. package/dist/core/config/package-json.mjs +1 -34
  40. package/dist/core/errors/index.d.mts +7 -7
  41. package/dist/core/execution/index.d.mts +1 -48
  42. package/dist/core/execution/index.mjs +42 -27
  43. package/dist/core/help/ansi.d.mts +0 -11
  44. package/dist/core/help/index.d.mts +3 -35
  45. package/dist/core/help/index.mjs +29 -6
  46. package/dist/core/help/theme.d.mts +1 -21
  47. package/dist/core/json-schema/index.d.mts +279 -10
  48. package/dist/core/json-schema/index.mjs +482 -237
  49. package/dist/core/json-schema/meta-descriptions.generated.d.mts +79 -7
  50. package/dist/core/json-schema/meta-descriptions.generated.mjs +40 -6
  51. package/dist/core/output/activity.d.mts +1 -193
  52. package/dist/core/output/activity.mjs +1 -1
  53. package/dist/core/output/bind.d.mts +1 -37
  54. package/dist/core/output/contracts.d.mts +7 -13
  55. package/dist/core/output/contracts.mjs +1 -1
  56. package/dist/core/output/display-value.d.mts +1 -19
  57. package/dist/core/output/index.d.mts +5 -187
  58. package/dist/core/output/index.mjs +44 -9
  59. package/dist/core/output/renderers.d.mts +1 -45
  60. package/dist/core/output/writer.d.mts +0 -1
  61. package/dist/core/parse/index.d.mts +27 -5
  62. package/dist/core/parse/index.mjs +350 -227
  63. package/dist/core/parse/occurrences.d.mts +89 -0
  64. package/dist/core/parse/occurrences.mjs +114 -0
  65. package/dist/core/prompt/index.d.mts +3 -3
  66. package/dist/core/read-flags/index.d.mts +150 -0
  67. package/dist/core/read-flags/index.mjs +217 -0
  68. package/dist/core/resolve/args.d.mts +35 -4
  69. package/dist/core/resolve/args.mjs +132 -55
  70. package/dist/core/resolve/coerce.d.mts +66 -9
  71. package/dist/core/resolve/coerce.mjs +834 -270
  72. package/dist/core/resolve/config.d.mts +1 -10
  73. package/dist/core/resolve/contracts.d.mts +67 -44
  74. package/dist/core/resolve/errors.mjs +29 -21
  75. package/dist/core/resolve/flags.d.mts +36 -9
  76. package/dist/core/resolve/flags.mjs +129 -151
  77. package/dist/core/resolve/index.d.mts +8 -6
  78. package/dist/core/resolve/index.mjs +51 -18
  79. package/dist/core/resolve/path-checks.d.mts +47 -0
  80. package/dist/core/resolve/path-checks.mjs +102 -0
  81. package/dist/core/resolve/redaction.d.mts +12 -0
  82. package/dist/core/resolve/redaction.mjs +14 -0
  83. package/dist/core/resolve/stages.d.mts +85 -0
  84. package/dist/core/resolve/stages.mjs +170 -0
  85. package/dist/core/resolve/standard.d.mts +1 -24
  86. package/dist/core/resolve/standard.mjs +141 -43
  87. package/dist/core/schema/activity.d.mts +16 -16
  88. package/dist/core/schema/arg.d.mts +849 -71
  89. package/dist/core/schema/arg.mjs +727 -54
  90. package/dist/core/schema/brand.d.mts +17 -0
  91. package/dist/core/schema/cardinality.d.mts +301 -0
  92. package/dist/core/schema/cardinality.mjs +514 -0
  93. package/dist/core/schema/command.d.mts +173 -119
  94. package/dist/core/schema/command.mjs +305 -42
  95. package/dist/core/schema/flag.d.mts +515 -173
  96. package/dist/core/schema/flag.mjs +576 -78
  97. package/dist/core/schema/index.d.mts +11 -8
  98. package/dist/core/schema/index.mjs +10 -0
  99. package/dist/core/schema/middleware.d.mts +15 -12
  100. package/dist/core/schema/number-constraints.d.mts +5 -5
  101. package/dist/core/schema/prompt.d.mts +4 -4
  102. package/dist/core/schema/provenance.d.mts +99 -0
  103. package/dist/core/schema/provenance.mjs +28 -0
  104. package/dist/core/schema/run.d.mts +21 -60
  105. package/dist/core/schema/source.d.mts +179 -0
  106. package/dist/core/schema/source.mjs +206 -0
  107. package/dist/core/schema/standard.d.mts +12 -19
  108. package/dist/core/schema/stdin.d.mts +87 -0
  109. package/dist/core/schema/stdin.mjs +91 -0
  110. package/dist/core/schema/string-constraints.d.mts +16 -5
  111. package/dist/core/schema/string-constraints.mjs +18 -1
  112. package/dist/core/schema/value-parsers.d.mts +81 -9
  113. package/dist/core/schema/value-parsers.mjs +19 -1
  114. package/dist/core/schema/value.d.mts +242 -0
  115. package/dist/core/schema/value.mjs +573 -0
  116. package/dist/core/testkit/index.d.mts +30 -3
  117. package/dist/core/testkit/index.mjs +40 -26
  118. package/dist/index.d.mts +21 -16
  119. package/dist/index.mjs +10 -6
  120. package/dist/runtime/adapter.d.mts +3 -3
  121. package/dist/runtime/deno.d.mts +3 -3
  122. package/dist/runtime/detect.d.mts +2 -2
  123. package/dist/runtime/node.d.mts +3 -3
  124. package/dist/runtime/paths.d.mts +1 -31
  125. package/dist/runtime.d.mts +4 -4
  126. package/dist/strings.d.mts +1 -16
  127. package/dist/testkit.d.mts +2 -2
  128. package/dist/testkit.mjs +1 -1
  129. package/dist/version.d.mts +0 -13
  130. package/dist/version.mjs +2 -2
  131. package/dreamcli.schema.json +368 -78
  132. package/examples/interactive.ts +6 -5
  133. package/package.json +12 -11
  134. package/skills/cli-creation/SKILL.md +72 -16
  135. package/skills/cli-creation/references/pattern-cookbook.md +169 -11
  136. package/dist/core/resolve/property.d.mts +0 -51
  137. package/dist/core/resolve/property.mjs +0 -53
package/README.md CHANGED
@@ -34,19 +34,23 @@ cli('deploy').default(deploy).run();
34
34
 
35
35
  By the time `action` runs, `flags.region` is `"us" | "eu" | "ap"` — not `string | undefined`.
36
36
 
37
- The value is resolved through a documented chain: **CLI → env → config → interactive prompt →
38
- default**. Every step is opt-in. Every step preserves types.
37
+ The value is resolved through a documented chain: **CLI → stdin → env → config → interactive
38
+ prompt → default**. Every step is opt-in. Every step preserves types.
39
39
 
40
40
  ## Install
41
41
 
42
42
  ```bash
43
43
  npm install @kjanat/dreamcli
44
+ # Or alias the package for imports from 'dreamcli' and 'dreamcli/testkit':
45
+ npm install dreamcli@npm:@kjanat/dreamcli
44
46
  ```
45
47
 
46
48
  <details><summary>bun/deno</summary>
47
49
 
48
50
  ```bash
49
51
  bun add @kjanat/dreamcli
52
+ # Or use the same import alias with Bun:
53
+ bun add dreamcli@npm:@kjanat/dreamcli
50
54
  ```
51
55
 
52
56
  ```bash
@@ -245,7 +249,7 @@ Every flag supports: `.default()`, `.required()`, `.alias()`, `.env()`, `.config
245
249
  Each flag resolves through an ordered pipeline. Every step is opt-in:
246
250
 
247
251
  ```text
248
- CLI argv → environment variable → config file → interactive prompt → default value
252
+ CLI argv → piped stdin → environment variable → config file → interactive prompt → default value
249
253
  ```
250
254
 
251
255
  Required flags that don't resolve produce a structured error before the action handler runs. In
@@ -0,0 +1,47 @@
1
+ import { schemaBrand } from "../schema/brand.mjs";
2
+ //#region src/core/cli/builtins.d.ts
3
+ /** A built-in flag a consumer can take over. */
4
+ type BuiltinName = "help" | "json" | "quiet";
5
+ /** Whether the root keeps a built-in or releases it to commands. */
6
+ type BuiltinMode = "on" | "off";
7
+ /**
8
+ * Built-in flag settings accepted by {@linkcode CLIBuilder.builtins} and the
9
+ * `builtins` field of {@link CLIDefinition}.
10
+ *
11
+ * `version` and `completions` are absent by design: `.version()` and
12
+ * `.completions()` are opt-in, so a CLI declines those two by not calling them.
13
+ */
14
+ interface BuiltinsConfig {
15
+ /**
16
+ * Root `--help`/`-h`, command-level `--help`/`-h`, and the bare `help` token.
17
+ * @defaultValue `'on'`
18
+ */
19
+ readonly help?: BuiltinMode;
20
+ /**
21
+ * Root `--json`.
22
+ * @defaultValue `'on'`
23
+ */
24
+ readonly json?: BuiltinMode;
25
+ /**
26
+ * Root `--quiet`/`-q`.
27
+ * @defaultValue `'on'`
28
+ */
29
+ readonly quiet?: BuiltinMode;
30
+ }
31
+ /**
32
+ * Normalized built-in flag state stored on {@link CLISchema}.
33
+ *
34
+ * Sealed by {@link createCLISchema}; every key is present after normalization.
35
+ */
36
+ interface Builtins {
37
+ /** Type-only seal produced by {@link createCLISchema}. */
38
+ readonly [schemaBrand]: "builtins";
39
+ /** Whether the root owns `--help`/`-h` and the bare `help` token. */
40
+ readonly help: BuiltinMode;
41
+ /** Whether the root owns `--json`. */
42
+ readonly json: BuiltinMode;
43
+ /** Whether the root owns `--quiet`/`-q`. */
44
+ readonly quiet: BuiltinMode;
45
+ }
46
+ //#endregion
47
+ export type { BuiltinMode, BuiltinName, Builtins, BuiltinsConfig };
@@ -0,0 +1,135 @@
1
+ import { CLIError } from "../errors/index.mjs";
2
+ //#region src/core/cli/builtins.ts
3
+ /**
4
+ * Consumer-owned built-in flags: `--help`/`-h`, `--json`, and `--quiet`/`-q`.
5
+ *
6
+ * The root owns these tokens by default. {@linkcode CLIBuilder.builtins} sets a
7
+ * built-in to `'off'`, which releases every spelling it answers to: the root
8
+ * scanner stops reading and stripping it, root help stops advertising it, and
9
+ * the `RESERVED_FLAG` guard stops reserving it, so a command may declare the
10
+ * flag and receive it (#86).
11
+ *
12
+ * This module is the single spelling table behind all three layers. A token
13
+ * added here reaches the scanner, the guard, and the help block in one change.
14
+ *
15
+ * @module dreamcli/core/cli/builtins
16
+ * @internal
17
+ */
18
+ /**
19
+ * The spelling table every built-in-aware layer reads.
20
+ *
21
+ * @internal
22
+ */
23
+ const BUILTIN_SPECS = {
24
+ help: {
25
+ long: ["--help"],
26
+ short: ["-h"],
27
+ description: "Show this help message and exit"
28
+ },
29
+ json: {
30
+ long: ["--json"],
31
+ short: [],
32
+ description: "Emit machine-readable JSON output"
33
+ },
34
+ quiet: {
35
+ long: ["--quiet"],
36
+ short: ["-q"],
37
+ description: "Suppress informational output"
38
+ }
39
+ };
40
+ /** Spelling error messages and help entries name a built-in by. @internal */
41
+ function builtinSpelling(name) {
42
+ return BUILTIN_SPECS[name].long[0] ?? BUILTIN_SPECS[name].short[0] ?? name;
43
+ }
44
+ /** Built-in names in the order root help advertises them. @internal */
45
+ const BUILTIN_NAMES = [
46
+ "help",
47
+ "json",
48
+ "quiet"
49
+ ];
50
+ /** Every built-in on, the state a CLI starts in. @internal */
51
+ const DEFAULT_BUILTINS = {
52
+ help: "on",
53
+ json: "on",
54
+ quiet: "on"
55
+ };
56
+ /**
57
+ * Whether the root still owns a built-in.
58
+ *
59
+ * @param builtins - Normalized state, or `undefined` for the defaults.
60
+ * @param name - Built-in to check.
61
+ * @returns `true` when the root reads the token, `false` once it is released.
62
+ *
63
+ * @internal
64
+ */
65
+ function builtinEnabled(builtins, name) {
66
+ return (builtins?.[name] ?? "on") === "on";
67
+ }
68
+ /**
69
+ * The argv spellings of one built-in, joined for a help entry.
70
+ *
71
+ * @param name - Built-in to render.
72
+ * @returns Short spellings first, e.g. `-h, --help`.
73
+ *
74
+ * @internal
75
+ */
76
+ function builtinFlagForms(name) {
77
+ const spec = BUILTIN_SPECS[name];
78
+ return [...spec.short, ...spec.long].join(", ");
79
+ }
80
+ /**
81
+ * The spellings of one built-in as bare tokens, dashes removed.
82
+ *
83
+ * @param name - Built-in to read.
84
+ * @returns Tokens as a command flag would declare them, e.g. `help` and `h`.
85
+ *
86
+ * @internal
87
+ */
88
+ function builtinTokens(name) {
89
+ const spec = BUILTIN_SPECS[name];
90
+ return [...spec.long, ...spec.short].map((spelling) => spelling.replace(/^-+/, ""));
91
+ }
92
+ /**
93
+ * Read one built-in's mode out of a caller-supplied config.
94
+ *
95
+ * @param config - Caller input, which a JS caller may fill with anything.
96
+ * @param name - Built-in to read.
97
+ * @returns The declared mode, or `'on'` when the key is absent.
98
+ * @throws {@linkcode CLIError} `INVALID_SCHEMA` when the value is neither mode.
99
+ */
100
+ function readBuiltinMode(config, name) {
101
+ const mode = config[name];
102
+ if (mode === void 0 || mode === "on" || mode === "off") return mode ?? "on";
103
+ throw new CLIError(`Built-in '${name}' must be 'on' or 'off'`, {
104
+ code: "INVALID_SCHEMA",
105
+ details: {
106
+ builtin: name,
107
+ value: mode
108
+ },
109
+ suggest: `Pass { ${name}: 'off' } to release the flag, or omit the key to keep it on`
110
+ });
111
+ }
112
+ /**
113
+ * Normalize built-in settings into the fully populated schema state.
114
+ *
115
+ * Shared by {@link createCLISchema} and {@linkcode CLIBuilder.builtins}, so both
116
+ * construction paths produce identical state. Re-feeding a normalized value
117
+ * returns an equal value.
118
+ *
119
+ * @param config - Caller-supplied settings, or `undefined` for the defaults.
120
+ * @returns Every built-in resolved to a mode.
121
+ * @throws {@linkcode CLIError} `INVALID_SCHEMA` for a value that is neither
122
+ * `'on'` nor `'off'`.
123
+ *
124
+ * @internal
125
+ */
126
+ function normalizeBuiltins(config) {
127
+ if (config === void 0) return DEFAULT_BUILTINS;
128
+ return {
129
+ help: readBuiltinMode(config, "help"),
130
+ json: readBuiltinMode(config, "json"),
131
+ quiet: readBuiltinMode(config, "quiet")
132
+ };
133
+ }
134
+ //#endregion
135
+ export { BUILTIN_NAMES, BUILTIN_SPECS, DEFAULT_BUILTINS, builtinEnabled, builtinFlagForms, builtinSpelling, builtinTokens, normalizeBuiltins };
@@ -0,0 +1,29 @@
1
+ import { CommandSchema, ErasedActionHandler, ExecutionStep } from "../schema/command.mjs";
2
+ import { CLIPlugin } from "./plugin.mjs";
3
+ //#region src/core/cli/compiled.d.ts
4
+ /**
5
+ * Executable form of one registered command.
6
+ */
7
+ interface CompiledCommand {
8
+ /** The very {@linkcode CommandSchema} object the public schema tree holds. */
9
+ readonly schema: CommandSchema;
10
+ /** Action handler, `undefined` for commands that only group subcommands. */
11
+ readonly handler: ErasedActionHandler | undefined;
12
+ /** Derive and middleware steps in registration order. */
13
+ readonly steps: readonly ExecutionStep[];
14
+ /** Nested subcommands, keyed by name and by every alias. */
15
+ readonly subcommands: ReadonlyMap<string, CompiledCommand>;
16
+ }
17
+ /**
18
+ * Executable state of a CLI program.
19
+ */
20
+ interface CompiledCLI {
21
+ /** Top-level commands in registration order. */
22
+ readonly commands: readonly CompiledCommand[];
23
+ /** The default command, `undefined` when none is registered. */
24
+ readonly defaultCommand: CompiledCommand | undefined;
25
+ /** Plugins in registration order. */
26
+ readonly plugins: readonly CLIPlugin[];
27
+ }
28
+ //#endregion
29
+ export type { CompiledCLI, CompiledCommand };
@@ -0,0 +1,76 @@
1
+ import { CLIError } from "../errors/index.mjs";
2
+ //#region src/core/cli/compiled.ts
3
+ /**
4
+ * Compiled execution graph behind a CLI program.
5
+ *
6
+ * {@linkcode CLISchema} describes the program; the compiled graph carries the
7
+ * executable half — action handlers, execution steps, and the route-indexed
8
+ * subcommand tree — and is reachable only through the module-private state in
9
+ * `cli/index.ts`.
10
+ *
11
+ * @module dreamcli/core/cli/compiled
12
+ */
13
+ /**
14
+ * The routes a command answers to: its name followed by its aliases.
15
+ *
16
+ * @param schema - Command schema to read the name and aliases from.
17
+ * @returns Route tokens in declaration order.
18
+ *
19
+ * @internal
20
+ */
21
+ function commandRoutes(schema) {
22
+ return [schema.name, ...schema.aliases];
23
+ }
24
+ /**
25
+ * Reject a route already claimed by a sibling command, then record its owner.
26
+ *
27
+ * @param parentCommandName - Name of the command the siblings live under.
28
+ * @param routeOwners - Route to owning command name, mutated with `route`.
29
+ * @param route - Name or alias being registered.
30
+ * @param commandName - Command claiming the route.
31
+ *
32
+ * @internal
33
+ */
34
+ function assertNoSiblingRouteConflict(parentCommandName, routeOwners, route, commandName) {
35
+ const owner = routeOwners.get(route);
36
+ if (owner !== void 0) {
37
+ const selfCollision = owner === commandName;
38
+ throw new CLIError(selfCollision ? `Command '${commandName}' reuses route '${route}' under '${parentCommandName}'` : `Duplicate command route '${route}' under '${parentCommandName}' (${owner} and ${commandName})`, {
39
+ code: "DUPLICATE_COMMAND",
40
+ suggest: selfCollision ? `Remove route '${route}' from the aliases of '${commandName}'` : "Ensure sibling command names and aliases are unique"
41
+ });
42
+ }
43
+ routeOwners.set(route, commandName);
44
+ }
45
+ /**
46
+ * Compile a command builder into its executable graph node.
47
+ *
48
+ * Extracts the handler and execution steps, then recurses into
49
+ * `_subcommands` to index each child by name and alias. The builder itself is
50
+ * not retained; `schema` is the builder's own schema object, so the compiled
51
+ * node and the public schema tree share command schema identity.
52
+ *
53
+ * @param cmd - Command builder to compile.
54
+ * @returns The compiled command node.
55
+ * @throws {@linkcode CLIError} `DUPLICATE_COMMAND` when two siblings claim the same route.
56
+ *
57
+ * @internal
58
+ */
59
+ function compileCommand(cmd) {
60
+ const subcommands = /* @__PURE__ */ new Map();
61
+ const routeOwners = /* @__PURE__ */ new Map();
62
+ for (const sub of cmd._subcommands) {
63
+ const routes = commandRoutes(sub.schema);
64
+ for (const route of routes) assertNoSiblingRouteConflict(cmd.schema.name, routeOwners, route, sub.schema.name);
65
+ const compiled = compileCommand(sub);
66
+ for (const route of routes) subcommands.set(route, compiled);
67
+ }
68
+ return {
69
+ schema: cmd.schema,
70
+ handler: cmd.handler,
71
+ steps: cmd._executionSteps,
72
+ subcommands
73
+ };
74
+ }
75
+ //#endregion
76
+ export { assertNoSiblingRouteConflict, commandRoutes, compileCommand };
@@ -1,20 +1,12 @@
1
- import { CommandSchema, ErasedCommand } from "../schema/command.mjs";
2
- import { FlagLookupEntry, ParseOptions } from "../parse/index.mjs";
1
+ import { CommandSchema } from "../schema/command.mjs";
2
+ import { CompiledCommand } from "./compiled.mjs";
3
3
  //#region src/core/cli/dispatch.d.ts
4
- /**
5
- * Flag lookup (spelling → {@link FlagLookupEntry}) used to make the
6
- * command-name scan aware of value-flag arity. Built from the flags valid at
7
- * the current dispatch level via {@link buildFlagLookup}.
8
- *
9
- * @internal
10
- */
11
- type ValueFlagLookup = ReadonlyMap<string, FlagLookupEntry>;
12
4
  /** Successful dispatch — target command found with argv path. */
13
5
  interface DispatchMatch {
14
6
  /** Discriminant — a command name in argv matched a registered command. */
15
- readonly kind: 'match';
7
+ readonly kind: "match";
16
8
  /** The matched (target) command. */
17
- readonly command: ErasedCommand;
9
+ readonly command: CompiledCommand;
18
10
  /** Root → target (inclusive). Used for `collectPropagatedFlags()`. */
19
11
  readonly commandPath: readonly CommandSchema[];
20
12
  /** argv after consuming command name segments. */
@@ -23,92 +15,24 @@ interface DispatchMatch {
23
15
  /** Target has subcommands but no handler and no subcommand was specified/matched. */
24
16
  interface DispatchNeedsSubcommand {
25
17
  /** Discriminant — command group reached without a subcommand or handler. */
26
- readonly kind: 'needs-subcommand';
18
+ readonly kind: "needs-subcommand";
27
19
  /** The group command that needs a subcommand. */
28
- readonly command: ErasedCommand;
20
+ readonly command: CompiledCommand;
29
21
  /** Root → group (inclusive). */
30
22
  readonly commandPath: readonly CommandSchema[];
31
23
  }
32
24
  /** Unknown command name at this dispatch level. */
33
25
  interface DispatchUnknown {
34
26
  /** Discriminant — no registered command matched the input token. */
35
- readonly kind: 'unknown';
27
+ readonly kind: "unknown";
36
28
  /** The unrecognised input token. Empty string when no token present. */
37
29
  readonly input: string;
38
30
  /** Commands available at the level where matching failed. */
39
- readonly candidates: readonly ErasedCommand[];
31
+ readonly candidates: readonly CompiledCommand[];
40
32
  /** Ancestor path up to (but not including) the unknown level. */
41
33
  readonly parentPath: readonly CommandSchema[];
42
34
  }
43
35
  /** Discriminated result of recursive command dispatch. */
44
36
  type DispatchResult = DispatchMatch | DispatchNeedsSubcommand | DispatchUnknown;
45
- /**
46
- * Recursively walk argv, consuming command name segments from the front.
47
- *
48
- * At each level, the first non-flag token is tested as a command name
49
- * against the provided command map. If matched and the matched command
50
- * has subcommands, dispatch recurses into the child level with the
51
- * remaining argv.
52
- *
53
- * Ambiguity resolution for commands that have both an action handler AND
54
- * subcommands (e.g. `git remote` lists remotes, `git remote add` dispatches):
55
- * - If the next token matches a subcommand → descend
56
- * - If the next token is unknown and the command has a handler → match here
57
- * - If the next token is unknown and no handler → propagate unknown error
58
- * - If no next token and command has a handler → match here
59
- * - If no next token and no handler → needs-subcommand
60
- *
61
- * @param argv - Remaining argv tokens (command names + flags + args).
62
- * @param commands - Command map at the current tree level.
63
- * @param ancestorPath - Schema path from root to current level (exclusive).
64
- * @param valueFlags - Lookup of flags valid at this level, used so a
65
- * space-separated value-flag's value (`--region eu`) is not mistaken for a
66
- * command name. Empty by default (arity-unaware, legacy behaviour).
67
- * @param parseOptions - Parser toggles (case parity) applied to descent-level
68
- * flag lookups built inside dispatch.
69
- * @returns Discriminated dispatch result.
70
- *
71
- * @internal
72
- */
73
- declare function dispatch(argv: readonly string[], commands: ReadonlyMap<string, ErasedCommand>, ancestorPath?: readonly CommandSchema[], valueFlags?: ValueFlagLookup, parseOptions?: ParseOptions): DispatchResult;
74
- /**
75
- * Whether a flag token consumes the following argv token as its value.
76
- *
77
- * Mirrors the parser's value-consumption rules (`parseLongFlag` /
78
- * `parseShortFlags`) so the command-name scan skips exactly the tokens the
79
- * parser would treat as flag values:
80
- * - `--flag value` → consumes when `--flag` is a known value-flag.
81
- * - `--flag=value` → self-contained, consumes nothing.
82
- * - `-abc value` → consumes only when the trailing short flag is a value-flag;
83
- * an earlier value-flag char takes the rest of the group as an inline value.
84
- *
85
- * Unknown flags conservatively consume nothing (the parser reports them later).
86
- *
87
- * @internal
88
- */
89
- declare function consumesFollowingToken(token: string, valueFlags: ValueFlagLookup): boolean;
90
- /**
91
- * Levenshtein distance between two strings.
92
- * @internal
93
- */
94
- declare function levenshtein(a: string, b: string): number;
95
- /**
96
- * Find the closest command name match for a "did you mean?" suggestion.
97
- *
98
- * Searches command names and aliases. Returns `undefined` if no
99
- * sufficiently close match exists (threshold: 3).
100
- *
101
- * @internal
102
- */
103
- declare function findClosestCommand(input: string, commands: readonly ErasedCommand[]): string | undefined;
104
- /**
105
- * Deduplicate commands from a name+alias map.
106
- *
107
- * A map keyed by name *and* alias contains duplicate entries for aliased
108
- * commands. This returns unique commands (by schema identity).
109
- *
110
- * @internal
111
- */
112
- declare function uniqueCommands(commands: ReadonlyMap<string, ErasedCommand>): readonly ErasedCommand[];
113
37
  //#endregion
114
- export { type DispatchMatch, type DispatchNeedsSubcommand, type DispatchResult, type DispatchUnknown, type ValueFlagLookup, consumesFollowingToken, dispatch, findClosestCommand, levenshtein, uniqueCommands };
38
+ export type { DispatchMatch, DispatchNeedsSubcommand, DispatchResult, DispatchUnknown };
@@ -1,10 +1,9 @@
1
- import { PackageJsonData } from "../config/package-json.mjs";
2
1
  //#region src/core/cli/help-links.d.ts
3
2
  /**
4
3
  * OSC 8 hyperlink targets for the root-help header.
5
4
  *
6
5
  * Set via `CLIBuilder.links()`; fields left `undefined` are derived from
7
- * package.json metadata when `.packageJson()` is active.
6
+ * manifest metadata when `.manifest()` is active.
8
7
  */
9
8
  interface HelpLinks {
10
9
  /** URL the program name links to (e.g. the repository or homepage). */
@@ -12,16 +11,5 @@ interface HelpLinks {
12
11
  /** URL the version links to (e.g. the release tag). */
13
12
  readonly version: string | undefined;
14
13
  }
15
- /**
16
- * Fill `undefined` link fields from package.json metadata.
17
- *
18
- * Explicit URLs always win. The name falls back to the normalized
19
- * `repository` URL, then `homepage`; the version falls back to the forge
20
- * release-tag URL when both a repository and a version are known.
21
- * Idempotent — already-resolved fields pass through unchanged.
22
- *
23
- * @internal
24
- */
25
- declare function deriveHelpLinks(links: HelpLinks | undefined, pkg: PackageJsonData | undefined, version: string | undefined): HelpLinks | undefined;
26
14
  //#endregion
27
- export { type HelpLinks, deriveHelpLinks };
15
+ export type { HelpLinks };