@kjanat/dreamcli 3.0.0 → 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.
- package/CHANGELOG.md +967 -1
- package/README.md +9 -3
- package/dist/core/cli/builtins.d.mts +47 -0
- package/dist/core/cli/builtins.mjs +135 -0
- package/dist/core/cli/compiled.d.mts +29 -0
- package/dist/core/cli/compiled.mjs +76 -0
- package/dist/core/cli/dispatch.d.mts +9 -85
- package/dist/core/cli/help-links.d.mts +2 -14
- package/dist/core/cli/index.d.mts +282 -101
- package/dist/core/cli/index.mjs +497 -264
- package/dist/core/cli/planner.d.mts +13 -86
- package/dist/core/cli/planner.mjs +47 -30
- package/dist/core/cli/plugin.d.mts +1 -1
- package/dist/core/cli/propagate.mjs +1 -1
- package/dist/core/cli/reserved-flags.d.mts +1 -0
- package/dist/core/cli/reserved-flags.mjs +158 -0
- package/dist/core/cli/root-help.d.mts +1 -47
- package/dist/core/cli/root-help.mjs +37 -47
- package/dist/core/cli/root-output-flags.d.mts +1 -0
- package/dist/core/cli/root-output-flags.mjs +169 -0
- package/dist/core/cli/root-surface.d.mts +1 -68
- package/dist/core/cli/root-surface.mjs +2 -2
- package/dist/core/cli/runtime-preflight.d.mts +1 -199
- package/dist/core/cli/runtime-preflight.mjs +67 -17
- package/dist/core/completion/index.d.mts +2 -2
- package/dist/core/completion/shells/bash.d.mts +0 -1
- package/dist/core/completion/shells/bash.mjs +2 -1
- package/dist/core/completion/shells/fish.d.mts +0 -1
- package/dist/core/completion/shells/fish.mjs +2 -1
- package/dist/core/completion/shells/powershell.d.mts +0 -1
- package/dist/core/completion/shells/powershell.mjs +2 -1
- package/dist/core/completion/shells/shared.d.mts +3 -114
- package/dist/core/completion/shells/shared.mjs +9 -39
- package/dist/core/completion/shells/zsh.d.mts +0 -1
- package/dist/core/completion/shells/zsh.mjs +2 -1
- package/dist/core/config/index.d.mts +3 -3
- package/dist/core/config/index.mjs +2 -2
- package/dist/core/config/package-json.d.mts +2 -33
- package/dist/core/config/package-json.mjs +1 -34
- package/dist/core/errors/index.d.mts +7 -7
- package/dist/core/execution/index.d.mts +1 -48
- package/dist/core/execution/index.mjs +42 -27
- package/dist/core/help/ansi.d.mts +0 -11
- package/dist/core/help/index.d.mts +3 -35
- package/dist/core/help/index.mjs +29 -6
- package/dist/core/help/theme.d.mts +1 -21
- package/dist/core/json-schema/index.d.mts +279 -10
- package/dist/core/json-schema/index.mjs +482 -237
- package/dist/core/json-schema/meta-descriptions.generated.d.mts +79 -7
- package/dist/core/json-schema/meta-descriptions.generated.mjs +40 -6
- package/dist/core/output/activity.d.mts +1 -193
- package/dist/core/output/activity.mjs +1 -1
- package/dist/core/output/bind.d.mts +1 -37
- package/dist/core/output/contracts.d.mts +7 -13
- package/dist/core/output/contracts.mjs +1 -1
- package/dist/core/output/display-value.d.mts +1 -19
- package/dist/core/output/index.d.mts +5 -187
- package/dist/core/output/index.mjs +44 -9
- package/dist/core/output/renderers.d.mts +1 -45
- package/dist/core/output/writer.d.mts +0 -1
- package/dist/core/parse/index.d.mts +27 -5
- package/dist/core/parse/index.mjs +350 -227
- package/dist/core/parse/occurrences.d.mts +89 -0
- package/dist/core/parse/occurrences.mjs +114 -0
- package/dist/core/prompt/index.d.mts +3 -3
- package/dist/core/read-flags/index.d.mts +150 -0
- package/dist/core/read-flags/index.mjs +217 -0
- package/dist/core/resolve/args.d.mts +35 -4
- package/dist/core/resolve/args.mjs +132 -55
- package/dist/core/resolve/coerce.d.mts +66 -9
- package/dist/core/resolve/coerce.mjs +834 -270
- package/dist/core/resolve/config.d.mts +1 -10
- package/dist/core/resolve/contracts.d.mts +67 -44
- package/dist/core/resolve/errors.mjs +29 -21
- package/dist/core/resolve/flags.d.mts +36 -9
- package/dist/core/resolve/flags.mjs +129 -151
- package/dist/core/resolve/index.d.mts +8 -6
- package/dist/core/resolve/index.mjs +51 -18
- package/dist/core/resolve/path-checks.d.mts +47 -0
- package/dist/core/resolve/path-checks.mjs +102 -0
- package/dist/core/resolve/redaction.d.mts +12 -0
- package/dist/core/resolve/redaction.mjs +14 -0
- package/dist/core/resolve/stages.d.mts +85 -0
- package/dist/core/resolve/stages.mjs +170 -0
- package/dist/core/resolve/standard.d.mts +1 -24
- package/dist/core/resolve/standard.mjs +141 -43
- package/dist/core/schema/activity.d.mts +16 -16
- package/dist/core/schema/arg.d.mts +849 -71
- package/dist/core/schema/arg.mjs +727 -54
- package/dist/core/schema/brand.d.mts +17 -0
- package/dist/core/schema/cardinality.d.mts +301 -0
- package/dist/core/schema/cardinality.mjs +514 -0
- package/dist/core/schema/command.d.mts +181 -112
- package/dist/core/schema/command.mjs +305 -42
- package/dist/core/schema/flag.d.mts +515 -173
- package/dist/core/schema/flag.mjs +576 -78
- package/dist/core/schema/index.d.mts +11 -8
- package/dist/core/schema/index.mjs +10 -0
- package/dist/core/schema/middleware.d.mts +15 -12
- package/dist/core/schema/number-constraints.d.mts +5 -5
- package/dist/core/schema/prompt.d.mts +4 -4
- package/dist/core/schema/provenance.d.mts +99 -0
- package/dist/core/schema/provenance.mjs +28 -0
- package/dist/core/schema/run.d.mts +21 -60
- package/dist/core/schema/source.d.mts +179 -0
- package/dist/core/schema/source.mjs +206 -0
- package/dist/core/schema/standard.d.mts +12 -19
- package/dist/core/schema/stdin.d.mts +87 -0
- package/dist/core/schema/stdin.mjs +91 -0
- package/dist/core/schema/string-constraints.d.mts +16 -5
- package/dist/core/schema/string-constraints.mjs +18 -1
- package/dist/core/schema/value-parsers.d.mts +81 -9
- package/dist/core/schema/value-parsers.mjs +19 -1
- package/dist/core/schema/value.d.mts +242 -0
- package/dist/core/schema/value.mjs +573 -0
- package/dist/core/testkit/index.d.mts +28 -3
- package/dist/core/testkit/index.mjs +40 -26
- package/dist/index.d.mts +21 -16
- package/dist/index.mjs +10 -6
- package/dist/runtime/adapter.d.mts +3 -3
- package/dist/runtime/deno.d.mts +3 -3
- package/dist/runtime/detect.d.mts +2 -2
- package/dist/runtime/node.d.mts +3 -3
- package/dist/runtime/paths.d.mts +1 -31
- package/dist/runtime.d.mts +4 -4
- package/dist/strings.d.mts +1 -16
- package/dist/testkit.d.mts +2 -2
- package/dist/testkit.mjs +1 -1
- package/dist/version.d.mts +0 -13
- package/dist/version.mjs +2 -2
- package/dreamcli.schema.json +368 -78
- package/examples/interactive.ts +6 -5
- package/package.json +10 -9
- package/skills/cli-creation/SKILL.md +196 -0
- package/skills/cli-creation/agents/openai.yaml +4 -0
- package/skills/cli-creation/assets/templates/multi-command.bun-test.ts.tpl +20 -0
- package/skills/cli-creation/assets/templates/multi-command.test.ts.tpl +20 -0
- package/skills/cli-creation/assets/templates/multi-command.ts.tpl +89 -0
- package/skills/cli-creation/assets/templates/single-command.bun-test.ts.tpl +29 -0
- package/skills/cli-creation/assets/templates/single-command.test.ts.tpl +29 -0
- package/skills/cli-creation/assets/templates/single-command.ts.tpl +47 -0
- package/skills/cli-creation/references/consumer-workflow.md +65 -0
- package/skills/cli-creation/references/pattern-cookbook.md +451 -0
- package/skills/cli-creation/references/runtime-notes.md +29 -0
- package/skills/cli-creation/scripts/scaffold_cli.py +360 -0
- package/dist/core/resolve/property.d.mts +0 -51
- package/dist/core/resolve/property.mjs +0 -53
|
@@ -1,9 +1,13 @@
|
|
|
1
1
|
import { CLIError, ParseError } from "../errors/index.mjs";
|
|
2
|
-
import {
|
|
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
|
-
/**
|
|
52
|
-
|
|
53
|
-
|
|
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.
|
|
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
|
|
142
|
-
const
|
|
143
|
-
const
|
|
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: "
|
|
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
|
|
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 =
|
|
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 [
|
|
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
|
|
@@ -20,7 +20,8 @@ import { getVisibleNegatedName, quoteShellArg, resolveRootCompletionSurface, san
|
|
|
20
20
|
* ```
|
|
21
21
|
*/
|
|
22
22
|
function generateBashCompletion(schema, options) {
|
|
23
|
-
const
|
|
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);
|
|
@@ -16,7 +16,8 @@ import { getVisibleNegatedName, quoteShellArg, resolveRootCompletionSurface, san
|
|
|
16
16
|
* ```
|
|
17
17
|
*/
|
|
18
18
|
function generateFishCompletion(schema, options) {
|
|
19
|
-
const
|
|
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);
|
|
@@ -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
|
|
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?:
|
|
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?:
|
|
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
|
|
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
|
-
|
|
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
|
|
@@ -21,7 +21,8 @@ import { getVisibleNegatedName, quoteShellArg, resolveRootCompletionSurface, san
|
|
|
21
21
|
* ```
|
|
22
22
|
*/
|
|
23
23
|
function generateZshCompletion(schema, options) {
|
|
24
|
-
const
|
|
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,
|
|
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,
|
|
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,
|
|
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,
|
|
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,
|
|
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,
|
|
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,
|
|
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,
|
|
353
|
+
export { discoverManifest, inferCliName, packageRepositoryUrl };
|