@kjanat/dreamcli 3.0.0-rc.6 → 3.0.0-rc.8

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 (94) hide show
  1. package/CHANGELOG.md +94 -1
  2. package/dist/core/cli/dispatch.d.mts +6 -5
  3. package/dist/core/cli/dispatch.mjs +7 -5
  4. package/dist/core/cli/help-links.d.mts +0 -1
  5. package/dist/core/cli/index.d.mts +27 -2
  6. package/dist/core/cli/index.mjs +28 -14
  7. package/dist/core/cli/planner.d.mts +3 -1
  8. package/dist/core/cli/planner.mjs +12 -12
  9. package/dist/core/cli/plugin.d.mts +1 -1
  10. package/dist/core/cli/propagate.d.mts +1 -1
  11. package/dist/core/cli/root-help.d.mts +0 -1
  12. package/dist/core/cli/root-help.mjs +38 -21
  13. package/dist/core/cli/root-surface.d.mts +0 -1
  14. package/dist/core/cli/runtime-preflight.d.mts +12 -2
  15. package/dist/core/cli/runtime-preflight.mjs +5 -4
  16. package/dist/core/completion/index.d.mts +0 -1
  17. package/dist/core/completion/index.mjs +1 -1
  18. package/dist/core/completion/shells/bash.d.mts +0 -1
  19. package/dist/core/completion/shells/bash.mjs +8 -4
  20. package/dist/core/completion/shells/fish.d.mts +0 -1
  21. package/dist/core/completion/shells/fish.mjs +6 -3
  22. package/dist/core/completion/shells/powershell.d.mts +0 -1
  23. package/dist/core/completion/shells/powershell.mjs +10 -5
  24. package/dist/core/completion/shells/shared.d.mts +13 -2
  25. package/dist/core/completion/shells/shared.mjs +24 -2
  26. package/dist/core/completion/shells/zsh.d.mts +0 -1
  27. package/dist/core/completion/shells/zsh.mjs +11 -4
  28. package/dist/core/config/index.d.mts +2 -3
  29. package/dist/core/config/index.mjs +2 -2
  30. package/dist/core/config/package-json.d.mts +27 -4
  31. package/dist/core/config/package-json.mjs +20 -19
  32. package/dist/core/errors/index.d.mts +1 -1
  33. package/dist/core/execution/index.d.mts +0 -1
  34. package/dist/core/execution/index.mjs +8 -4
  35. package/dist/core/help/ansi.mjs +3 -2
  36. package/dist/core/help/index.d.mts +22 -3
  37. package/dist/core/help/index.mjs +65 -53
  38. package/dist/core/help/theme.d.mts +68 -0
  39. package/dist/core/help/theme.mjs +46 -0
  40. package/dist/core/json-schema/index.d.mts +1 -1
  41. package/dist/core/json-schema/index.mjs +39 -8
  42. package/dist/core/json-schema/meta-descriptions.generated.d.mts +22 -5
  43. package/dist/core/json-schema/meta-descriptions.generated.mjs +14 -5
  44. package/dist/core/output/activity.d.mts +0 -1
  45. package/dist/core/output/contracts.d.mts +0 -1
  46. package/dist/core/output/contracts.mjs +1 -1
  47. package/dist/core/output/index.d.mts +0 -1
  48. package/dist/core/output/index.mjs +1 -1
  49. package/dist/core/output/renderers.d.mts +0 -1
  50. package/dist/core/parse/index.d.mts +40 -7
  51. package/dist/core/parse/index.mjs +209 -40
  52. package/dist/core/prompt/index.d.mts +1 -0
  53. package/dist/core/resolve/args.d.mts +1 -1
  54. package/dist/core/resolve/coerce.d.mts +1 -1
  55. package/dist/core/resolve/coerce.mjs +71 -14
  56. package/dist/core/resolve/contracts.d.mts +7 -2
  57. package/dist/core/resolve/errors.d.mts +0 -1
  58. package/dist/core/resolve/flags.d.mts +7 -2
  59. package/dist/core/resolve/flags.mjs +61 -6
  60. package/dist/core/resolve/index.d.mts +2 -2
  61. package/dist/core/resolve/index.mjs +1 -1
  62. package/dist/core/resolve/property.d.mts +3 -0
  63. package/dist/core/resolve/property.mjs +11 -3
  64. package/dist/core/schema/activity.d.mts +31 -11
  65. package/dist/core/schema/arg.d.mts +1 -2
  66. package/dist/core/schema/command.d.mts +8 -6
  67. package/dist/core/schema/command.mjs +26 -12
  68. package/dist/core/schema/flag.d.mts +439 -10
  69. package/dist/core/schema/flag.mjs +255 -3
  70. package/dist/core/schema/index.d.mts +4 -2
  71. package/dist/core/schema/middleware.d.mts +4 -3
  72. package/dist/core/schema/prompt.d.mts +5 -2
  73. package/dist/core/schema/run.d.mts +20 -1
  74. package/dist/core/schema/string-constraints.d.mts +97 -0
  75. package/dist/core/schema/string-constraints.mjs +69 -0
  76. package/dist/core/schema/value-parsers.d.mts +78 -0
  77. package/dist/core/schema/value-parsers.mjs +142 -0
  78. package/dist/core/schema-dsl/to-json-schema.d.mts +0 -1
  79. package/dist/core/testkit/index.d.mts +0 -31
  80. package/dist/core/testkit/index.mjs +1 -1
  81. package/dist/index.d.mts +8 -4
  82. package/dist/index.mjs +7 -7
  83. package/dist/runtime/adapter.d.mts +22 -1
  84. package/dist/runtime/adapter.mjs +3 -0
  85. package/dist/runtime/auto.d.mts +0 -1
  86. package/dist/runtime/deno.d.mts +15 -5
  87. package/dist/runtime/deno.mjs +9 -0
  88. package/dist/runtime/node.d.mts +2 -2
  89. package/dist/runtime/node.mjs +10 -0
  90. package/dist/runtime.d.mts +1 -0
  91. package/dist/testkit.d.mts +1 -0
  92. package/dist/version.mjs +2 -2
  93. package/dreamcli.schema.json +35 -6
  94. package/package.json +12 -13
@@ -1,7 +1,8 @@
1
+ import { command } from "../schema/command.mjs";
1
2
  import { resolveRootSurface } from "./root-surface.mjs";
2
3
  import { osc8, padEnd, wrapText } from "../help/ansi.mjs";
4
+ import { resolveHelpTheme } from "../help/theme.mjs";
3
5
  import { formatFlagEntriesBlock, formatHelpSections } from "../help/index.mjs";
4
- import { command } from "../schema/command.mjs";
5
6
  //#region src/core/cli/root-help.ts
6
7
  /**
7
8
  * Root-level help formatter for the CLI program.
@@ -30,16 +31,18 @@ function formatRootHelp(schema, options) {
30
31
  const hyperlinks = options?.hyperlinks === true;
31
32
  const inlineDefault = options?.inlineDefault ?? true;
32
33
  const showDefaultInCommands = options?.showDefaultInCommands ?? false;
34
+ const theme = resolveHelpTheme(options?.colors, options?.theme);
33
35
  const surface = resolveRootSurface(schema);
34
36
  const defaultCommand = surface.visibleDefaultCommand;
35
37
  const defaultIsSoleSurface = !surface.hasVisibleSubcommands && schema.completionsFlag === void 0;
36
38
  const inlineDefaultCommand = inlineDefault || defaultIsSoleSurface ? defaultCommand : void 0;
37
39
  const surfaceCommand = resolveSurfaceCommand(schema, inlineDefaultCommand);
38
40
  const inline = surfaceCommand !== void 0;
39
- const sections = [formatHeader(schema, hyperlinks)];
41
+ const sections = [formatHeader(schema, hyperlinks, theme)];
40
42
  if (schema.description !== void 0) sections.push(schema.description);
41
43
  const placeholder = surface.hasVisibleSubcommands ? defaultCommand !== void 0 ? "[command]" : "<command>" : "";
42
- const rootUsage = placeholder.length > 0 ? `Usage: ${binName} ${placeholder} [options]` : `Usage: ${binName} [options]`;
44
+ const usageTitle = theme.sectionTitle("Usage:");
45
+ const rootUsage = placeholder.length > 0 ? `${usageTitle} ${theme.usageBin(binName)} ${theme.placeholder(placeholder)} ${theme.placeholder("[options]")}` : `${usageTitle} ${theme.usageBin(binName)} ${theme.placeholder("[options]")}`;
43
46
  let surfaceSections = [];
44
47
  if (inline && surfaceCommand !== void 0) surfaceSections = [...formatHelpSections(surfaceCommand, {
45
48
  ...options,
@@ -47,16 +50,16 @@ function formatRootHelp(schema, options) {
47
50
  isDefaultHelp: true
48
51
  })];
49
52
  const surfaceUsage = surfaceSections.shift();
50
- if (inline && surfaceUsage !== void 0 && inlineDefaultCommand !== void 0) sections.push(surface.hasVisibleSubcommands ? mergeUsageSections(rootUsage, surfaceUsage) : surfaceUsage);
53
+ if (inline && surfaceUsage !== void 0 && inlineDefaultCommand !== void 0) sections.push(surface.hasVisibleSubcommands ? mergeUsageSections(rootUsage, surfaceUsage, usageTitle) : surfaceUsage);
51
54
  else sections.push(rootUsage);
52
55
  const listDefaultInCommands = defaultCommand !== void 0 && (surface.defaultRouted || showDefaultInCommands);
53
56
  const listedCommands = listDefaultInCommands ? [...surface.visibleSubcommands, defaultCommand] : surface.visibleSubcommands;
54
- if (listedCommands.length > 0) sections.push(formatRootCommandsSection(listedCommands, listDefaultInCommands ? defaultCommand?.name : void 0, width));
57
+ if (listedCommands.length > 0) sections.push(formatRootCommandsSection(listedCommands, listDefaultInCommands ? defaultCommand?.name : void 0, width, theme));
55
58
  if (inline && surfaceCommand !== void 0) {
56
59
  if (surfaceCommand.description !== void 0 && surfaceCommand.description === schema.description && surfaceSections[0] === surfaceCommand.description) surfaceSections.shift();
57
60
  sections.push(...surfaceSections);
58
61
  }
59
- const globalOptions = formatGlobalOptionsSection(schema, width);
62
+ const globalOptions = formatGlobalOptionsSection(schema, width, theme);
60
63
  if (globalOptions.length > 0) sections.push(globalOptions);
61
64
  if (options?.footer ?? surface.hasVisibleSubcommands) {
62
65
  const footerPlaceholder = surface.hasVisibleSubcommands ? defaultCommand !== void 0 ? " [command]" : " <command>" : "";
@@ -105,11 +108,18 @@ function completionsFlagSchema(shells) {
105
108
  description: "Print a shell completion script and exit",
106
109
  enumValues: shells,
107
110
  elementSchema: void 0,
111
+ separator: void 0,
112
+ unique: false,
108
113
  numberConstraints: void 0,
114
+ stringConstraints: void 0,
115
+ pathChecks: void 0,
116
+ valueHint: void 0,
109
117
  prompt: void 0,
110
118
  parseFn: void 0,
111
119
  deprecated: void 0,
112
- propagate: false
120
+ propagate: false,
121
+ negation: void 0,
122
+ duplicates: "last"
113
123
  };
114
124
  }
115
125
  /**
@@ -123,14 +133,16 @@ function completionsFlagSchema(shells) {
123
133
  *
124
134
  * @param schema - The CLI schema.
125
135
  * @param hyperlinks - Whether OSC 8 hyperlinks may be emitted.
136
+ * @param theme - Theme applied to the name and version (inside any hyperlink).
126
137
  * @returns The header line.
127
138
  * @internal
128
139
  */
129
- function formatHeader(schema, hyperlinks) {
140
+ function formatHeader(schema, hyperlinks, theme) {
130
141
  const links = hyperlinks ? schema.helpLinks : void 0;
131
- const name = links?.name !== void 0 ? osc8(links.name, schema.name) : schema.name;
142
+ const styledName = theme.headerName(schema.name);
143
+ const name = links?.name !== void 0 ? osc8(links.name, styledName) : styledName;
132
144
  if (schema.version === void 0) return name;
133
- const version = `v${schema.version}`;
145
+ const version = theme.headerVersion(`v${schema.version}`);
134
146
  return `${name} ${links?.version !== void 0 ? osc8(links.version, version) : version}`;
135
147
  }
136
148
  /**
@@ -139,11 +151,12 @@ function formatHeader(schema, hyperlinks) {
139
151
  * @param visibleCommands - Non-hidden top-level commands.
140
152
  * @param defaultName - Name of the default command (appends " (default)" tag).
141
153
  * @param width - Terminal width for description wrapping.
154
+ * @param theme - Theme applied to the title, command names, and default tag.
142
155
  * @returns Formatted commands block.
143
156
  * @internal
144
157
  */
145
- function formatRootCommandsSection(visibleCommands, defaultName, width) {
146
- const lines = ["Commands:"];
158
+ function formatRootCommandsSection(visibleCommands, defaultName, width, theme) {
159
+ const lines = [theme.sectionTitle("Commands:")];
147
160
  const GAP = 2;
148
161
  const DEFAULT_TAG = " (default)";
149
162
  let maxNameLen = 0;
@@ -154,7 +167,7 @@ function formatRootCommandsSection(visibleCommands, defaultName, width) {
154
167
  }
155
168
  const descCol = 2 + maxNameLen + GAP;
156
169
  for (const cmd of visibleCommands) {
157
- const padded = padEnd(` ${cmd.name === defaultName ? `${cmd.name}${DEFAULT_TAG}` : cmd.name}`, descCol);
170
+ const padded = padEnd(` ${cmd.name === defaultName ? `${theme.command(cmd.name)}${theme.annotation(DEFAULT_TAG)}` : theme.command(cmd.name)}`, descCol);
158
171
  const desc = cmd.description ?? "";
159
172
  if (desc.length === 0) lines.push(padded.trimEnd());
160
173
  else lines.push(`${padded}${wrapText(desc, width, descCol)}`);
@@ -171,38 +184,42 @@ function formatRootCommandsSection(visibleCommands, defaultName, width) {
171
184
  *
172
185
  * @param schema - The CLI schema (read for `version` and `configSettings`).
173
186
  * @param width - Terminal width for description wrapping.
187
+ * @param theme - Theme applied to the title and flag forms.
174
188
  * @returns Formatted `Global options:` block (always non-empty).
175
189
  * @internal
176
190
  */
177
- function formatGlobalOptionsSection(schema, width) {
191
+ function formatGlobalOptionsSection(schema, width, theme) {
178
192
  const entries = [{
179
- left: "-h, --help",
193
+ left: theme.flag("-h, --help"),
180
194
  description: "Show this help message and exit"
181
195
  }];
182
196
  if (schema.version !== void 0) entries.push({
183
- left: "-V, --version",
197
+ left: theme.flag("-V, --version"),
184
198
  description: "Print the version number and exit"
185
199
  });
186
200
  entries.push({
187
- left: "--json",
201
+ left: theme.flag("--json"),
188
202
  description: "Emit machine-readable JSON output"
189
203
  });
190
204
  if (schema.configSettings !== void 0) entries.push({
191
- left: "--config <path>",
205
+ left: `${theme.flag("--config")} ${theme.placeholder("<path>")}`,
192
206
  description: "Load configuration from the given file"
193
207
  });
194
- return formatFlagEntriesBlock("Global options:", entries, width);
208
+ return formatFlagEntriesBlock(theme.sectionTitle("Global options:"), entries, width);
195
209
  }
196
210
  /**
197
211
  * Merge root and default-command usage lines into a single block.
198
212
  *
199
213
  * @param rootUsage - The root usage line (e.g. `Usage: mycli [command] [options]`).
200
214
  * @param commandUsage - The default command's usage line.
215
+ * @param usageTitle - The themed `Usage:` title — byte-identical in both lines
216
+ * within one render, so the styled prefix strips cleanly.
201
217
  * @returns Combined usage block with aligned continuation.
202
218
  * @internal
203
219
  */
204
- function mergeUsageSections(rootUsage, commandUsage) {
205
- const commandSuffix = commandUsage.startsWith("Usage: ") ? commandUsage.slice(7) : commandUsage;
220
+ function mergeUsageSections(rootUsage, commandUsage, usageTitle) {
221
+ const usagePrefix = `${usageTitle} `;
222
+ const commandSuffix = commandUsage.startsWith(usagePrefix) ? commandUsage.slice(usagePrefix.length) : commandUsage;
206
223
  return `${rootUsage}\n${" ".repeat(7)}${commandSuffix}`;
207
224
  }
208
225
  //#endregion
@@ -1,5 +1,4 @@
1
1
  import { CommandSchema } from "../schema/command.mjs";
2
-
3
2
  //#region src/core/cli/root-surface.d.ts
4
3
  /**
5
4
  * Structural CLI shape needed for root-surface analysis.
@@ -1,15 +1,18 @@
1
1
  import { Verbosity } from "../output/contracts.mjs";
2
+ import "../output/index.mjs";
2
3
  import { PromptEngine } from "../prompt/index.mjs";
3
4
  import { CLIPlugin } from "./plugin.mjs";
4
5
  import { CLIError } from "../errors/index.mjs";
6
+ import { HelpThemeFactory } from "../help/theme.mjs";
7
+ import "../help/index.mjs";
5
8
  import { CommandSchema, ErasedCommand } from "../schema/command.mjs";
9
+ import { ParseOptions } from "../parse/index.mjs";
6
10
  import { RuntimeAdapter } from "../../runtime/adapter.mjs";
7
11
  import { PackageJsonData } from "../config/package-json.mjs";
8
12
  import { HelpLinks } from "./help-links.mjs";
9
13
  import { CompletionOptions } from "../completion/shells/shared.mjs";
10
14
  import { Shell } from "../completion/index.mjs";
11
15
  import { FormatLoader } from "../config/index.mjs";
12
-
13
16
  //#region src/core/cli/runtime-preflight.d.ts
14
17
  /** Config discovery settings extracted from CLISchema for preflight use. @internal */
15
18
  interface RuntimeConfigSettings {
@@ -80,7 +83,10 @@ interface RuntimePreflightSchemaLike {
80
83
  readonly footer?: boolean;
81
84
  readonly width?: number;
82
85
  readonly hyperlinks?: boolean;
86
+ readonly theme?: HelpThemeFactory;
83
87
  } | undefined;
88
+ /** Flag-parsing behavior settings (e.g. case parity). */
89
+ readonly flagSettings: ParseOptions | undefined;
84
90
  /** Plugins forwarded into the execution pipeline. */
85
91
  readonly plugins: readonly CLIPlugin[];
86
92
  }
@@ -106,6 +112,8 @@ interface RuntimePreflightOptions {
106
112
  readonly jsonMode?: boolean;
107
113
  /** TTY detection override; bypasses adapter TTY check. */
108
114
  readonly isTTY?: boolean;
115
+ /** Filesystem probe override for `flag.path()` checks; bypasses the adapter probe. */
116
+ readonly stat?: (path: string) => Promise<'file' | 'directory' | null>;
109
117
  }
110
118
  /**
111
119
  * Fully resolved runtime inputs ready for the execution pipeline.
@@ -129,6 +137,8 @@ interface RuntimeExecutionInputs {
129
137
  readonly prompter?: PromptEngine;
130
138
  /** Loaded config data for the config resolution step. */
131
139
  readonly config?: Readonly<Record<string, unknown>>;
140
+ /** Filesystem probe (from the adapter) for `flag.path()` checks. */
141
+ readonly stat?: (path: string) => Promise<'file' | 'directory' | null>;
132
142
  }
133
143
  /** Preflight succeeded — all runtime inputs are resolved and ready for execution. @internal */
134
144
  interface ReadyRuntimePreflight {
@@ -169,7 +179,7 @@ declare function extractConfigFlag(argv: readonly string[]): {
169
179
  readonly filteredArgv: readonly string[];
170
180
  };
171
181
  /** Check whether a single command's args declare stdin-mode and argv leaves them unresolved. @internal */
172
- declare function commandInvocationNeedsStdin(schema: CommandSchema, argv: readonly string[]): boolean;
182
+ declare function commandInvocationNeedsStdin(schema: CommandSchema, argv: readonly string[], flagSettings?: ParseOptions): boolean;
173
183
  /** Plan the invocation and check whether the matched command needs stdin data. @internal */
174
184
  declare function invocationNeedsStdin(schema: RuntimePreflightSchemaLike, argv: readonly string[]): boolean;
175
185
  /**
@@ -49,10 +49,10 @@ function extractConfigFlag(argv) {
49
49
  };
50
50
  }
51
51
  /** Check whether a single command's args declare stdin-mode and argv leaves them unresolved. @internal */
52
- function commandInvocationNeedsStdin(schema, argv) {
52
+ function commandInvocationNeedsStdin(schema, argv, flagSettings) {
53
53
  if (argv.includes("--help") || argv.includes("-h")) return false;
54
54
  try {
55
- const parsed = parse(schema, argv);
55
+ const parsed = parse(schema, argv, flagSettings);
56
56
  return schema.args.some(({ name, schema: argSchema }) => {
57
57
  const parsedValue = parsed.args[name];
58
58
  return argSchema.stdinMode && (parsedValue === void 0 || parsedValue === "-");
@@ -71,7 +71,7 @@ function invocationNeedsStdin(schema, argv) {
71
71
  output: PRECHECK_OUTPUT
72
72
  });
73
73
  switch (plan.kind) {
74
- case "match": return commandInvocationNeedsStdin(plan.plan.mergedSchema, plan.plan.argv);
74
+ case "match": return commandInvocationNeedsStdin(plan.plan.mergedSchema, plan.plan.argv, schema.flagSettings);
75
75
  case "dispatch-error":
76
76
  case "needs-subcommand":
77
77
  case "root-help":
@@ -158,6 +158,7 @@ async function prepareRuntimePreflight(options) {
158
158
  isTTY: options.options?.isTTY ?? options.adapter.isTTY,
159
159
  jsonMode,
160
160
  verbosity: options.options?.verbosity ?? "normal",
161
+ stat: options.options?.stat ?? options.adapter.stat,
161
162
  ...stdinData !== void 0 ? { stdinData } : {},
162
163
  ...options.options?.prompter !== void 0 ? { prompter: options.options.prompter } : autoPrompter !== void 0 ? { prompter: autoPrompter } : {},
163
164
  ...loadedConfig !== void 0 ? { config: loadedConfig } : {}
@@ -165,4 +166,4 @@ async function prepareRuntimePreflight(options) {
165
166
  };
166
167
  }
167
168
  //#endregion
168
- export { prepareRuntimePreflight };
169
+ export { commandInvocationNeedsStdin, extractConfigFlag, invocationNeedsStdin, prepareRuntimePreflight };
@@ -4,7 +4,6 @@ import { generateFishCompletion } from "./shells/fish.mjs";
4
4
  import { generatePowerShellCompletion } from "./shells/powershell.mjs";
5
5
  import { generateZshCompletion } from "./shells/zsh.mjs";
6
6
  import { CLISchema } from "../cli/index.mjs";
7
-
8
7
  //#region src/core/completion/index.d.ts
9
8
  /**
10
9
  * Supported shell targets for completion script generation.
@@ -87,4 +87,4 @@ function generateCompletion(schema, shell, options) {
87
87
  }
88
88
  }
89
89
  //#endregion
90
- export { SHELLS, detectShell, generateCompletion, normalizeShell };
90
+ export { SHELLS, detectShell, generateBashCompletion, generateCompletion, generateFishCompletion, generatePowerShellCompletion, generateZshCompletion, normalizeShell };
@@ -1,6 +1,5 @@
1
1
  import { CompletionOptions } from "./shared.mjs";
2
2
  import { CLISchema } from "../../cli/index.mjs";
3
-
4
3
  //#region src/core/completion/shells/bash.d.ts
5
4
  /**
6
5
  * Generate a bash completion script for the CLI.
@@ -1,5 +1,6 @@
1
1
  import { getFlagAliasNames } from "../../schema/flag.mjs";
2
- import { quoteShellArg, resolveRootCompletionSurface, sanitizeShellIdentifier, versionTag, walkCommandTree } from "./shared.mjs";
2
+ import { flagExpectsValue } from "../../parse/index.mjs";
3
+ import { getVisibleNegatedName, quoteShellArg, resolveRootCompletionSurface, sanitizeShellIdentifier, versionTag, walkCommandTree } from "./shared.mjs";
3
4
  //#region src/core/completion/shells/bash.ts
4
5
  /**
5
6
  * Generate a bash completion script for the CLI.
@@ -241,7 +242,8 @@ function escapeBashDollarQuote(value) {
241
242
  return value.replace(/\\/g, "\\\\").replace(/'/g, "\\'").replace(/\n/g, "\\n");
242
243
  }
243
244
  /**
244
- * Collect all `--flag` words (long + short aliases) for a flag record.
245
+ * Collect all `--flag` words (long + short aliases + visible negated
246
+ * spellings) for a flag record.
245
247
  *
246
248
  * @internal
247
249
  */
@@ -250,11 +252,13 @@ function collectFlagWords(flags) {
250
252
  for (const [name, schema] of Object.entries(flags)) {
251
253
  words.push(`--${name}`);
252
254
  for (const alias of getFlagAliasNames(schema)) words.push(alias.length === 1 ? `-${alias}` : `--${alias}`);
255
+ const negated = getVisibleNegatedName(name, schema);
256
+ if (negated !== void 0) words.push(`--${negated}`);
253
257
  }
254
258
  return words.join(" ");
255
259
  }
256
260
  /**
257
- * Collect all non-boolean flag forms across every node and root surface,
261
+ * Collect all value-taking flag forms across every node and root surface,
258
262
  * deduplicated and escaped for use in a bash `case` pattern.
259
263
  *
260
264
  * Returns a `|`-joined pattern like `--schema|-s|--output|-o` that the
@@ -267,7 +271,7 @@ function collectValueFlagPattern(nodes, rootSurface) {
267
271
  const forms = /* @__PURE__ */ new Set();
268
272
  const addFlags = (flags) => {
269
273
  for (const [name, schema] of Object.entries(flags)) {
270
- if (schema.kind === "boolean") continue;
274
+ if (!flagExpectsValue(schema)) continue;
271
275
  forms.add(`--${name}`);
272
276
  for (const alias of getFlagAliasNames(schema, { includeHidden: true })) forms.add(alias.length === 1 ? `-${alias}` : `--${alias}`);
273
277
  }
@@ -1,6 +1,5 @@
1
1
  import { CompletionOptions } from "./shared.mjs";
2
2
  import { CLISchema } from "../../cli/index.mjs";
3
-
4
3
  //#region src/core/completion/shells/fish.d.ts
5
4
  /**
6
5
  * Generate a fish completion script for the CLI.
@@ -1,5 +1,6 @@
1
1
  import { getFlagAliasNames } from "../../schema/flag.mjs";
2
- import { quoteShellArg, resolveRootCompletionSurface, sanitizeShellIdentifier, versionTag, walkCommandTree } from "./shared.mjs";
2
+ import { flagExpectsValue } from "../../parse/index.mjs";
3
+ import { getVisibleNegatedName, quoteShellArg, resolveRootCompletionSurface, sanitizeShellIdentifier, versionTag, walkCommandTree } from "./shared.mjs";
3
4
  //#region src/core/completion/shells/fish.ts
4
5
  /**
5
6
  * Generate a fish completion script for the CLI.
@@ -110,8 +111,10 @@ function appendFishFlagCompletions(lines, commandName, pathIsFuncName, path, fla
110
111
  for (const alias of getFlagAliasNames(schema, { kind: "short" })) parts.push(`-s ${quoteShellArg(alias)}`);
111
112
  parts.push(`-l ${quoteShellArg(name)}`);
112
113
  for (const alias of getFlagAliasNames(schema, { kind: "long" })) parts.push(`-l ${quoteShellArg(alias)}`);
114
+ const negated = getVisibleNegatedName(name, schema);
115
+ if (negated !== void 0) parts.push(`-l ${quoteShellArg(negated)}`);
113
116
  parts.push(`-d ${quoteShellArg(schema.description ?? name)}`);
114
- if (schema.kind !== "boolean") parts.push("-r", "-f");
117
+ if (flagExpectsValue(schema)) parts.push("-r", "-f");
115
118
  if (schema.kind === "enum" && schema.enumValues !== void 0) {
116
119
  for (const enumValue of schema.enumValues) lines.push([...parts, `-a ${quoteShellArg(enumValue)}`].join(" "));
117
120
  continue;
@@ -129,7 +132,7 @@ function collectFishValueFlagPatterns(nodes, rootSurface) {
129
132
  ...nodes.map((node) => node.mergedFlags)
130
133
  ];
131
134
  for (const flags of flagSets) for (const [name, schema] of Object.entries(flags)) {
132
- if (schema.kind === "boolean") continue;
135
+ if (!flagExpectsValue(schema)) continue;
133
136
  exact.add(`--${name}`);
134
137
  prefix.add(`--${name}=*`);
135
138
  for (const alias of getFlagAliasNames(schema, {
@@ -1,6 +1,5 @@
1
1
  import { CompletionOptions } from "./shared.mjs";
2
2
  import { CLISchema } from "../../cli/index.mjs";
3
-
4
3
  //#region src/core/completion/shells/powershell.d.ts
5
4
  /**
6
5
  * Generate a PowerShell completion script for the CLI.
@@ -1,5 +1,6 @@
1
- import { getFlagAliasNames } from "../../schema/flag.mjs";
2
- import { resolveRootCompletionSurface, sanitizeShellIdentifier, versionTag, walkCommandTree } from "./shared.mjs";
1
+ import { getFlagAliasNames, getFlagNegatedName } from "../../schema/flag.mjs";
2
+ import { flagExpectsValue } from "../../parse/index.mjs";
3
+ import { getVisibleNegatedName, resolveRootCompletionSurface, sanitizeShellIdentifier, versionTag, walkCommandTree } from "./shared.mjs";
3
4
  //#region src/core/completion/shells/powershell.ts
4
5
  /**
5
6
  * Generate a PowerShell completion script for the CLI.
@@ -89,10 +90,13 @@ function appendPowerShellPathEntry(lines, path, commands, flags) {
89
90
  lines.push(" )");
90
91
  lines.push(" Flags = @(");
91
92
  for (const [name, schema] of Object.entries(flags)) {
93
+ const visibleNegated = getVisibleNegatedName(name, schema);
94
+ const parseNegated = getFlagNegatedName(name, schema);
92
95
  const forms = dedupeValues([
93
96
  `--${name}`,
94
97
  ...getFlagAliasNames(schema, { kind: "short" }).map((alias) => `-${alias}`),
95
- ...getFlagAliasNames(schema, { kind: "long" }).map((alias) => `--${alias}`)
98
+ ...getFlagAliasNames(schema, { kind: "long" }).map((alias) => `--${alias}`),
99
+ ...visibleNegated !== void 0 ? [`--${visibleNegated}`] : []
96
100
  ]);
97
101
  const parseForms = dedupeValues([
98
102
  `--${name}`,
@@ -103,13 +107,14 @@ function appendPowerShellPathEntry(lines, path, commands, flags) {
103
107
  ...getFlagAliasNames(schema, {
104
108
  kind: "long",
105
109
  includeHidden: true
106
- }).map((alias) => `--${alias}`)
110
+ }).map((alias) => `--${alias}`),
111
+ ...parseNegated !== void 0 ? [`--${parseNegated}`] : []
107
112
  ]);
108
113
  lines.push(" @{");
109
114
  lines.push(`\t\t\t\tCanonicalName = ${quotePowerShellString(name)}`);
110
115
  lines.push(`\t\t\t\tForms = ${formatPowerShellArray(forms)}`);
111
116
  lines.push(`\t\t\t\tParseForms = ${formatPowerShellArray(parseForms)}`);
112
- lines.push(`\t\t\t\tRequiresValue = ${schema.kind === "boolean" ? "$false" : "$true"}`);
117
+ lines.push(`\t\t\t\tRequiresValue = ${flagExpectsValue(schema) ? "$true" : "$false"}`);
113
118
  lines.push(`\t\t\t\tDescription = ${quotePowerShellString(schema.description ?? name)}`);
114
119
  lines.push(`\t\t\t\tEnumValues = ${formatPowerShellArray(schema.enumValues ?? [])}`);
115
120
  lines.push(" }");
@@ -1,6 +1,6 @@
1
1
  import { FlagSchema } from "../../schema/flag.mjs";
2
2
  import { CommandSchema } from "../../schema/command.mjs";
3
-
3
+ import "../../schema/index.mjs";
4
4
  //#region src/core/completion/shells/shared.d.ts
5
5
  /**
6
6
  * Format a version tag for generated completion script headers.
@@ -120,6 +120,17 @@ interface CommandNode {
120
120
  * @internal
121
121
  */
122
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;
123
134
  /**
124
135
  * Sanitize a string for use as a shell function identifier.
125
136
  * Replaces non-alphanumeric/underscore characters with underscores.
@@ -146,4 +157,4 @@ declare function sanitizeShellIdentifier(name: string): string;
146
157
  */
147
158
  declare function quoteShellArg(value: string): string;
148
159
  //#endregion
149
- export { type CommandNode, type CompletionOptions, type RootCompletionSurface, quoteShellArg, resolveRootCompletionSurface, sanitizeShellIdentifier, versionTag, walkCommandTree };
160
+ export { type CommandNode, type CompletionOptions, type RootCompletionSurface, getVisibleNegatedName, quoteShellArg, resolveRootCompletionSurface, sanitizeShellIdentifier, versionTag, walkCommandTree };
@@ -1,3 +1,4 @@
1
+ import { getFlagNegatedName } from "../../schema/flag.mjs";
1
2
  import { collectPropagatedFlags } from "../../cli/propagate.mjs";
2
3
  import { resolveRootSurface } from "../../cli/root-surface.mjs";
3
4
  import { DREAMCLI_REVISION, DREAMCLI_VERSION } from "../../../version.mjs";
@@ -74,11 +75,18 @@ function createSyntheticRootFlag(description) {
74
75
  description,
75
76
  enumValues: void 0,
76
77
  numberConstraints: void 0,
78
+ stringConstraints: void 0,
77
79
  elementSchema: void 0,
80
+ separator: void 0,
81
+ unique: false,
82
+ pathChecks: void 0,
83
+ valueHint: void 0,
78
84
  prompt: void 0,
79
85
  parseFn: void 0,
80
86
  deprecated: void 0,
81
- propagate: false
87
+ propagate: false,
88
+ negation: void 0,
89
+ duplicates: "last"
82
90
  };
83
91
  }
84
92
  /**
@@ -114,6 +122,20 @@ function walkCommandTree(topLevel, ancestorSchemas = []) {
114
122
  return nodes;
115
123
  }
116
124
  /**
125
+ * Effective negated long-form spelling for user-facing suggestion lists.
126
+ *
127
+ * Returns the negated spelling without the `--` prefix (e.g. `no-verbose`)
128
+ * when the flag is negatable and the negation is not hidden; `undefined`
129
+ * otherwise. Negated spellings are long-only and take no value, so they only
130
+ * belong in suggestion lists — never in value-flag (operand-skip) patterns.
131
+ *
132
+ * @internal
133
+ */
134
+ function getVisibleNegatedName(name, schema) {
135
+ if (schema.negation === void 0 || schema.negation.hidden) return void 0;
136
+ return getFlagNegatedName(name, schema);
137
+ }
138
+ /**
117
139
  * Sanitize a string for use as a shell function identifier.
118
140
  * Replaces non-alphanumeric/underscore characters with underscores.
119
141
  * When sanitization changes the name, appends a short stable hash suffix so
@@ -151,4 +173,4 @@ function quoteShellArg(value) {
151
173
  return `'${value.replace(/'/g, "'\\''")}'`;
152
174
  }
153
175
  //#endregion
154
- export { quoteShellArg, resolveRootCompletionSurface, sanitizeShellIdentifier, versionTag, walkCommandTree };
176
+ export { getVisibleNegatedName, quoteShellArg, resolveRootCompletionSurface, sanitizeShellIdentifier, versionTag, walkCommandTree };
@@ -1,6 +1,5 @@
1
1
  import { CompletionOptions } from "./shared.mjs";
2
2
  import { CLISchema } from "../../cli/index.mjs";
3
-
4
3
  //#region src/core/completion/shells/zsh.d.ts
5
4
  /**
6
5
  * Generate a zsh completion script for the CLI.
@@ -1,6 +1,7 @@
1
- import { getFlagAliasNames } from "../../schema/flag.mjs";
2
- import { quoteShellArg, resolveRootCompletionSurface, sanitizeShellIdentifier, versionTag, walkCommandTree } from "./shared.mjs";
3
1
  import { CLIError } from "../../errors/index.mjs";
2
+ import { getFlagAliasNames } from "../../schema/flag.mjs";
3
+ import { flagExpectsValue } from "../../parse/index.mjs";
4
+ import { getVisibleNegatedName, quoteShellArg, resolveRootCompletionSurface, sanitizeShellIdentifier, versionTag, walkCommandTree } from "./shared.mjs";
4
5
  //#region src/core/completion/shells/zsh.ts
5
6
  /**
6
7
  * Generate a zsh completion script for the CLI.
@@ -202,6 +203,9 @@ function escapeZshDescription(value) {
202
203
  * - `'(-s --name --alias)'{-s,--name,--alias}'[description]'` for flags with
203
204
  * visible aliases
204
205
  *
206
+ * A visible negated spelling (`--no-name`) joins the flag's form group — the
207
+ * two spellings are one logical flag, so completing one excludes the other.
208
+ *
205
209
  * @internal
206
210
  */
207
211
  function buildZshFlagSpecsFromFlags(flags) {
@@ -211,13 +215,16 @@ function buildZshFlagSpecsFromFlags(flags) {
211
215
  const longFlag = `--${name}`;
212
216
  const shortFlags = getFlagAliasNames(schema, { kind: "short" }).map((alias) => `-${alias}`);
213
217
  const longAliases = getFlagAliasNames(schema, { kind: "long" }).map((alias) => `--${alias}`);
218
+ const negated = getVisibleNegatedName(name, schema);
219
+ const negatedForms = negated !== void 0 ? [`--${negated}`] : [];
214
220
  const allForms = [
215
221
  ...shortFlags,
216
222
  longFlag,
217
- ...longAliases
223
+ ...longAliases,
224
+ ...negatedForms
218
225
  ];
219
226
  let valuePart = "";
220
- if (schema.kind === "boolean") {} else if (schema.kind === "enum" && schema.enumValues !== void 0) valuePart = `:value:(${schema.enumValues.map(escapeZshEnumValue).join(" ")})`;
227
+ if (!flagExpectsValue(schema)) {} else if (schema.kind === "enum" && schema.enumValues !== void 0) valuePart = `:value:(${schema.enumValues.map(escapeZshEnumValue).join(" ")})`;
221
228
  else valuePart = ":value:";
222
229
  if (allForms.length > 1) {
223
230
  const escapedForms = allForms.map(escapeZshCasePatternValue).join(",");
@@ -1,6 +1,5 @@
1
1
  import { RuntimeAdapter } from "../../runtime/adapter.mjs";
2
- import { ManifestDiscoveryOptions, PackageJsonAdapter, PackageJsonData, PackageRepository, discoverManifest, discoverPackageJson, inferCliName, packageRepositoryUrl } from "./package-json.mjs";
3
-
2
+ import { ManifestDiscoveryOptions, PackageJsonAdapter, PackageJsonData, PackageRepository, PackageRepositoryUrlOptions, discoverManifest, discoverPackageJson, inferCliName, packageRepositoryUrl } from "./package-json.mjs";
4
3
  //#region src/core/config/index.d.ts
5
4
  /**
6
5
  * Format loader — parses file content into a config object.
@@ -158,4 +157,4 @@ declare function discoverConfig(appName: string, adapter: ConfigAdapter, options
158
157
  */
159
158
  declare function configFormat(extensions: readonly string[], parse: (content: string) => unknown): FormatLoader;
160
159
  //#endregion
161
- export { type ConfigAdapter, type ConfigDiscoveryOptions, type ConfigDiscoveryResult, type ConfigFound, type ConfigNotFound, type FormatLoader, type ManifestDiscoveryOptions, type PackageJsonAdapter, type PackageJsonData, type PackageRepository, buildConfigSearchPaths, configFormat, discoverConfig, discoverManifest, discoverPackageJson, inferCliName, packageRepositoryUrl };
160
+ export { type ConfigAdapter, type ConfigDiscoveryOptions, type ConfigDiscoveryResult, type ConfigFound, type ConfigNotFound, type FormatLoader, type ManifestDiscoveryOptions, type PackageJsonAdapter, type PackageJsonData, type PackageRepository, type PackageRepositoryUrlOptions, buildConfigSearchPaths, configFormat, discoverConfig, discoverManifest, discoverPackageJson, inferCliName, packageRepositoryUrl };
@@ -1,5 +1,5 @@
1
1
  import { CLIError } from "../errors/index.mjs";
2
- import "./package-json.mjs";
2
+ import { discoverManifest, discoverPackageJson, inferCliName, packageRepositoryUrl } from "./package-json.mjs";
3
3
  //#region src/core/config/index.ts
4
4
  /**
5
5
  * Config file discovery and loading.
@@ -243,4 +243,4 @@ function configFormat(extensions, parse) {
243
243
  };
244
244
  }
245
245
  //#endregion
246
- export { buildConfigSearchPaths, configFormat, discoverConfig };
246
+ export { buildConfigSearchPaths, configFormat, discoverConfig, discoverManifest, discoverPackageJson, inferCliName, packageRepositoryUrl };
@@ -1,5 +1,4 @@
1
1
  import { RuntimeAdapter } from "../../runtime/adapter.mjs";
2
-
3
2
  //#region src/core/config/package-json.d.ts
4
3
  /**
5
4
  * Object form of the package.json `repository` field
@@ -133,6 +132,20 @@ declare function discoverManifest(adapter: PackageJsonAdapter, options?: Manifes
133
132
  * ```
134
133
  */
135
134
  declare function discoverPackageJson(adapter: PackageJsonAdapter, startDir?: string): Promise<PackageJsonData | null>;
135
+ /** Options for {@link packageRepositoryUrl}. */
136
+ interface PackageRepositoryUrlOptions {
137
+ /**
138
+ * Throw a `CLIError` (code `INVALID_REPOSITORY`) instead of returning
139
+ * `undefined` when the `repository` field is absent or not a recognisable
140
+ * locator. With `require: true` the return type narrows to `string`, so
141
+ * callers that know their manifest carries a valid repository need no
142
+ * assertion — and a bad manifest fails fast with a real message instead
143
+ * of propagating `undefined`.
144
+ *
145
+ * @defaultValue `false`
146
+ */
147
+ readonly require?: boolean;
148
+ }
136
149
  /**
137
150
  * Resolve a package's `repository` field to a browsable `https://` URL.
138
151
  *
@@ -143,15 +156,25 @@ declare function discoverPackageJson(adapter: PackageJsonAdapter, startDir?: str
143
156
  * - shorthands: `github:u/r`, `gitlab:u/r`, `bitbucket:u/r`, and bare `u/r`
144
157
  * (GitHub, per npm convention)
145
158
  *
146
- * Returns `undefined` when the field is absent or unrecognised.
159
+ * Returns `undefined` when the field is absent or unrecognised — or, with
160
+ * `{ require: true }`, throws instead and the return type is `string`.
161
+ * (The narrowing cannot key off the input type alone: a present `repository`
162
+ * may still be an empty string, a url-less object, or an unparseable
163
+ * locator, so the `string` promise is backed by the runtime check.)
147
164
  *
148
165
  * @example
149
166
  * ```ts
150
167
  * packageRepositoryUrl({ repository: 'git+https://github.com/u/r.git' });
151
168
  * // 'https://github.com/u/r'
169
+ *
170
+ * const url: string = packageRepositoryUrl(pkg, { require: true });
171
+ * // throws CLIError when pkg.repository is missing or unrecognised
152
172
  * ```
153
173
  */
154
- declare function packageRepositoryUrl(pkg: PackageJsonData): string | undefined;
174
+ declare function packageRepositoryUrl(pkg: PackageJsonData, options: PackageRepositoryUrlOptions & {
175
+ readonly require: true;
176
+ }): string;
177
+ declare function packageRepositoryUrl(pkg: PackageJsonData, options?: PackageRepositoryUrlOptions): string | undefined;
155
178
  /**
156
179
  * Infer the CLI binary name from manifest data.
157
180
  *
@@ -183,4 +206,4 @@ declare function inferCliName(pkg: PackageJsonData, options?: {
183
206
  readonly stripScope?: boolean;
184
207
  }): string | undefined;
185
208
  //#endregion
186
- export { type ManifestDiscoveryOptions, type PackageJsonAdapter, type PackageJsonData, type PackageRepository, discoverManifest, discoverPackageJson, inferCliName, packageRepositoryUrl };
209
+ export { type ManifestDiscoveryOptions, type PackageJsonAdapter, type PackageJsonData, type PackageRepository, type PackageRepositoryUrlOptions, discoverManifest, discoverPackageJson, inferCliName, packageRepositoryUrl };