@kjanat/dreamcli 3.0.1 → 4.0.0-rc.1

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 +951 -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 +181 -112
  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 +28 -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 +9 -9
  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
@@ -1,9 +1,13 @@
1
1
  import { CLIError, ParseError } from "../errors/index.mjs";
2
- import { includesBeforeSeparator, parse } from "../parse/index.mjs";
2
+ import { invocationSelectsStdin } from "../schema/source.mjs";
3
+ import { parse } from "../parse/index.mjs";
4
+ import { builtinEnabled } from "./builtins.mjs";
3
5
  import { createTerminalPrompter } from "../prompt/index.mjs";
4
6
  import { discoverManifest, inferCliName } from "../config/package-json.mjs";
5
7
  import { deriveHelpLinks } from "./help-links.mjs";
8
+ import { readRootOutputFlags, resolveRootJsonMode, resolveRootVerbosity } from "./root-output-flags.mjs";
6
9
  import { planInvocation } from "./planner.mjs";
10
+ import { assertNoReservedFlagCollisions } from "./reserved-flags.mjs";
7
11
  import { discoverConfig } from "../config/index.mjs";
8
12
  //#region src/core/cli/runtime-preflight.ts
9
13
  const PRECHECK_OUTPUT = {
@@ -48,30 +52,41 @@ function extractConfigFlag(argv) {
48
52
  filteredArgv
49
53
  };
50
54
  }
51
- /** Check whether a single command's args declare stdin-mode and argv leaves them unresolved. @internal */
52
- function commandInvocationNeedsStdin(schema, argv, flagSettings) {
53
- if (argv.includes("--help") || argv.includes("-h")) return false;
55
+ /**
56
+ * Check whether this invocation will actually select a stdin source.
57
+ *
58
+ * A `'dash'` binding is eligible when its token is `-`. A `'missing'` binding is
59
+ * eligible when argv left the input absent; env, config, prompt, and default do
60
+ * not suppress the read, because the stdin fallback outranks all four.
61
+ *
62
+ * @param schema - The matched command's merged schema.
63
+ * @param argv - The command's own argv slice.
64
+ * @param flagSettings - Parser behavior settings.
65
+ * @param builtins - Which built-in flags the root still owns.
66
+ * @returns `true` when at least one input would read stdin.
67
+ * @internal
68
+ */
69
+ function commandInvocationNeedsStdin(schema, argv, flagSettings, builtins) {
70
+ if (builtinEnabled(builtins, "help") && (argv.includes("--help") || argv.includes("-h"))) return false;
54
71
  try {
55
72
  const parsed = parse(schema, argv, flagSettings);
56
- return schema.args.some(({ name, schema: argSchema }) => {
57
- const parsedValue = parsed.args[name];
58
- return argSchema.stdinMode && (parsedValue === void 0 || parsedValue === "-");
59
- });
73
+ return invocationSelectsStdin(schema.flags, schema.args, parsed);
60
74
  } catch (error) {
61
75
  if (error instanceof ParseError) return false;
62
76
  throw error;
63
77
  }
64
78
  }
65
79
  /** Plan the invocation and check whether the matched command needs stdin data. @internal */
66
- function invocationNeedsStdin(schema, argv) {
80
+ function invocationNeedsStdin(schema, compiled, argv) {
67
81
  const plan = planInvocation({
68
82
  schema,
83
+ compiled,
69
84
  argv,
70
85
  help: { binName: schema.name },
71
86
  output: PRECHECK_OUTPUT
72
87
  });
73
88
  switch (plan.kind) {
74
- case "match": return commandInvocationNeedsStdin(plan.plan.mergedSchema, plan.plan.argv, schema.flagSettings);
89
+ case "match": return commandInvocationNeedsStdin(plan.plan.mergedSchema, plan.plan.argv, schema.flagSettings, schema.builtins);
75
90
  case "dispatch-error":
76
91
  case "needs-subcommand":
77
92
  case "root-help":
@@ -79,10 +94,11 @@ function invocationNeedsStdin(schema, argv) {
79
94
  case "root-completions": return false;
80
95
  }
81
96
  }
82
- function isCompletionsInvocation(schema, argv) {
97
+ function isCompletionsInvocation(schema, compiled, argv) {
83
98
  if (!schema.hasBuiltInCompletions) return false;
84
99
  const plan = planInvocation({
85
100
  schema,
101
+ compiled,
86
102
  argv,
87
103
  help: { binName: schema.name },
88
104
  output: PRECHECK_OUTPUT
@@ -111,6 +127,33 @@ async function applyPackageJsonDiscovery(schema, adapter, inheritedName, isCompl
111
127
  name: inheritedName
112
128
  } : packageSchema;
113
129
  }
130
+ /**
131
+ * Re-run the `RESERVED_FLAG` guard when discovery supplied the version.
132
+ *
133
+ * `.manifest()` reads a version off the filesystem at `.run()` time, past every
134
+ * build-time check, so a command flag spelling `--version` or `-V` as a name, an
135
+ * alias, or a negated spelling would become unreachable without ever being
136
+ * rejected. Running the same guard here fails the startup with the identical
137
+ * error the build paths raise (#86), rendered like every other startup failure
138
+ * rather than thrown at the caller.
139
+ *
140
+ * @param discovered - Schema after manifest discovery merged its metadata in.
141
+ * @param declared - Schema as the builder had it before discovery.
142
+ * @param compiled - Compiled graph carrying every registered command schema.
143
+ * @returns The `RESERVED_FLAG` error for the first collision, or `undefined`.
144
+ *
145
+ * @internal
146
+ */
147
+ function discoveredVersionCollision(discovered, declared, compiled) {
148
+ if (discovered.version === declared.version) return void 0;
149
+ try {
150
+ assertNoReservedFlagCollisions(discovered.version, [compiled.defaultCommand?.schema, ...compiled.commands.map((command) => command.schema)], discovered.builtins);
151
+ return;
152
+ } catch (error) {
153
+ if (error instanceof CLIError) return error;
154
+ throw error;
155
+ }
156
+ }
114
157
  async function loadRuntimeConfig(schema, adapter, configPath, isCompletions, existingConfig) {
115
158
  if (schema.configSettings === void 0 || isCompletions || existingConfig !== void 0) return existingConfig;
116
159
  try {
@@ -138,18 +181,25 @@ async function prepareRuntimePreflight(options) {
138
181
  configPath: void 0,
139
182
  filteredArgv: rawArgv
140
183
  };
141
- const jsonMode = includesBeforeSeparator(filteredArgv, "--json") || options.options?.jsonMode === true;
142
- const hasQuietFlag = includesBeforeSeparator(filteredArgv, "--quiet") || includesBeforeSeparator(filteredArgv, "-q");
143
- const isCompletions = isCompletionsInvocation(options.schema, filteredArgv);
184
+ const rootOutputFlags = readRootOutputFlags(filteredArgv, options.schema.builtins);
185
+ const jsonMode = resolveRootJsonMode(rootOutputFlags, options.options?.jsonMode);
186
+ const verbosity = resolveRootVerbosity(rootOutputFlags, options.options?.verbosity) ?? "normal";
187
+ const isCompletions = isCompletionsInvocation(options.schema, options.compiled, filteredArgv);
144
188
  const schema = await applyPackageJsonDiscovery(options.schema, options.adapter, options.inheritedName, isCompletions);
189
+ const versionCollision = discoveredVersionCollision(schema, options.schema, options.compiled);
190
+ if (versionCollision !== void 0) return {
191
+ kind: "startup-error",
192
+ error: versionCollision,
193
+ jsonMode
194
+ };
145
195
  const loadedConfig = await loadRuntimeConfig(schema, options.adapter, configPath, isCompletions, options.options?.config);
146
196
  if (loadedConfig instanceof CLIError) return {
147
- kind: "config-error",
197
+ kind: "startup-error",
148
198
  error: loadedConfig,
149
199
  jsonMode
150
200
  };
151
201
  const autoPrompter = options.options?.prompter === void 0 && options.adapter.stdinIsTTY ? createTerminalPrompter(options.adapter.stdin, options.adapter.stderr) : void 0;
152
- const stdinData = options.options?.stdinData === void 0 && invocationNeedsStdin(schema, filteredArgv) ? await options.adapter.readStdin() : options.options?.stdinData;
202
+ const stdinData = options.options?.stdinData === void 0 && invocationNeedsStdin(schema, options.compiled, filteredArgv) ? await options.adapter.readStdin() : options.options?.stdinData;
153
203
  return {
154
204
  kind: "ready",
155
205
  schema,
@@ -158,7 +208,7 @@ async function prepareRuntimePreflight(options) {
158
208
  env: options.options?.env ?? options.adapter.env,
159
209
  isTTY: options.options?.isTTY ?? options.adapter.isTTY,
160
210
  jsonMode,
161
- verbosity: hasQuietFlag ? "quiet" : options.options?.verbosity ?? "normal",
211
+ verbosity,
162
212
  stat: options.options?.stat ?? options.adapter.stat,
163
213
  mkdir: options.options?.mkdir ?? options.adapter.mkdir,
164
214
  ...stdinData !== void 0 ? { stdinData } : {},
@@ -10,7 +10,7 @@ import { CLISchema } from "../cli/index.mjs";
10
10
  *
11
11
  * `bash`, `zsh`, `fish`, and `powershell` are implemented today.
12
12
  */
13
- type Shell = 'bash' | 'zsh' | 'fish' | 'powershell';
13
+ type Shell = "bash" | "zsh" | "fish" | "powershell";
14
14
  /**
15
15
  * Implemented shell values as a frozen readonly non-empty tuple.
16
16
  *
@@ -20,7 +20,7 @@ type Shell = 'bash' | 'zsh' | 'fish' | 'powershell';
20
20
  *
21
21
  * @see {@link Shell} for the union type matching these entries.
22
22
  */
23
- declare const SHELLS: Readonly<readonly ['bash', 'zsh', 'fish', 'powershell']>;
23
+ declare const SHELLS: Readonly<readonly ["bash", "zsh", "fish", "powershell"]>;
24
24
  /**
25
25
  * Normalize a raw shell token — a bare name (`zsh`), a `$SHELL` path
26
26
  * (`/bin/zsh`), or a Windows executable (`…\pwsh.exe`) — to a supported
@@ -1,5 +1,4 @@
1
1
  import { CompletionOptions } from "./shared.mjs";
2
- import { CLISchema } from "../../cli/index.mjs";
3
2
  //#region src/core/completion/shells/bash.d.ts
4
3
  /**
5
4
  * Generate a bash completion script for the CLI.
@@ -20,7 +20,8 @@ import { getVisibleNegatedName, quoteShellArg, resolveRootCompletionSurface, san
20
20
  * ```
21
21
  */
22
22
  function generateBashCompletion(schema, options) {
23
- const funcName = `_${sanitizeShellIdentifier(options?.functionPrefix ?? schema.name)}_completions`;
23
+ const prefix = options?.functionPrefix ?? schema.name;
24
+ const funcName = `_${sanitizeShellIdentifier(prefix)}_completions`;
24
25
  const rootSurface = resolveRootCompletionSurface(schema, options?.rootMode);
25
26
  const visibleCommands = rootSurface.visibleCommands;
26
27
  const nodes = walkCommandTree(visibleCommands);
@@ -1,5 +1,4 @@
1
1
  import { CompletionOptions } from "./shared.mjs";
2
- import { CLISchema } from "../../cli/index.mjs";
3
2
  //#region src/core/completion/shells/fish.d.ts
4
3
  /**
5
4
  * Generate a fish completion script for the CLI.
@@ -16,7 +16,8 @@ import { getVisibleNegatedName, quoteShellArg, resolveRootCompletionSurface, san
16
16
  * ```
17
17
  */
18
18
  function generateFishCompletion(schema, options) {
19
- const helperPrefix = `__${sanitizeShellIdentifier(options?.functionPrefix ?? schema.name)}_completions`;
19
+ const prefix = options?.functionPrefix ?? schema.name;
20
+ const helperPrefix = `__${sanitizeShellIdentifier(prefix)}_completions`;
20
21
  const pathFuncName = `${helperPrefix}_path`;
21
22
  const pathIsFuncName = `${helperPrefix}_path_is`;
22
23
  const rootSurface = resolveRootCompletionSurface(schema, options?.rootMode);
@@ -1,5 +1,4 @@
1
1
  import { CompletionOptions } from "./shared.mjs";
2
- import { CLISchema } from "../../cli/index.mjs";
3
2
  //#region src/core/completion/shells/powershell.d.ts
4
3
  /**
5
4
  * Generate a PowerShell completion script for the CLI.
@@ -10,7 +10,8 @@ import { getVisibleNegatedName, resolveRootCompletionSurface, sanitizeShellIdent
10
10
  * @returns A complete PowerShell completion script.
11
11
  */
12
12
  function generatePowerShellCompletion(schema, options) {
13
- const helperPrefix = `__${sanitizeShellIdentifier(options?.functionPrefix ?? schema.name)}_completions`;
13
+ const prefix = options?.functionPrefix ?? schema.name;
14
+ const helperPrefix = `__${sanitizeShellIdentifier(prefix)}_completions`;
14
15
  const dataVarName = `${helperPrefix}_paths`;
15
16
  const rootSurface = resolveRootCompletionSurface(schema, options?.rootMode);
16
17
  const visibleCommands = rootSurface.visibleCommands;
@@ -1,16 +1,4 @@
1
- import { FlagSchema } from "../../schema/flag.mjs";
2
- import { CommandSchema } from "../../schema/command.mjs";
3
- import "../../schema/index.mjs";
4
1
  //#region src/core/completion/shells/shared.d.ts
5
- /**
6
- * Format a version tag for generated completion script headers.
7
- *
8
- * Produces e.g. `"@kjanat/dreamcli v0.9.1 (f9b5f1a)"` when built, or
9
- * `"@kjanat/dreamcli"` when running unbundled in development.
10
- *
11
- * @internal
12
- */
13
- declare function versionTag(): string;
14
2
  /**
15
3
  * Options for completion script generation.
16
4
  *
@@ -42,7 +30,7 @@ interface CompletionOptions {
42
30
  *
43
31
  * @defaultValue `'command'`
44
32
  */
45
- readonly as?: 'command' | 'flag';
33
+ readonly as?: "command" | "flag";
46
34
  /**
47
35
  * Controls which root-level surface shell completion exposes when a
48
36
  * default command exists.
@@ -55,106 +43,7 @@ interface CompletionOptions {
55
43
  *
56
44
  * @defaultValue `'subcommands'`
57
45
  */
58
- readonly rootMode?: 'subcommands' | 'surface';
59
- }
60
- /**
61
- * Normalized root completion surface consumed by shell generators.
62
- *
63
- * @internal
64
- */
65
- interface RootCompletionSurface {
66
- readonly visibleCommands: readonly CommandSchema[];
67
- readonly visibleDefaultCommand: CommandSchema | undefined;
68
- readonly rootFlags: Readonly<Record<string, FlagSchema>>;
69
- readonly defaultFlags: Readonly<Record<string, FlagSchema>>;
70
- readonly includeDefaultFlags: boolean;
71
- }
72
- /**
73
- * Schema shape needed to compute the root completion surface.
74
- *
75
- * @internal
76
- */
77
- interface RootCompletionSchemaLike {
78
- readonly commands: ReadonlyArray<{
79
- readonly schema: CommandSchema;
80
- }>;
81
- readonly defaultCommand: {
82
- readonly schema: CommandSchema;
83
- } | undefined;
84
- readonly version: string | undefined;
85
- }
86
- /**
87
- * Resolve the root-level completion surface from the CLI schema and policy.
88
- *
89
- * @internal
90
- */
91
- declare function resolveRootCompletionSurface(schema: RootCompletionSchemaLike, rootMode?: CompletionOptions['rootMode']): RootCompletionSurface;
92
- /**
93
- * A flattened node from the command tree, carrying its ancestry context.
94
- *
95
- * Used by both bash and zsh generators to produce completions at every
96
- * nesting level with correct propagated flag inheritance.
97
- *
98
- * @internal
99
- */
100
- interface CommandNode {
101
- /** Name path from root: `['db', 'migrate']` */
102
- readonly path: readonly string[];
103
- /** The command schema at this node */
104
- readonly schema: CommandSchema;
105
- /** Propagated flags inherited from ancestors (excludes own flags) */
106
- readonly propagatedFlags: Readonly<Record<string, FlagSchema>>;
107
- /** Merged flags: propagated + own (own shadows propagated) */
108
- readonly mergedFlags: Readonly<Record<string, FlagSchema>>;
109
- /** Visible child command schemas (for subcommand completion) */
110
- readonly children: readonly CommandSchema[];
46
+ readonly rootMode?: "subcommands" | "surface";
111
47
  }
112
- /**
113
- * Walk the command tree depth-first, producing a flat list of
114
- * {@link CommandNode}s with propagated flag context.
115
- *
116
- * @param topLevel - Top-level visible command schemas.
117
- * @param ancestorSchemas - Schema path from root (for propagation calculation).
118
- * @returns Flat list of all visible nodes in the tree.
119
- *
120
- * @internal
121
- */
122
- declare function walkCommandTree(topLevel: readonly CommandSchema[], ancestorSchemas?: readonly CommandSchema[]): readonly CommandNode[];
123
- /**
124
- * Effective negated long-form spelling for user-facing suggestion lists.
125
- *
126
- * Returns the negated spelling without the `--` prefix (e.g. `no-verbose`)
127
- * when the flag is negatable and the negation is not hidden; `undefined`
128
- * otherwise. Negated spellings are long-only and take no value, so they only
129
- * belong in suggestion lists — never in value-flag (operand-skip) patterns.
130
- *
131
- * @internal
132
- */
133
- declare function getVisibleNegatedName(name: string, schema: FlagSchema): string | undefined;
134
- /**
135
- * Sanitize a string for use as a shell function identifier.
136
- * Replaces non-alphanumeric/underscore characters with underscores.
137
- * When sanitization changes the name, appends a short stable hash suffix so
138
- * distinct originals cannot collide on the same helper identifier.
139
- * Used by both bash and zsh generators.
140
- *
141
- * @internal
142
- */
143
- declare function sanitizeShellIdentifier(name: string): string;
144
- /**
145
- * Quote a string for safe interpolation into a shell script.
146
- *
147
- * Uses single-quote wrapping with the standard `'\''` idiom for
148
- * embedded single quotes. This prevents shell injection from CLI
149
- * names containing spaces, semicolons, backticks, or other
150
- * special characters.
151
- *
152
- * Returns the input unquoted if it consists only of shell-safe
153
- * characters (`[a-zA-Z0-9_\-.]`), avoiding unnecessary noise
154
- * in generated scripts for common CLI names like `my-cli` or `app.v2`.
155
- *
156
- * @internal
157
- */
158
- declare function quoteShellArg(value: string): string;
159
48
  //#endregion
160
- export { type CommandNode, type CompletionOptions, type RootCompletionSurface, getVisibleNegatedName, quoteShellArg, resolveRootCompletionSurface, sanitizeShellIdentifier, versionTag, walkCommandTree };
49
+ export type { CompletionOptions };
@@ -1,19 +1,10 @@
1
- import { getFlagNegatedName } from "../../schema/flag.mjs";
1
+ import { createFlagSchema, getFlagNegatedName } from "../../schema/flag.mjs";
2
+ import { builtinEnabled } from "../../cli/builtins.mjs";
2
3
  import { collectPropagatedFlags } from "../../cli/propagate.mjs";
3
4
  import { resolveRootSurface } from "../../cli/root-surface.mjs";
4
5
  import { DREAMCLI_REVISION, DREAMCLI_VERSION } from "../../../version.mjs";
5
6
  //#region src/core/completion/shells/shared.ts
6
7
  /**
7
- * Shared infrastructure for shell completion generators.
8
- *
9
- * Provides the command tree walker, shell escaping utilities, and
10
- * the version tag used in generated script headers. Consumed by
11
- * the per-shell generators in sibling files.
12
- *
13
- * @module dreamcli/core/completion/shells/shared
14
- * @internal
15
- */
16
- /**
17
8
  * Format a version tag for generated completion script headers.
18
9
  *
19
10
  * Produces e.g. `"@kjanat/dreamcli v0.9.1 (f9b5f1a)"` when built, or
@@ -22,7 +13,8 @@ import { DREAMCLI_REVISION, DREAMCLI_VERSION } from "../../../version.mjs";
22
13
  * @internal
23
14
  */
24
15
  function versionTag() {
25
- return `@kjanat/dreamcli v${DREAMCLI_VERSION}${` (${DREAMCLI_REVISION})`}`;
16
+ const rev = ` (${DREAMCLI_REVISION})`;
17
+ return `@kjanat/dreamcli v${DREAMCLI_VERSION}${rev}`;
26
18
  }
27
19
  /**
28
20
  * Resolve the root-level completion surface from the CLI schema and policy.
@@ -31,7 +23,7 @@ function versionTag() {
31
23
  */
32
24
  function resolveRootCompletionSurface(schema, rootMode = "subcommands") {
33
25
  const rootSurface = resolveRootSurface(schema);
34
- const rootFlags = createRootFlags(schema.version !== void 0);
26
+ const rootFlags = createRootFlags(builtinEnabled(schema.builtins, "help"), schema.version !== void 0);
35
27
  const defaultFlags = rootSurface.visibleDefaultCommand?.flags ?? {};
36
28
  const includeDefaultFlags = rootMode === "surface" ? rootSurface.hasVisibleDefault : rootSurface.hasVisibleDefault && !rootSurface.hasVisibleSubcommands;
37
29
  const defaultCommand = rootSurface.visibleDefaultCommand;
@@ -47,13 +39,14 @@ function resolveRootCompletionSurface(schema, rootMode = "subcommands") {
47
39
  /**
48
40
  * Build the synthetic root-level flags (`--help`, optionally `--version`).
49
41
  *
42
+ * @param hasHelp - Whether the root still owns `--help`.
50
43
  * @param hasVersion - Whether to include a `--version` flag.
51
44
  * @returns A record of root flag schemas.
52
45
  * @internal
53
46
  */
54
- function createRootFlags(hasVersion) {
47
+ function createRootFlags(hasHelp, hasVersion) {
55
48
  return {
56
- help: createSyntheticRootFlag("Show help text"),
49
+ ...hasHelp ? { help: createSyntheticRootFlag("Show help text") } : {},
57
50
  ...hasVersion ? { version: createSyntheticRootFlag("Show version") } : {}
58
51
  };
59
52
  }
@@ -65,30 +58,7 @@ function createRootFlags(hasVersion) {
65
58
  * @internal
66
59
  */
67
60
  function createSyntheticRootFlag(description) {
68
- return {
69
- kind: "boolean",
70
- presence: "optional",
71
- defaultValue: void 0,
72
- aliases: [],
73
- envVar: void 0,
74
- configPath: void 0,
75
- description,
76
- enumValues: void 0,
77
- numberConstraints: void 0,
78
- stringConstraints: void 0,
79
- elementSchema: void 0,
80
- separator: void 0,
81
- unique: false,
82
- pathChecks: void 0,
83
- valueHint: void 0,
84
- prompt: void 0,
85
- parseFn: void 0,
86
- standard: void 0,
87
- deprecated: void 0,
88
- propagate: false,
89
- negation: void 0,
90
- duplicates: "last"
91
- };
61
+ return createFlagSchema("boolean", { description });
92
62
  }
93
63
  /**
94
64
  * Walk the command tree depth-first, producing a flat list of
@@ -1,5 +1,4 @@
1
1
  import { CompletionOptions } from "./shared.mjs";
2
- import { CLISchema } from "../../cli/index.mjs";
3
2
  //#region src/core/completion/shells/zsh.d.ts
4
3
  /**
5
4
  * Generate a zsh completion script for the CLI.
@@ -21,7 +21,8 @@ import { getVisibleNegatedName, quoteShellArg, resolveRootCompletionSurface, san
21
21
  * ```
22
22
  */
23
23
  function generateZshCompletion(schema, options) {
24
- const funcName = `_${sanitizeShellIdentifier(options?.functionPrefix ?? schema.name)}`;
24
+ const prefix = options?.functionPrefix ?? schema.name;
25
+ const funcName = `_${sanitizeShellIdentifier(prefix)}`;
25
26
  const rootSurface = resolveRootCompletionSurface(schema, options?.rootMode);
26
27
  const visibleCommands = rootSurface.visibleCommands;
27
28
  const nodes = walkCommandTree(visibleCommands);
@@ -1,5 +1,5 @@
1
1
  import { RuntimeAdapter } from "../../runtime/adapter.mjs";
2
- import { ManifestDiscoveryOptions, PackageJsonAdapter, PackageJsonData, PackageRepository, PackageRepositoryUrlOptions, discoverManifest, discoverPackageJson, inferCliName, packageRepositoryUrl } from "./package-json.mjs";
2
+ import { ManifestDiscoveryOptions, PackageJsonAdapter, PackageJsonData, PackageRepository, PackageRepositoryUrlOptions, discoverManifest, inferCliName, packageRepositoryUrl } from "./package-json.mjs";
3
3
  //#region src/core/config/index.d.ts
4
4
  /**
5
5
  * Format loader — parses file content into a config object.
@@ -126,7 +126,7 @@ declare function buildConfigSearchPaths(appName: string, options: ConfigSearchPa
126
126
  * Exported so custom hosts and tests can type the minimal adapter required by
127
127
  * {@link discoverConfig} without depending on the full runtime adapter shape.
128
128
  */
129
- type ConfigAdapter = Pick<RuntimeAdapter, 'readFile' | 'cwd' | 'configDir'> & Partial<Pick<RuntimeAdapter, 'userConfigDirs' | 'systemConfigDirs'>>;
129
+ type ConfigAdapter = Pick<RuntimeAdapter, "readFile" | "cwd" | "configDir"> & Partial<Pick<RuntimeAdapter, "userConfigDirs" | "systemConfigDirs">>;
130
130
  /**
131
131
  * Discover and load a config file.
132
132
  *
@@ -188,4 +188,4 @@ declare function discoverConfig(appName: string, adapter: ConfigAdapter, options
188
188
  */
189
189
  declare function configFormat(extensions: readonly string[], parse: (content: string) => unknown): FormatLoader;
190
190
  //#endregion
191
- export { type ConfigAdapter, type ConfigDiscoveryOptions, type ConfigDiscoveryResult, type ConfigFound, type ConfigNotFound, type ConfigSearchPathOptions, type FormatLoader, type ManifestDiscoveryOptions, type PackageJsonAdapter, type PackageJsonData, type PackageRepository, type PackageRepositoryUrlOptions, buildConfigSearchPaths, configFormat, discoverConfig, discoverManifest, discoverPackageJson, inferCliName, packageRepositoryUrl };
191
+ export { type ConfigAdapter, type ConfigDiscoveryOptions, type ConfigDiscoveryResult, type ConfigFound, type ConfigNotFound, type ConfigSearchPathOptions, type FormatLoader, type ManifestDiscoveryOptions, type PackageJsonAdapter, type PackageJsonData, type PackageRepository, type PackageRepositoryUrlOptions, buildConfigSearchPaths, configFormat, discoverConfig, discoverManifest, inferCliName, packageRepositoryUrl };
@@ -1,5 +1,5 @@
1
1
  import { CLIError } from "../errors/index.mjs";
2
- import { discoverManifest, discoverPackageJson, inferCliName, packageRepositoryUrl } from "./package-json.mjs";
2
+ import { discoverManifest, inferCliName, packageRepositoryUrl } from "./package-json.mjs";
3
3
  //#region src/core/config/index.ts
4
4
  /**
5
5
  * Config file discovery and loading.
@@ -282,4 +282,4 @@ function configFormat(extensions, parse) {
282
282
  };
283
283
  }
284
284
  //#endregion
285
- export { buildConfigSearchPaths, configFormat, discoverConfig, discoverManifest, discoverPackageJson, inferCliName, packageRepositoryUrl };
285
+ export { buildConfigSearchPaths, configFormat, discoverConfig, discoverManifest, inferCliName, packageRepositoryUrl };
@@ -37,7 +37,7 @@ interface PackageJsonData {
37
37
  * Using a narrow pick keeps the function easy to test and makes the
38
38
  * dependency explicit.
39
39
  */
40
- type PackageJsonAdapter = Pick<RuntimeAdapter, 'readFile' | 'cwd'>;
40
+ type PackageJsonAdapter = Pick<RuntimeAdapter, "readFile" | "cwd">;
41
41
  /** Options for {@link discoverManifest}. */
42
42
  interface ManifestDiscoveryOptions {
43
43
  /**
@@ -101,37 +101,6 @@ interface ManifestDiscoveryOptions {
101
101
  * ```
102
102
  */
103
103
  declare function discoverManifest(adapter: PackageJsonAdapter, options?: ManifestDiscoveryOptions): Promise<PackageJsonData | null>;
104
- /**
105
- * Discover the nearest `package.json` by walking up from `startDir` (or
106
- * `adapter.cwd` when omitted).
107
- *
108
- * @deprecated Use {@link discoverManifest} with `{ files: ['package.json'] }`
109
- * (the default), which also supports `deno.json` / `jsr.json`.
110
- *
111
- * Behavior note (changed by the manifest generalization): a parseable but
112
- * metadata-less `package.json` — `{}`, or one carrying only non-metadata fields
113
- * such as `dependencies` / `scripts` / `type` — is no longer treated as a
114
- * discovery hit. Previously such a file halted the walk-up and resolved to `{}`;
115
- * now it is skipped and the walk-up CONTINUES to parent directories. In a
116
- * monorepo this means a metadata-less leaf `package.json` no longer shadows an
117
- * ancestor manifest, so an ancestor's `version` can surface where the old
118
- * behavior returned `{}`. Pass pre-loaded `data` (or use {@link discoverManifest}
119
- * with an explicit `startDir`) when you need to pin discovery to one directory.
120
- *
121
- * @param adapter - Adapter providing `readFile` + `cwd`.
122
- * @param startDir - Optional explicit directory or file path to walk up from.
123
- *
124
- * @example
125
- * ```ts
126
- * import { discoverPackageJson } from '@kjanat/dreamcli';
127
- *
128
- * const pkg = await discoverPackageJson(adapter);
129
- * if (pkg !== null) {
130
- * console.log(pkg.version); // '1.2.3'
131
- * }
132
- * ```
133
- */
134
- declare function discoverPackageJson(adapter: PackageJsonAdapter, startDir?: string): Promise<PackageJsonData | null>;
135
104
  /** Options for {@link packageRepositoryUrl}. */
136
105
  interface PackageRepositoryUrlOptions {
137
106
  /**
@@ -207,4 +176,4 @@ declare function inferCliName(pkg: PackageJsonData, options?: {
207
176
  readonly stripScope?: boolean;
208
177
  }): string | undefined;
209
178
  //#endregion
210
- export { type ManifestDiscoveryOptions, type PackageJsonAdapter, type PackageJsonData, type PackageRepository, type PackageRepositoryUrlOptions, discoverManifest, discoverPackageJson, inferCliName, packageRepositoryUrl };
179
+ export { type ManifestDiscoveryOptions, type PackageJsonAdapter, type PackageJsonData, type PackageRepository, type PackageRepositoryUrlOptions, discoverManifest, inferCliName, packageRepositoryUrl };
@@ -114,39 +114,6 @@ async function discoverManifest(adapter, options = {}) {
114
114
  }
115
115
  return null;
116
116
  }
117
- /**
118
- * Discover the nearest `package.json` by walking up from `startDir` (or
119
- * `adapter.cwd` when omitted).
120
- *
121
- * @deprecated Use {@link discoverManifest} with `{ files: ['package.json'] }`
122
- * (the default), which also supports `deno.json` / `jsr.json`.
123
- *
124
- * Behavior note (changed by the manifest generalization): a parseable but
125
- * metadata-less `package.json` — `{}`, or one carrying only non-metadata fields
126
- * such as `dependencies` / `scripts` / `type` — is no longer treated as a
127
- * discovery hit. Previously such a file halted the walk-up and resolved to `{}`;
128
- * now it is skipped and the walk-up CONTINUES to parent directories. In a
129
- * monorepo this means a metadata-less leaf `package.json` no longer shadows an
130
- * ancestor manifest, so an ancestor's `version` can surface where the old
131
- * behavior returned `{}`. Pass pre-loaded `data` (or use {@link discoverManifest}
132
- * with an explicit `startDir`) when you need to pin discovery to one directory.
133
- *
134
- * @param adapter - Adapter providing `readFile` + `cwd`.
135
- * @param startDir - Optional explicit directory or file path to walk up from.
136
- *
137
- * @example
138
- * ```ts
139
- * import { discoverPackageJson } from '@kjanat/dreamcli';
140
- *
141
- * const pkg = await discoverPackageJson(adapter);
142
- * if (pkg !== null) {
143
- * console.log(pkg.version); // '1.2.3'
144
- * }
145
- * ```
146
- */
147
- async function discoverPackageJson(adapter, startDir) {
148
- return discoverManifest(adapter, startDir !== void 0 ? { startDir } : {});
149
- }
150
117
  /** Whitespace characters JSON treats as insignificant. @internal */
151
118
  function isJsonWhitespace(ch) {
152
119
  return ch === " " || ch === " " || ch === "\n" || ch === "\r";
@@ -383,4 +350,4 @@ function inferCliName(pkg, options = {}) {
383
350
  }
384
351
  }
385
352
  //#endregion
386
- export { discoverManifest, discoverPackageJson, inferCliName, packageRepositoryUrl };
353
+ export { discoverManifest, inferCliName, packageRepositoryUrl };