@kjanat/dreamcli 2.4.1 → 3.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 (94) hide show
  1. package/CHANGELOG.md +169 -1
  2. package/README.md +14 -7
  3. package/dist/core/cli/index.d.mts +283 -81
  4. package/dist/core/cli/index.mjs +1 -1
  5. package/dist/core/cli/planner.d.mts +27 -5
  6. package/dist/core/cli/planner.mjs +1 -1
  7. package/dist/core/cli/root-help.d.mts +16 -2
  8. package/dist/core/cli/root-help.mjs +3 -5
  9. package/dist/core/cli/root-surface.d.mts +18 -3
  10. package/dist/core/cli/root-surface.mjs +1 -1
  11. package/dist/core/cli/runtime-preflight.d.mts +31 -5
  12. package/dist/core/cli/runtime-preflight.mjs +1 -1
  13. package/dist/core/completion/index.d.mts +32 -1
  14. package/dist/core/completion/index.mjs +1 -1
  15. package/dist/core/completion/shells/shared.d.mts +10 -0
  16. package/dist/core/completion/shells/shared.mjs +1 -1
  17. package/dist/core/config/index.d.mts +2 -2
  18. package/dist/core/config/package-json.d.mts +93 -20
  19. package/dist/core/config/package-json.mjs +3 -1
  20. package/dist/core/help/index.d.mts +45 -1
  21. package/dist/core/help/index.mjs +6 -6
  22. package/dist/core/json-schema/index.mjs +1 -1
  23. package/dist/core/json-schema/meta-descriptions.generated.d.mts +38 -38
  24. package/dist/core/parse/index.d.mts +15 -1
  25. package/dist/core/parse/index.mjs +1 -1
  26. package/dist/core/prompt/index.d.mts +11 -3
  27. package/dist/core/prompt/index.mjs +3 -3
  28. package/dist/core/resolve/coerce.mjs +1 -1
  29. package/dist/core/resolve/flags.mjs +1 -1
  30. package/dist/core/resolve/property.d.mts +2 -0
  31. package/dist/core/resolve/property.mjs +1 -1
  32. package/dist/core/schema/arg.d.mts +90 -10
  33. package/dist/core/schema/arg.mjs +1 -1
  34. package/dist/core/schema/command.d.mts +3 -1
  35. package/dist/core/schema/flag.d.mts +92 -2
  36. package/dist/core/schema/flag.mjs +1 -1
  37. package/dist/core/schema/index.d.mts +2 -1
  38. package/dist/core/schema/number-constraints.d.mts +96 -0
  39. package/dist/core/schema/number-constraints.mjs +1 -0
  40. package/dist/core/schema/prompt.d.mts +15 -0
  41. package/dist/core/schema/run.d.mts +4 -4
  42. package/dist/core/testkit/index.d.mts +9 -5
  43. package/dist/core/testkit/index.mjs +1 -1
  44. package/dist/index.d.mts +4 -3
  45. package/dist/index.mjs +1 -1
  46. package/dist/runtime/auto.mjs +1 -1
  47. package/dist/runtime/bun.mjs +1 -1
  48. package/dist/runtime/deno.mjs +2 -2
  49. package/dist/runtime/node.mjs +2 -2
  50. package/dist/version.mjs +1 -1
  51. package/examples/basic.ts +5 -1
  52. package/examples/gh/package.json +2 -7
  53. package/examples/pwsh-demo/package.json +1 -7
  54. package/examples/pwsh-demo/src/main.test.ts +1 -4
  55. package/examples/pwsh-demo/src/main.ts +14 -4
  56. package/examples/transport-launcher.ts +85 -0
  57. package/package.json +15 -24
  58. package/src/core/cli/dispatch.ts +7 -1
  59. package/src/core/cli/index.ts +521 -122
  60. package/src/core/cli/planner.ts +192 -23
  61. package/src/core/cli/root-help.ts +195 -105
  62. package/src/core/cli/root-surface.ts +25 -12
  63. package/src/core/cli/runtime-preflight.ts +43 -8
  64. package/src/core/completion/index.ts +50 -0
  65. package/src/core/completion/shells/powershell.ts +2 -2
  66. package/src/core/completion/shells/shared.ts +30 -3
  67. package/src/core/config/index.ts +12 -2
  68. package/src/core/config/package-json.ts +250 -41
  69. package/src/core/execution/index.ts +1 -4
  70. package/src/core/help/index.ts +57 -10
  71. package/src/core/json-schema/index.ts +23 -4
  72. package/src/core/json-schema/meta-descriptions.generated.ts +115 -98
  73. package/src/core/parse/index.ts +62 -1
  74. package/src/core/prompt/index.ts +54 -14
  75. package/src/core/resolve/coerce.ts +73 -5
  76. package/src/core/resolve/flags.ts +14 -0
  77. package/src/core/resolve/property.ts +4 -4
  78. package/src/core/schema/arg.ts +125 -3
  79. package/src/core/schema/command.ts +3 -1
  80. package/src/core/schema/flag.ts +120 -4
  81. package/src/core/schema/index.ts +5 -0
  82. package/src/core/schema/number-constraints.ts +153 -0
  83. package/src/core/schema/prompt.ts +15 -0
  84. package/src/core/schema/run.ts +4 -4
  85. package/src/core/testkit/index.ts +32 -8
  86. package/src/index.ts +8 -0
  87. package/src/runtime/auto.ts +0 -24
  88. package/src/runtime/bun.ts +0 -7
  89. package/src/runtime/deno.ts +0 -2
  90. package/src/runtime/node.ts +0 -11
  91. package/src/runtime/support.ts +1 -59
  92. package/src/schema.ts +16 -0
  93. package/dist/runtime/support.d.mts +0 -42
  94. package/dist/runtime/support.mjs +0 -1
@@ -29,13 +29,26 @@ interface RootSurfaceSchemaLike {
29
29
  /**
30
30
  * Normalized root shape shared by help and completion logic.
31
31
  *
32
+ * Since v0.3 the default command is a distinct root *surface* rather than a
33
+ * named subcommand: `.default()` no longer registers it under
34
+ * {@link RootSurfaceSchemaLike.commands}. To stay robust against callers that
35
+ * still place the default in the command list (e.g. hand-built test schemas),
36
+ * {@link resolveRootSurface} always derives {@link RootSurface.visibleSubcommands}
37
+ * by excluding the default command from the visible command list.
38
+ *
32
39
  * @internal
33
40
  */
34
41
  interface RootSurface {
42
+ /** All visible top-level commands as declared in `schema.commands`. */
35
43
  readonly visibleCommands: readonly CommandSchema[];
44
+ /** Visible real subcommands — `visibleCommands` minus the default command. */
45
+ readonly visibleSubcommands: readonly CommandSchema[];
46
+ /** The visible default command, or `undefined` when none exists or it is hidden. */
36
47
  readonly visibleDefaultCommand: CommandSchema | undefined;
37
- readonly hasSingleVisibleDefault: boolean;
38
- readonly hasVisibleSiblingCommands: boolean;
48
+ /** Whether a visible default command exists. */
49
+ readonly hasVisibleDefault: boolean;
50
+ /** Whether any visible real subcommands exist (the default does not count). */
51
+ readonly hasVisibleSubcommands: boolean;
39
52
  }
40
53
 
41
54
  /**
@@ -43,7 +56,9 @@ interface RootSurface {
43
56
  *
44
57
  * Hidden commands are excluded from the visible command list. Hidden
45
58
  * default commands remain executable, but are not surfaced through
46
- * help or completions.
59
+ * help or completions. The default command is reported separately from the
60
+ * real subcommands so help and completion can render it as the root surface
61
+ * instead of echoing it as a pseudo-subcommand.
47
62
  *
48
63
  * @internal
49
64
  */
@@ -54,19 +69,17 @@ function resolveRootSurface(schema: RootSurfaceSchemaLike): RootSurface {
54
69
  const rawDefaultCommand = schema.defaultCommand?.schema;
55
70
  const visibleDefaultCommand =
56
71
  rawDefaultCommand !== undefined && !rawDefaultCommand.hidden ? rawDefaultCommand : undefined;
57
- const hasSingleVisibleDefault =
58
- visibleDefaultCommand !== undefined &&
59
- visibleCommands.length === 1 &&
60
- visibleCommands[0]?.name === visibleDefaultCommand.name;
61
- const hasVisibleSiblingCommands =
62
- visibleDefaultCommand !== undefined &&
63
- visibleCommands.some((command) => command.name !== visibleDefaultCommand.name);
72
+ const visibleSubcommands =
73
+ visibleDefaultCommand !== undefined
74
+ ? visibleCommands.filter((command) => command.name !== visibleDefaultCommand.name)
75
+ : visibleCommands;
64
76
 
65
77
  return {
66
78
  visibleCommands,
79
+ visibleSubcommands,
67
80
  visibleDefaultCommand,
68
- hasSingleVisibleDefault,
69
- hasVisibleSiblingCommands,
81
+ hasVisibleDefault: visibleDefaultCommand !== undefined,
82
+ hasVisibleSubcommands: visibleSubcommands.length > 0,
70
83
  };
71
84
  }
72
85
 
@@ -9,10 +9,11 @@
9
9
  * @internal
10
10
  */
11
11
 
12
+ import type { CompletionOptions, Shell } from '#internals/core/completion/index.ts';
12
13
  import type { FormatLoader } from '#internals/core/config/index.ts';
13
14
  import { discoverConfig } from '#internals/core/config/index.ts';
14
15
  import type { PackageJsonData } from '#internals/core/config/package-json.ts';
15
- import { discoverPackageJson, inferCliName } from '#internals/core/config/package-json.ts';
16
+ import { discoverManifest, inferCliName } from '#internals/core/config/package-json.ts';
16
17
  import { CLIError, ParseError } from '#internals/core/errors/index.ts';
17
18
  import type { Verbosity } from '#internals/core/output/index.ts';
18
19
  import { parse } from '#internals/core/parse/index.ts';
@@ -33,12 +34,23 @@ interface RuntimeConfigSettings {
33
34
  readonly loaders: readonly FormatLoader[] | undefined;
34
35
  }
35
36
 
36
- /** Package.json discovery settings extracted from CLISchema. @internal */
37
- interface RuntimePackageJsonSettings {
38
- /** Whether to infer the CLI binary name from `package.json` `bin` field. */
37
+ /**
38
+ * Manifest discovery settings extracted from CLISchema for preflight use.
39
+ *
40
+ * Mirrors the public `ResolvedManifestSettings` shape (consumed structurally),
41
+ * named with the `Runtime` prefix to match its {@link RuntimeConfigSettings}
42
+ * sibling and avoid colliding with the exported public type.
43
+ * @internal
44
+ */
45
+ interface RuntimeManifestSettings {
46
+ /** Whether to infer the CLI binary name from `bin` keys or `name`. */
39
47
  readonly inferName: boolean;
48
+ /** Strip a leading `@scope/` from the inferred `name` fallback. */
49
+ readonly stripScope: boolean;
40
50
  /** Explicit anchor (resolved path) for discovery; `undefined` falls back to `adapter.cwd`. */
41
51
  readonly from: string | undefined;
52
+ /** Candidate manifest filenames in priority order. */
53
+ readonly files: readonly string[];
42
54
  /** Pre-loaded data; when set, discovery is skipped entirely. */
43
55
  readonly data: PackageJsonData | undefined;
44
56
  }
@@ -66,11 +78,25 @@ interface RuntimePreflightSchemaLike {
66
78
  /** Config file discovery settings; `undefined` disables config loading. */
67
79
  readonly configSettings: RuntimeConfigSettings | undefined;
68
80
  /** Package.json discovery settings; `undefined` disables package.json inference. */
69
- readonly packageJsonSettings: RuntimePackageJsonSettings | undefined;
81
+ readonly packageJsonSettings: RuntimeManifestSettings | undefined;
70
82
  /** Root-help header link targets; `undefined` fields may be derived from package.json. */
71
83
  readonly helpLinks: HelpLinks | undefined;
72
- /** Whether `.completions()` registered the built-in completions command. */
84
+ /** Whether `.completions()` registered the built-in completions command/flag. */
73
85
  readonly hasBuiltInCompletions: boolean;
86
+ /** Eager `--completions <shell>` flag config; `undefined` disables interception. */
87
+ readonly completionsFlag:
88
+ | { readonly shells: readonly Shell[]; readonly options: CompletionOptions | undefined }
89
+ | undefined;
90
+ /** Consumer-configured root-help defaults. */
91
+ readonly helpConfig:
92
+ | {
93
+ readonly inlineDefault?: boolean;
94
+ readonly showDefaultInCommands?: boolean;
95
+ readonly footer?: boolean;
96
+ readonly width?: number;
97
+ readonly hyperlinks?: boolean;
98
+ }
99
+ | undefined;
74
100
  /** Plugins forwarded into the execution pipeline. */
75
101
  readonly plugins: readonly CLIPlugin[];
76
102
  }
@@ -253,6 +279,7 @@ function invocationNeedsStdin(
253
279
  case 'needs-subcommand':
254
280
  case 'root-help':
255
281
  case 'root-version':
282
+ case 'root-completions':
256
283
  return false;
257
284
  }
258
285
  }
@@ -287,10 +314,18 @@ async function applyPackageJsonDiscovery(
287
314
  ? await (async (): Promise<RuntimePreflightSchemaLike> => {
288
315
  // Pre-loaded data short-circuits filesystem discovery entirely.
289
316
  const pkg =
290
- packageJsonSettings.data ?? (await discoverPackageJson(adapter, packageJsonSettings.from));
317
+ packageJsonSettings.data ??
318
+ (await discoverManifest(adapter, {
319
+ ...(packageJsonSettings.from !== undefined
320
+ ? { startDir: packageJsonSettings.from }
321
+ : {}),
322
+ files: packageJsonSettings.files,
323
+ }));
291
324
  if (pkg === null) return schema;
292
325
 
293
- const inferredName = packageJsonSettings.inferName ? inferCliName(pkg) : undefined;
326
+ const inferredName = packageJsonSettings.inferName
327
+ ? inferCliName(pkg, { stripScope: packageJsonSettings.stripScope })
328
+ : undefined;
294
329
  return {
295
330
  ...schema,
296
331
  ...(schema.version === undefined && pkg.version !== undefined
@@ -41,6 +41,54 @@ const SHELLS: Readonly<readonly ['bash', 'zsh', 'fish', 'powershell']> = Object.
41
41
  'powershell',
42
42
  ] as const satisfies readonly ['bash', 'zsh', 'fish', 'powershell']);
43
43
 
44
+ // --- Shell token normalization
45
+
46
+ /**
47
+ * Normalize a raw shell token — a bare name (`zsh`), a `$SHELL` path
48
+ * (`/bin/zsh`), or a Windows executable (`…\pwsh.exe`) — to a supported
49
+ * {@link Shell}, or `undefined` when it does not map to one.
50
+ *
51
+ * Mirrors the matching used by the `completions` subcommand so the subcommand
52
+ * and the eager `--completions <shell>` flag accept exactly the same inputs.
53
+ *
54
+ * @param raw - User-supplied shell token or interpreter path.
55
+ * @returns The resolved {@link Shell}, or `undefined` if unrecognized.
56
+ */
57
+ function normalizeShell(raw: string): Shell | undefined {
58
+ const segments = raw.split(/[\\/]/);
59
+ const basename = segments[segments.length - 1] ?? raw;
60
+ const name = basename.replace(/\.(?:exe|cmd|bat)$/i, '');
61
+ if (name === 'pwsh') return 'powershell';
62
+ return (SHELLS as readonly string[]).includes(name) ? (name as Shell) : undefined;
63
+ }
64
+
65
+ /**
66
+ * Auto-detect the current shell from environment variables.
67
+ *
68
+ * Resolution order:
69
+ * 1. `$SHELL` parsed as an interpreter path (`/bin/zsh` → `zsh`). It wins when
70
+ * it names a shell we support — a pwsh session launched from bash inherits
71
+ * `SHELL=/bin/bash`, and the login shell the user opted into should be
72
+ * honored over the fallback.
73
+ * 2. Otherwise, the presence of `$PSModulePath` signals PowerShell. PowerShell
74
+ * never sets `$SHELL` on any platform but always exports `PSModulePath` for
75
+ * module discovery, so it is the reliable pwsh signal.
76
+ *
77
+ * Returns `undefined` when no signal resolves, leaving the caller to ask the
78
+ * user for an explicit shell.
79
+ *
80
+ * @param env - Environment record (e.g. `process.env` or an adapter's env).
81
+ * @returns The detected {@link Shell}, or `undefined`.
82
+ */
83
+ function detectShell(env: Readonly<Record<string, string | undefined>>): Shell | undefined {
84
+ const shellVar = env.SHELL;
85
+ const fromShell =
86
+ shellVar !== undefined && shellVar !== '' ? normalizeShell(shellVar) : undefined;
87
+ if (fromShell !== undefined) return fromShell;
88
+ if (env.PSModulePath !== undefined) return 'powershell';
89
+ return undefined;
90
+ }
91
+
44
92
  // --- Shell-agnostic dispatch
45
93
 
46
94
  /**
@@ -84,5 +132,7 @@ export {
84
132
  generateFishCompletion,
85
133
  generatePowerShellCompletion,
86
134
  generateZshCompletion,
135
+ detectShell,
136
+ normalizeShell,
87
137
  SHELLS,
88
138
  };
@@ -318,14 +318,14 @@ function emitPowerShellHelpers(lines: string[], helperPrefix: string, dataVarNam
318
318
  lines.push(`function ${helperPrefix}_FormatCompletionValue {`);
319
319
  lines.push('\tparam([string]$Value)');
320
320
  lines.push('\tif ($Value.Length -eq 0) {');
321
- lines.push("\t\treturn \"''\"");
321
+ lines.push('\t\treturn "\'\'"');
322
322
  lines.push('\t}');
323
323
  lines.push('');
324
324
  lines.push("\tif ($Value -match '^[a-zA-Z0-9_./:\\\\-]+$') {");
325
325
  lines.push('\t\treturn $Value');
326
326
  lines.push('\t}');
327
327
  lines.push('');
328
- lines.push("\treturn \"'$([CodeGeneration]::EscapeSingleQuotedStringContent($Value))'\"");
328
+ lines.push('\treturn "\'$([CodeGeneration]::EscapeSingleQuotedStringContent($Value))\'"');
329
329
  lines.push('}');
330
330
  lines.push('');
331
331
  lines.push(`function ${helperPrefix}_MatchesCompletionPrefix {`);
@@ -54,6 +54,16 @@ interface CompletionOptions {
54
54
  * ```
55
55
  */
56
56
  readonly functionPrefix?: string;
57
+ /**
58
+ * Where the built-in shell completion is exposed.
59
+ *
60
+ * - `'command'` registers a `completions` subcommand (the default).
61
+ * - `'flag'` exposes an eager `--completions <shell>` flag on the CLI root
62
+ * instead, keeping the root free of a `completions` subcommand.
63
+ *
64
+ * @defaultValue `'command'`
65
+ */
66
+ readonly as?: 'command' | 'flag';
57
67
  /**
58
68
  * Controls which root-level surface shell completion exposes when a
59
69
  * default command exists.
@@ -109,13 +119,29 @@ function resolveRootCompletionSurface(
109
119
  const rootSurface = resolveRootSurface(schema);
110
120
  const rootFlags = createRootFlags(schema.version !== undefined);
111
121
  const defaultFlags = rootSurface.visibleDefaultCommand?.flags ?? {};
122
+ // Default flags surface at the root either always (`surface`) or only when
123
+ // the default is the sole surface (`subcommands`).
112
124
  const includeDefaultFlags =
113
125
  rootMode === 'surface'
114
- ? rootSurface.visibleDefaultCommand !== undefined
115
- : rootSurface.hasSingleVisibleDefault;
126
+ ? rootSurface.hasVisibleDefault
127
+ : rootSurface.hasVisibleDefault && !rootSurface.hasVisibleSubcommands;
128
+
129
+ // Generated completion scripts keep treating the default command as part of
130
+ // the root surface (a walkable node carrying its own flags/args), regardless
131
+ // of whether it is registered under `commands` — since v0.3 `.default()` keeps
132
+ // it only in `defaultCommand`. Re-add it here so the per-shell generators,
133
+ // which build their dispatch machinery from this list, behave unchanged.
134
+ const defaultCommand = rootSurface.visibleDefaultCommand;
135
+ const alreadyListed =
136
+ defaultCommand !== undefined &&
137
+ rootSurface.visibleCommands.some((c) => c.name === defaultCommand.name);
138
+ const visibleCommands =
139
+ defaultCommand !== undefined && !alreadyListed
140
+ ? [defaultCommand, ...rootSurface.visibleCommands]
141
+ : rootSurface.visibleCommands;
116
142
 
117
143
  return {
118
- visibleCommands: rootSurface.visibleCommands,
144
+ visibleCommands,
119
145
  visibleDefaultCommand: rootSurface.visibleDefaultCommand,
120
146
  rootFlags,
121
147
  defaultFlags,
@@ -154,6 +180,7 @@ function createSyntheticRootFlag(description: string): FlagSchema {
154
180
  configPath: undefined,
155
181
  description,
156
182
  enumValues: undefined,
183
+ numberConstraints: undefined,
157
184
  elementSchema: undefined,
158
185
  prompt: undefined,
159
186
  parseFn: undefined,
@@ -394,8 +394,18 @@ function configFormat(
394
394
 
395
395
  // --- Exports
396
396
 
397
- export type { PackageJsonAdapter, PackageJsonData, PackageRepository } from './package-json.ts';
398
- export { discoverPackageJson, inferCliName, packageRepositoryUrl } from './package-json.ts';
397
+ export type {
398
+ ManifestDiscoveryOptions,
399
+ PackageJsonAdapter,
400
+ PackageJsonData,
401
+ PackageRepository,
402
+ } from './package-json.ts';
403
+ export {
404
+ discoverManifest,
405
+ discoverPackageJson,
406
+ inferCliName,
407
+ packageRepositoryUrl,
408
+ } from './package-json.ts';
399
409
  export type {
400
410
  ConfigAdapter,
401
411
  ConfigDiscoveryOptions,