@kjanat/dreamcli 2.3.0 → 2.4.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 +37 -1
- package/README.md +94 -34
- package/dist/core/cli/index.mjs +1 -1
- package/dist/core/cli/planner.mjs +1 -1
- package/dist/core/config/package-json.mjs +1 -1
- package/dist/core/execution/index.mjs +1 -1
- package/dist/core/json-schema/meta-descriptions.generated.d.mts +59 -59
- package/dist/core/output/activity.mjs +1 -1
- package/dist/core/output/bind.d.mts +37 -0
- package/dist/core/output/bind.mjs +1 -0
- package/dist/core/output/index.d.mts +6 -1
- package/dist/core/output/index.mjs +2 -2
- package/dist/core/parse/index.mjs +1 -1
- package/dist/core/schema/activity.d.mts +1 -1
- package/dist/core/schema/command.d.mts +8 -0
- package/dist/core/schema/run.d.mts +8 -5
- package/dist/core/schema-dsl/runtime.mjs +1 -1
- package/dist/core/testkit/index.mjs +1 -1
- package/dist/index.mjs +1 -1
- package/dist/runtime/paths.mjs +1 -1
- package/dist/strings.d.mts +27 -0
- package/dist/strings.mjs +1 -0
- package/dist/testkit.mjs +1 -1
- package/dist/version.mjs +1 -1
- package/package.json +46 -35
- package/src/core/cli/index.ts +9 -3
- package/src/core/cli/planner.ts +58 -2
- package/src/core/config/package-json.ts +3 -2
- package/src/core/execution/index.ts +7 -1
- package/src/core/help/index.ts +2 -2
- package/src/core/output/activity.ts +7 -0
- package/src/core/output/bind.ts +59 -0
- package/src/core/output/index.ts +35 -0
- package/src/core/parse/index.ts +2 -2
- package/src/core/schema/command.ts +8 -0
- package/src/core/schema/run.ts +8 -5
- package/src/runtime/paths.ts +4 -2
- package/src/strings.ts +34 -0
package/CHANGELOG.md
CHANGED
|
@@ -7,6 +7,40 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
|
|
7
7
|
|
|
8
8
|
## [Unreleased]
|
|
9
9
|
|
|
10
|
+
## [2.4.1] - 2026-06-27
|
|
11
|
+
|
|
12
|
+
### Fixed
|
|
13
|
+
|
|
14
|
+
- **Destructuring `out` and activity handles** — `Out` methods and the spinner/progress activity
|
|
15
|
+
handle methods are now bound to their instance, so pulling them off via destructuring (e.g.
|
|
16
|
+
`const { done } = handle`) no longer breaks `this`-dependent behaviour and cleanup
|
|
17
|
+
(https://github.com/kjanat/dreamcli/pull/40).
|
|
18
|
+
|
|
19
|
+
## [2.4.0] - 2026-06-23
|
|
20
|
+
|
|
21
|
+
### Added
|
|
22
|
+
|
|
23
|
+
- **`out.setExitCode(code)` for normal-output status exits** — command handlers can now request a
|
|
24
|
+
process exit code without throwing or emitting error-shaped output, covering status/check CLIs that
|
|
25
|
+
should print their normal report while still signalling degraded state to scripts
|
|
26
|
+
(https://github.com/kjanat/dreamcli/issues/27).
|
|
27
|
+
|
|
28
|
+
### Fixed
|
|
29
|
+
|
|
30
|
+
- **Unknown root commands under no-arg defaults now report `UNKNOWN_COMMAND`** — when a CLI has a
|
|
31
|
+
`.default()` command with no positional args, an unknown root token no longer falls through to the
|
|
32
|
+
default parser as an unexpected positional. Defaults that declare positional args still receive
|
|
33
|
+
those root tokens as before (https://github.com/kjanat/dreamcli/issues/26).
|
|
34
|
+
|
|
35
|
+
### Security
|
|
36
|
+
|
|
37
|
+
- **Hardened trailing-separator trimming against polynomial ReDoS** — the home/config path
|
|
38
|
+
resolution, `package.json` repository-URL normalization, and runtime-binary `basename` helpers
|
|
39
|
+
previously stripped trailing slashes with backtracking regexes (`/[\\/]+$/`, `/\/+$/`) that CodeQL
|
|
40
|
+
flagged as polynomial regular expressions (`js/polynomial-redos`). They now route through a shared
|
|
41
|
+
linear-time `stripTrailing` scan, so adversarial slash-heavy input can no longer trigger quadratic
|
|
42
|
+
matching. No behavior change for valid inputs.
|
|
43
|
+
|
|
10
44
|
## [2.3.0] - 2026-06-20
|
|
11
45
|
|
|
12
46
|
### Fixed
|
|
@@ -804,7 +838,9 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
|
|
804
838
|
- MIT License.
|
|
805
839
|
- Markdownlint configuration.
|
|
806
840
|
|
|
807
|
-
[Unreleased]: https://github.com/kjanat/dreamcli/compare/v2.
|
|
841
|
+
[Unreleased]: https://github.com/kjanat/dreamcli/compare/v2.4.1...HEAD
|
|
842
|
+
[2.4.1]: https://github.com/kjanat/dreamcli/compare/v2.4.0...v2.4.1
|
|
843
|
+
[2.4.0]: https://github.com/kjanat/dreamcli/compare/v2.3.0...v2.4.0
|
|
808
844
|
[2.3.0]: https://github.com/kjanat/dreamcli/compare/v2.2.1...v2.3.0
|
|
809
845
|
[2.2.1]: https://github.com/kjanat/dreamcli/compare/v2.2.0...v2.2.1
|
|
810
846
|
[2.2.0]: https://github.com/kjanat/dreamcli/compare/v2.1.0...v2.2.0
|
package/README.md
CHANGED
|
@@ -8,14 +8,7 @@ Schema-first, fully typed TypeScript CLI framework. Zero runtime dependencies.
|
|
|
8
8
|
One flag declaration configures the entire resolution pipeline:
|
|
9
9
|
|
|
10
10
|
```ts
|
|
11
|
-
import {
|
|
12
|
-
cli,
|
|
13
|
-
command,
|
|
14
|
-
flag,
|
|
15
|
-
arg,
|
|
16
|
-
middleware,
|
|
17
|
-
CLIError,
|
|
18
|
-
} from '@kjanat/dreamcli';
|
|
11
|
+
import { cli, command, flag, arg } from '@kjanat/dreamcli';
|
|
19
12
|
|
|
20
13
|
const deploy = command('deploy')
|
|
21
14
|
.description('Deploy to an environment')
|
|
@@ -34,6 +27,8 @@ const deploy = command('deploy')
|
|
|
34
27
|
.action(({ args, flags, out }) => {
|
|
35
28
|
out.log(`Deploying ${args.target} to ${flags.region}`);
|
|
36
29
|
});
|
|
30
|
+
|
|
31
|
+
cli('deploy').default(deploy).run();
|
|
37
32
|
```
|
|
38
33
|
|
|
39
34
|
By the time `action` runs, `flags.region` is `"us" | "eu" | "ap"` — not `string | undefined`.
|
|
@@ -64,7 +59,7 @@ deno add jsr:@kjanat/dreamcli # or npm:@kjanat/dreamcli
|
|
|
64
59
|
### Single command
|
|
65
60
|
|
|
66
61
|
```ts
|
|
67
|
-
import { command, flag, arg } from '@kjanat/dreamcli';
|
|
62
|
+
import { cli, command, flag, arg } from '@kjanat/dreamcli';
|
|
68
63
|
|
|
69
64
|
const greet = command('greet')
|
|
70
65
|
.description('Greet someone')
|
|
@@ -87,11 +82,17 @@ const greet = command('greet')
|
|
|
87
82
|
}
|
|
88
83
|
});
|
|
89
84
|
|
|
90
|
-
greet.run();
|
|
85
|
+
cli('greet').default(greet).run();
|
|
91
86
|
```
|
|
92
87
|
|
|
93
88
|
### Multi-command CLI
|
|
94
89
|
|
|
90
|
+
<picture>
|
|
91
|
+
<source media="(prefers-color-scheme: dark)" width="700" height="400" alt="dreamcli-migrate-dark" srcset="https://github.com/user-attachments/assets/1ef7f20c-9ffb-4cb6-a6bc-fb562895aa6f">
|
|
92
|
+
<source media="(prefers-color-scheme: light)" width="700" height="400" alt="dreamcli-migrate-light" srcset="https://github.com/user-attachments/assets/1ee5f38d-cad8-47ec-94b2-c826eabab76b">
|
|
93
|
+
<img alt="DreamCLI migration progress demo" width="700" height="400" src="https://github.com/user-attachments/assets/1ee5f38d-cad8-47ec-94b2-c826eabab76b">
|
|
94
|
+
</picture>
|
|
95
|
+
|
|
95
96
|
```ts
|
|
96
97
|
import {
|
|
97
98
|
cli,
|
|
@@ -130,8 +131,31 @@ const login = command('login')
|
|
|
130
131
|
const migrate = command('migrate')
|
|
131
132
|
.description('Run migrations')
|
|
132
133
|
.flag('steps', flag.number())
|
|
133
|
-
.action(({ flags, out }) => {
|
|
134
|
-
|
|
134
|
+
.action(async ({ flags, meta, out }) => {
|
|
135
|
+
const steps = flags.steps ?? 3;
|
|
136
|
+
|
|
137
|
+
out.log(`${meta.name} ${meta.version ?? ''}`.trim());
|
|
138
|
+
out.log(`Command: ${meta.command}`);
|
|
139
|
+
|
|
140
|
+
const spinner = out.spinner('Preparing migrations');
|
|
141
|
+
await new Promise((resolve) =>
|
|
142
|
+
setTimeout(resolve, 1000),
|
|
143
|
+
);
|
|
144
|
+
spinner.succeed(`Ready to run ${steps} steps`);
|
|
145
|
+
|
|
146
|
+
const progress = out.progress({
|
|
147
|
+
label: 'Migrating',
|
|
148
|
+
total: steps,
|
|
149
|
+
});
|
|
150
|
+
|
|
151
|
+
for (let step = 1; step <= steps; step++) {
|
|
152
|
+
await new Promise((resolve) =>
|
|
153
|
+
setTimeout(resolve, 700),
|
|
154
|
+
);
|
|
155
|
+
progress.update(step);
|
|
156
|
+
}
|
|
157
|
+
|
|
158
|
+
progress.done(`Migrated ${steps} steps`);
|
|
135
159
|
});
|
|
136
160
|
|
|
137
161
|
const seed = command('seed')
|
|
@@ -190,6 +214,8 @@ the insight was wiring them so types flow end-to-end.
|
|
|
190
214
|
### Flag types
|
|
191
215
|
|
|
192
216
|
```ts
|
|
217
|
+
import { flag } from '@kjanat/dreamcli';
|
|
218
|
+
|
|
193
219
|
flag.string(); // string | undefined
|
|
194
220
|
flag.number(); // number | undefined
|
|
195
221
|
flag.boolean(); // boolean (defaults to false)
|
|
@@ -217,6 +243,8 @@ non-interactive contexts (CI, piped stdin), prompts are automatically skipped.
|
|
|
217
243
|
Four prompt types, declared per-flag or per-command:
|
|
218
244
|
|
|
219
245
|
```ts
|
|
246
|
+
import { command, flag } from '@kjanat/dreamcli';
|
|
247
|
+
|
|
220
248
|
// Per-flag
|
|
221
249
|
flag.string().prompt({ kind: 'input', message: 'Name?' });
|
|
222
250
|
flag
|
|
@@ -245,7 +273,7 @@ command('deploy')
|
|
|
245
273
|
### Derive typed context from resolved input
|
|
246
274
|
|
|
247
275
|
```ts
|
|
248
|
-
import { CLIError } from '@kjanat/dreamcli';
|
|
276
|
+
import { CLIError, command, flag } from '@kjanat/dreamcli';
|
|
249
277
|
|
|
250
278
|
command('deploy')
|
|
251
279
|
.flag('token', flag.string().env('AUTH_TOKEN'))
|
|
@@ -268,7 +296,7 @@ the action handler runs.
|
|
|
268
296
|
### Middleware with typed context
|
|
269
297
|
|
|
270
298
|
```ts
|
|
271
|
-
import { middleware } from '@kjanat/dreamcli';
|
|
299
|
+
import { command, middleware } from '@kjanat/dreamcli';
|
|
272
300
|
|
|
273
301
|
const timing = middleware<{ startTime: number }>(
|
|
274
302
|
async ({ next }) => {
|
|
@@ -301,26 +329,33 @@ Use middleware when you need wrapper behavior with `next()`.
|
|
|
301
329
|
Handlers receive `out` instead of `console`. Adapts to context automatically:
|
|
302
330
|
|
|
303
331
|
```ts
|
|
304
|
-
cli
|
|
305
|
-
|
|
306
|
-
|
|
307
|
-
|
|
308
|
-
|
|
309
|
-
|
|
310
|
-
|
|
311
|
-
|
|
312
|
-
|
|
313
|
-
|
|
314
|
-
|
|
315
|
-
|
|
332
|
+
import { cli, command } from '@kjanat/dreamcli';
|
|
333
|
+
|
|
334
|
+
const rows = [
|
|
335
|
+
{ name: 'api', status: 'ok' },
|
|
336
|
+
{ name: 'worker', status: 'deploying' },
|
|
337
|
+
];
|
|
338
|
+
|
|
339
|
+
const status = command('status').action(({ out }) => {
|
|
340
|
+
out.log('Human-readable message');
|
|
341
|
+
out.json({ status: 'ok', count: 42 });
|
|
342
|
+
out.table(rows, [
|
|
343
|
+
{ key: 'name', header: 'Name' },
|
|
344
|
+
{ key: 'status', header: 'Status' },
|
|
345
|
+
]);
|
|
346
|
+
|
|
347
|
+
const spinner = out.spinner('Deploying...');
|
|
348
|
+
spinner.succeed('Done');
|
|
316
349
|
|
|
317
|
-
|
|
318
|
-
|
|
319
|
-
|
|
320
|
-
});
|
|
321
|
-
progress.update(50);
|
|
322
|
-
progress.done('Upload complete');
|
|
350
|
+
const progress = out.progress({
|
|
351
|
+
label: 'Uploading',
|
|
352
|
+
total: 100,
|
|
323
353
|
});
|
|
354
|
+
progress.update(50);
|
|
355
|
+
progress.done('Upload complete');
|
|
356
|
+
});
|
|
357
|
+
|
|
358
|
+
cli('mycli').default(status).run();
|
|
324
359
|
```
|
|
325
360
|
|
|
326
361
|
- TTY → pretty formatting, spinners animate
|
|
@@ -332,7 +367,24 @@ cli('mycli')
|
|
|
332
367
|
Generated from the command schema — always in sync:
|
|
333
368
|
|
|
334
369
|
```ts
|
|
335
|
-
import {
|
|
370
|
+
import { cli, command } from '@kjanat/dreamcli';
|
|
371
|
+
|
|
372
|
+
cli('mycli').command(command('deploy')).completions().run();
|
|
373
|
+
|
|
374
|
+
// mycli completions bash
|
|
375
|
+
// mycli completion zsh
|
|
376
|
+
```
|
|
377
|
+
|
|
378
|
+
For programmatic integrations, call the generator directly:
|
|
379
|
+
|
|
380
|
+
```ts
|
|
381
|
+
import {
|
|
382
|
+
cli,
|
|
383
|
+
command,
|
|
384
|
+
generateCompletion,
|
|
385
|
+
} from '@kjanat/dreamcli';
|
|
386
|
+
|
|
387
|
+
const myCli = cli('mycli').command(command('deploy'));
|
|
336
388
|
|
|
337
389
|
generateCompletion(myCli.schema, 'bash');
|
|
338
390
|
generateCompletion(myCli.schema, 'zsh');
|
|
@@ -341,6 +393,8 @@ generateCompletion(myCli.schema, 'zsh');
|
|
|
341
393
|
### Config file discovery
|
|
342
394
|
|
|
343
395
|
```ts
|
|
396
|
+
import { command, flag } from '@kjanat/dreamcli';
|
|
397
|
+
|
|
344
398
|
command('deploy').flag(
|
|
345
399
|
'region',
|
|
346
400
|
flag.enum(['us', 'eu']).config('deploy.region'),
|
|
@@ -350,7 +404,7 @@ command('deploy').flag(
|
|
|
350
404
|
Searches XDG-standard paths automatically. JSON built-in, plugin hook for YAML/TOML:
|
|
351
405
|
|
|
352
406
|
```ts
|
|
353
|
-
import { configFormat } from '@kjanat/dreamcli';
|
|
407
|
+
import { cli, configFormat } from '@kjanat/dreamcli';
|
|
354
408
|
import { parse as parseYAML } from 'yaml';
|
|
355
409
|
|
|
356
410
|
cli('mycli')
|
|
@@ -361,6 +415,11 @@ cli('mycli')
|
|
|
361
415
|
### Structured errors
|
|
362
416
|
|
|
363
417
|
```ts
|
|
418
|
+
import { CLIError } from '@kjanat/dreamcli';
|
|
419
|
+
|
|
420
|
+
const target = 'production';
|
|
421
|
+
const region = 'us';
|
|
422
|
+
|
|
364
423
|
throw new CLIError('Deployment failed', {
|
|
365
424
|
code: 'DEPLOY_FAILED',
|
|
366
425
|
exitCode: 1,
|
|
@@ -378,6 +437,7 @@ In `--json` mode, errors serialize to machine-readable JSON.
|
|
|
378
437
|
subprocesses, no `process.argv` mutation, no mocking.
|
|
379
438
|
|
|
380
439
|
```ts
|
|
440
|
+
import { expect } from 'vitest';
|
|
381
441
|
import { arg, command, flag } from '@kjanat/dreamcli';
|
|
382
442
|
import {
|
|
383
443
|
runCommand,
|
package/dist/core/cli/index.mjs
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
import{CLIError as e}from"../errors/index.mjs";import{SHELLS as t,generateCompletion as n}from"../completion/index.mjs";import{formatHelp as r}from"../help/index.mjs";import{
|
|
1
|
+
import{CLIError as e}from"../errors/index.mjs";import{SHELLS as t,generateCompletion as n}from"../completion/index.mjs";import{formatHelp as r}from"../help/index.mjs";import{clearRequestedExitCode as i,createCaptureOutput as a,createOutput as o}from"../output/index.mjs";import{includesBeforeSeparator as s}from"../parse/index.mjs";import{buildRunResult as c,executeCommand as l}from"../execution/index.mjs";import{arg as u}from"../schema/arg.mjs";import{command as d}from"../schema/command.mjs";import{runCommand as f}from"../testkit/index.mjs";import{stripTrailing as p}from"../../strings.mjs";import{createAdapter as m}from"../../runtime/auto.mjs";import{deriveHelpLinks as h}from"./help-links.mjs";import{planInvocation as g}from"./planner.mjs";import"./plugin.mjs";import{formatRootHelp as _}from"./root-help.mjs";import{prepareRuntimePreflight as v}from"./runtime-preflight.mjs";function y(e){return[e.name,...e.aliases]}function b(t,n,r,i){let a=n.get(r);if(a!==void 0)throw new e(`Duplicate command route '${r}' under '${t}' (${a} and ${i})`,{code:`DUPLICATE_COMMAND`,suggest:`Ensure sibling command names and aliases are unique`});n.set(r,i)}function x(t,n){let r=new Map;for(let e of t)for(let t of y(e.schema))b(`root`,r,t,e.schema.name);for(let t of y(n)){let i=r.get(t);if(i!==void 0)throw new e(`Command route '${t}' is already registered by '${i}'`,{code:`DUPLICATE_COMMAND`,suggest:i===n.name?`Ensure command '${n.name}' does not reuse route '${t}'`:`Rename '${n.name}' or remove route '${t}' from '${i}'`});r.set(t,n.name)}}function S(e){let t=new Map,n=new Map;for(let r of e._subcommands){let i=y(r.schema);for(let t of i)b(e.schema.name,n,t,r.schema.name);let a=S(r);for(let e of i)t.set(e,a)}return{schema:e.schema,subcommands:t,_command:e,_execute(t,n){return f(e,t,n)}}}function C(e,t,n){return{help:t,...n===void 0?{}:{meta:n},...e?.plugins===void 0?{}:{plugins:e.plugins},...e?.env===void 0?{}:{env:e.env},...e?.config===void 0?{}:{config:e.config},...e?.stdinData===void 0?{}:{stdinData:e.stdinData},...e?.prompter===void 0?{}:{prompter:e.prompter},...e?.answers===void 0?{}:{answers:e.answers},...e?.verbosity===void 0?{}:{verbosity:e.verbosity},...e?.jsonMode===void 0?{}:{jsonMode:e.jsonMode},...e?.isTTY===void 0?{}:{isTTY:e.isTTY},...e?.out===void 0?{}:{out:e.out},...e?.captured===void 0?{}:{captured:e.captured}}}var w=class f{schema;constructor(e){this.schema=e}version(e){return new f({...this.schema,version:e})}description(e){return new f({...this.schema,description:e})}links(e){return new f({...this.schema,helpLinks:{name:k(e?.name),version:k(e?.version)}})}config(e,t){return new f({...this.schema,configSettings:{appName:e,loaders:t}})}configLoader(t){if(this.schema.configSettings===void 0)throw new e(`.configLoader() requires .config() to be called first`,{code:`INVALID_BUILDER_STATE`,suggest:`Call .config(appName) before .configLoader()`});let n=this.schema.configSettings.loaders??[];return new f({...this.schema,configSettings:{...this.schema.configSettings,loaders:[...n,t]}})}packageJson(e){return M(e)?new f({...this.schema,...this.schema.version===void 0&&e.version!==void 0?{version:e.version}:{},...this.schema.description===void 0&&e.description!==void 0?{description:e.description}:{},packageJsonSettings:{inferName:!1,from:void 0,data:e}}):new f({...this.schema,packageJsonSettings:{inferName:e?.inferName??!1,from:j(e?.from),data:void 0}})}command(e){return x(this.schema.commands,e.schema),new f({...this.schema,commands:[...this.schema.commands,S(e)]})}default(t){if(this.schema.defaultCommand!==void 0)throw new e(`Only one default command is allowed`,{code:`DUPLICATE_DEFAULT`,suggest:`Call .default() only once when building the CLI`});x(this.schema.commands,t.schema);let n=S(t);return new f({...this.schema,commands:[...this.schema.commands,n],defaultCommand:n})}plugin(e){return new f({...this.schema,plugins:[...this.schema.plugins,e]})}completions(r){if(this.schema.hasBuiltInCompletions)throw new e(`.completions() has already been called`,{code:`DUPLICATE_COMMAND`,suggest:`Call .completions() only once when building the CLI`});let i=this.schema,a=r,o=new Map;for(let e of t)o.set(e,e);o.set(`pwsh`,`powershell`);let s=d(`completions`).alias(`completion`).description(`Generate shell completion script`).arg(`shell`,u.custom(e=>{let n=e.split(/[\\/]/),r=(n[n.length-1]??e).replace(/\.(?:exe|cmd|bat)$/i,``),i=o.get(r);if(i===void 0)throw Error(`Unknown shell '${r}'. Valid shells: ${t.join(`, `)}`);return i}).env(`SHELL`).describe(`Target shell (${t.join(`, `)})`)).action(({args:e,meta:t,out:r})=>{let o=n(t.bin===i.name?i:{...i,name:t.bin},e.shell,a);r.jsonMode?r.json({shell:e.shell,script:o}):r.log(o)});return new f({...this.command(s).schema,hasBuiltInCompletions:!0})}async execute(e,t){let n=s(e,`--json`)||t?.jsonMode===!0,o={...t?.verbosity===void 0?{}:{verbosity:t.verbosity},...n?{jsonMode:n}:{},...t?.isTTY===void 0?{}:{isTTY:t.isTTY}},u,d;t?.out===void 0?[u,d]=a(Object.keys(o).length>0?o:void 0):(u=t.out,d=t.captured??{stdout:[],stderr:[],activity:[]}),i(u);let f={...t?.help,binName:t?.help?.binName??this.schema.name,hyperlinks:t?.help?.hyperlinks??u.isTTY},p={...t,plugins:this.schema.plugins,...n?{jsonMode:n}:{}},m={jsonMode:n,isTTY:u.isTTY,verbosity:t?.verbosity??`normal`},h=g({schema:this.schema,argv:e,help:f,output:m});switch(h.kind){case`root-version`:return u.log(h.version),c({exitCode:0,error:void 0},d);case`root-help`:{let e=_(A(this.schema),h.help);return u.log(e),c({exitCode:0,error:void 0},d)}case`dispatch-error`:return n?u.json({error:h.error.toJSON()}):(u.error(h.error.message),h.error.suggest!==void 0&&h.error.code!==`NO_ACTION`&&u.error(`Suggestion: ${h.error.suggest}`)),c({exitCode:h.error.exitCode,error:h.error},d);case`needs-subcommand`:{let e=r(h.command.schema,h.help);return u.log(e),c({exitCode:0,error:void 0},d)}case`match`:{let e=C(p,h.plan.help??f,h.plan.meta);return h.plan.command._command===void 0?h.plan.command._execute(h.plan.argv,{...e,mergedSchema:h.plan.mergedSchema}):c(await l({command:h.plan.command._command,argv:h.plan.argv,out:u,schema:h.plan.mergedSchema,meta:h.plan.meta,options:e}),d)}}}async run(e){let t=e?.adapter??m(),n=this.schema.inheritName?O(t.argv):void 0,r=await v({schema:this.schema,adapter:t,options:e,inheritedName:n});if(r.kind===`config-error`)return r.jsonMode?t.stdout(`${JSON.stringify({error:r.error.toJSON()})}\n`):(t.stderr(`Error: ${r.error.message}\n`),r.error.suggest!==void 0&&t.stderr(`Suggestion: ${r.error.suggest}\n`)),t.exit(r.error.exitCode);let i=r.schema===this.schema?this:new f(r.schema),a={...e,...r.inputs,out:o({stdout:t.stdout,stderr:t.stderr,jsonMode:r.inputs.jsonMode,isTTY:r.inputs.isTTY,...r.inputs.verbosity===`normal`?{}:{verbosity:r.inputs.verbosity}})},s=await i.execute(r.filteredArgv,a);for(let e of s.stdout)t.stdout(e);for(let e of s.stderr)t.stderr(e);return t.exit(s.exitCode)}};const T=new Set([`bun`,`deno`,`node`,`tsx`]);function E(e){let t=p(e,[47,92]);if(t.length===0)return;let n=Math.max(t.lastIndexOf(`/`),t.lastIndexOf(`\\`)),r=n>=0?t.slice(n+1):t;return r.length>0?r:void 0}function D(e){let t=e.toLowerCase().replace(/\.exe$/i,``);return T.has(t)}function O(e){let t=e[0],n=e[1],r=t===void 0?void 0:E(t);if(r!==void 0&&D(r)){if(r===`bun`&&n===`run`){let t=e[2];return t===void 0||t.startsWith(`-`)?void 0:E(t)}return r===`deno`&&n===`run`||n===void 0||n.startsWith(`-`)?void 0:E(n)}return t===void 0?void 0:E(t)}function k(e){if(e!==void 0)return e instanceof URL?e.href:e}function A(e){return e.helpLinks===void 0?e:{...e,helpLinks:h(e.helpLinks,e.packageJsonSettings?.data,e.version)}}function j(e){if(e===void 0)return;if(e instanceof URL){if(e.protocol!==`file:`)return e.href}else if(!e.startsWith(`file:`))return e;let t=decodeURIComponent(new URL(e).pathname);return/^\/[A-Za-z]:/.test(t)?t.slice(1).replace(/\//g,`\\`):t}function M(e){return typeof e!=`object`||!e||Array.isArray(e)?!1:`name`in e||`version`in e||`description`in e||`bin`in e||`homepage`in e||`repository`in e}function N(e){return new w({name:typeof e==`string`?e:e.name??`cli`,inheritName:typeof e==`string`?!1:e.inherit??!1,version:void 0,description:void 0,commands:[],defaultCommand:void 0,configSettings:void 0,packageJsonSettings:void 0,helpLinks:void 0,hasBuiltInCompletions:!1,plugins:[]})}export{w as CLIBuilder,N as cli};
|
|
@@ -1 +1 @@
|
|
|
1
|
-
import{collectPropagatedFlags as e}from"./propagate.mjs";import{CLIError as t,ParseError as n}from"../errors/index.mjs";import{buildFlagLookup as r,includesBeforeSeparator as
|
|
1
|
+
import{collectPropagatedFlags as e}from"./propagate.mjs";import{CLIError as t,ParseError as n}from"../errors/index.mjs";import{buildFlagLookup as r,flagExpectsValue as i,includesBeforeSeparator as a}from"../parse/index.mjs";import{dispatch as o,findClosestCommand as s}from"./dispatch.mjs";function c(e,t,n){return{name:e.name,bin:t.binName??e.name,version:e.version,command:n}}function l(e){let n=new Map,r=(e,r)=>{let i=n.get(e);if(i!==void 0)throw new t(`Duplicate root command route '${e}' (${i.schema.name} and ${r.schema.name})`,{code:`DUPLICATE_COMMAND`,suggest:`Ensure root command names and aliases are unique`});n.set(e,r)};for(let t of e){r(t.schema.name,t);for(let e of t.schema.aliases)r(e,t)}return n}function u(t,n){let r=e(n);return Object.keys(r).length===0?t.schema:{...t.schema,flags:{...r,...t.schema.flags}}}function d(e){return{command:e.command,mergedSchema:u(e.command,e.commandPath),argv:e.argv,meta:e.meta,plugins:e.plugins,output:e.output,help:e.help}}function f(e,t,n,r,i,a){return{kind:`match`,plan:d({command:t,commandPath:n,argv:r,meta:c(e,i,t.schema.name),plugins:e.plugins,output:a,help:i})}}function p(e,t){return t===``||e.schema.args.length>0}function m(e,t){let n=r(t);for(let t=0;t<e.length;t++){let r=e[t];if(r===void 0||r===`--`||r===`-`||!r.startsWith(`-`))return;if(r.startsWith(`--`)){let e=r.indexOf(`=`),a=r.slice(2,e===-1?void 0:e),o=n.get(a);if(o===void 0)return e===-1?r:`--${a}`;e===-1&&i(o[1])&&t++;continue}let a=r.slice(1);for(let e=0;e<a.length;e++){let r=a.charAt(e),o=n.get(r);if(o===void 0)return`-${r}`;if(i(o[1])){e===a.length-1&&t++;break}}}}function h(e){let i=e.argv.indexOf(`--`),c=i===-1?e.argv:e.argv.slice(0,i),u=i===-1?[]:e.argv.slice(i),d=c.includes(`--json`)?c.filter(e=>e!==`--json`):c,g=i===-1?d:[...d,...u];if(e.schema.version!==void 0&&(a(e.argv,`--version`)||a(e.argv,`-V`)))return{kind:`root-version`,version:e.schema.version};let _=g[0];if(_===`--help`||_===`-h`)return{kind:`root-help`,help:e.help};if(_===`help`&&!e.schema.commands.some(e=>e.schema.name===`help`||e.schema.aliases.includes(`help`))){let t=g.slice(1);return t.length===0?{kind:`root-help`,help:e.help}:h({...e,argv:[...t,`--help`]})}if(_===void 0&&e.schema.defaultCommand===void 0)return{kind:`root-help`,help:e.help};if(e.schema.commands.length===0)return{kind:`dispatch-error`,error:new t(`No commands registered`,{code:`NO_ACTION`,suggest:`Add commands via .command() before calling .run()`})};let v=e.schema.defaultCommand,y=v===void 0?void 0:r(v.schema.flags),b=o(g,l(e.schema.commands),[],y);switch(b.kind){case`unknown`:{if(v!==void 0&&b.parentPath.length===0){if((b.input===``?void 0:s(b.input,b.candidates))===void 0&&p(v,b.input))return f(e.schema,v,[v.schema],g,e.help,e.output);let t=m(g,v.schema.flags);if(t!==void 0)return{kind:`dispatch-error`,error:new n(`Unknown flag ${t}`,{code:`UNKNOWN_FLAG`,suggest:`Run '${e.schema.name} --help' for available commands`})}}if(b.input===``){let t=g.find(e=>e.startsWith(`-`));return t===void 0?{kind:`root-help`,help:e.help}:{kind:`dispatch-error`,error:new n(`Unknown flag ${t}`,{code:`UNKNOWN_FLAG`,suggest:`Run '${e.schema.name} --help' for available commands`})}}let t=s(b.input,b.candidates),r=b.parentPath.length>0?`${e.schema.name} ${b.parentPath.map(e=>e.name).join(` `)}`:e.schema.name;return{kind:`dispatch-error`,error:new n(`Unknown command: ${b.input}`,{code:`UNKNOWN_COMMAND`,suggest:t===void 0?`Run '${r} --help' for available commands`:`Did you mean '${t}'?`})}}case`needs-subcommand`:{let t=b.commandPath.slice(0,-1).map(e=>e.name);return{kind:`needs-subcommand`,command:b.command,commandPath:b.commandPath,help:{...e.help,binName:[e.schema.name,...t].join(` `)}}}case`match`:return f(e.schema,b.command,b.commandPath,b.remainingArgv,e.help,e.output)}}export{h as planInvocation};
|
|
@@ -1 +1 @@
|
|
|
1
|
-
function
|
|
1
|
+
import{stripTrailing as e}from"../../strings.mjs";function t(e){return typeof e==`object`&&!!e&&!Array.isArray(e)}function n(e){let t=e.lastIndexOf(`/`),n=e.lastIndexOf(`\\`),r=Math.max(t,n),i=n>t?`\\`:`/`;if(r<0)return;if(r===0)return e.length>1?i:void 0;let a=e.slice(0,r);if(a.length===2&&a[1]===`:`){let t=`${a}${i}`;return t===e?void 0:t}return a}function r(e,t){let n=e.includes(`\\`)?`\\`:`/`;return e.endsWith(n)?`${e}${t}`:`${e}${n}${t}`}async function i(e,t){let i=t??e.cwd;for(;i!==void 0;){let t=null;try{t=await e.readFile(r(i,`package.json`))}catch{}if(t!==null){let e=a(t);if(e!==null)return e}i=n(i)}return null}function a(e){try{let n=JSON.parse(e);if(!t(n))return null;let r=typeof n.name==`string`?n.name:void 0,i=typeof n.version==`string`?n.version:void 0,a=typeof n.description==`string`?n.description:void 0,c=o(n.bin),l=typeof n.homepage==`string`?n.homepage:void 0,u=s(n.repository);return{...r===void 0?{}:{name:r},...i===void 0?{}:{version:i},...a===void 0?{}:{description:a},...c===void 0?{}:{bin:c},...l===void 0?{}:{homepage:l},...u===void 0?{}:{repository:u}}}catch{return null}}function o(e){if(typeof e==`string`)return e;if(!t(e))return;let n={};for(let[t,r]of Object.entries(e)){if(typeof r!=`string`)return;n[t]=r}return n}function s(e){if(typeof e==`string`)return e;if(!t(e))return;let n=typeof e.type==`string`?e.type:void 0,r=typeof e.url==`string`?e.url:void 0,i=typeof e.directory==`string`?e.directory:void 0;if(!(n===void 0&&r===void 0&&i===void 0))return{...n===void 0?{}:{type:n},...r===void 0?{}:{url:r},...i===void 0?{}:{directory:i}}}const c={github:`https://github.com`,gitlab:`https://gitlab.com`,bitbucket:`https://bitbucket.org`};function l(e){return e.endsWith(`.git`)?e.slice(0,-4):e}function u(t){let n=typeof t.repository==`string`?t.repository:t.repository?.url;if(n===void 0)return;let r=n.trim();if(r.length===0)return;let i=/^(github|gitlab|bitbucket):([^/]+\/[^/]+)$/.exec(r);if(i!==null&&i[1]!==void 0&&i[2]!==void 0){let e=c[i[1]];if(e!==void 0)return`${e}/${l(i[2])}`}if(/^[\w.-]+\/[\w.-]+$/.test(r))return`https://github.com/${l(r)}`;r.startsWith(`git+`)&&(r=r.slice(4));let a=/^git@([^:/]+):(.+)$/.exec(r);if(a!==null&&a[1]!==void 0&&a[2]!==void 0)return`https://${a[1]}/${l(e(a[2],[47]))}`;if(/^(?:https?|git|ssh):\/\//.test(r))try{let t=new URL(r),n=l(e(t.pathname,[47]));return`https://${t.hostname}${n}`}catch{return}}function d(e){if(typeof e.bin==`object`){let t=Object.keys(e.bin);if(t.length>0&&t[0]!==void 0)return t[0]}if(e.name!==void 0){let t=e.name.indexOf(`/`);return t>=0?e.name.slice(t+1):e.name}}export{i as discoverPackageJson,d as inferCliName,u as packageRepositoryUrl};
|
|
@@ -1 +1 @@
|
|
|
1
|
-
import{CLIError as e}from"../errors/index.mjs";import{formatHelp as t}from"../help/index.mjs";import{
|
|
1
|
+
import{CLIError as e}from"../errors/index.mjs";import{formatHelp as t}from"../help/index.mjs";import{clearRequestedExitCode as n,getRequestedExitCode as r}from"../output/index.mjs";import{includesBeforeSeparator as i,parse as a}from"../parse/index.mjs";import{createTestPrompter as o}from"../prompt/index.mjs";import{resolve as s}from"../resolve/index.mjs";async function c(c){let{argv:f,command:m,meta:h,options:g,out:_,schema:v}=c;n(_);try{if(i(f,`--help`)||i(f,`-h`)){let e=t(v,g?.help);return _.log(e),{exitCode:0,error:void 0}}let n=m.handler;if(n===void 0){let t=new e(`Command '${m.schema.name}' has no action handler`,{code:`NO_ACTION`,suggest:`Add an .action() handler to the '${m.schema.name}' command`});return _.error(t.message),{exitCode:1,error:t}}await l(g?.plugins,{argv:f,command:v,meta:h,out:_});let c=a(v,f),y=g?.prompter??(g?.answers===void 0?void 0:o(g.answers)),b=await s(v,c,{...g?.stdinData===void 0?{}:{stdinData:g.stdinData},...g?.env===void 0?{}:{env:g.env},...g?.config===void 0?{}:{config:g.config},...y===void 0?{}:{prompter:y}}),x={args:b.args,flags:b.flags,deprecations:b.deprecations,command:v,meta:h,out:_};await u(g?.plugins,`afterResolve`,x);for(let e of b.deprecations)_.warn(p(e));return await u(g?.plugins,`beforeAction`,x),await d(m,n,b.flags,b.args,_,h),await u(g?.plugins,`afterAction`,x),{exitCode:r(_)??0,error:void 0}}catch(t){if(t instanceof e)return g?.jsonMode===!0?_.json({error:t.toJSON()}):(_.error(t.message),t.suggest!==void 0&&_.error(`Suggestion: ${t.suggest}`)),{exitCode:t.exitCode,error:t};let n=new e(`Unexpected error: ${t instanceof Error?t.message:String(t)}`,{code:`UNEXPECTED_ERROR`,cause:t});return g?.jsonMode===!0?_.json({error:n.toJSON()}):_.error(n.message),{exitCode:1,error:n}}finally{_.stopActive(),n(_)}}async function l(e,t){if(e!==void 0)for(let n of e){let e=n.hooks.beforeParse;e!==void 0&&await e(t)}}async function u(e,t,n){if(e!==void 0)for(let r of e){let e=r.hooks[t];e!==void 0&&await e(n)}}async function d(t,n,r,i,a,o){let s=t._executionSteps,c=async e=>{await n({flags:r,args:i,ctx:e,out:a,meta:o})};for(let t=s.length-1;t>=0;t--){let n=s[t];if(n===void 0)continue;let l=c;switch(n.kind){case`derive`:c=async t=>{let s=await n.handler({args:i,flags:r,ctx:t,out:a,meta:o});if(s===void 0){await l(t);return}if(typeof s!=`object`||!s||Array.isArray(s))throw new e(`derive() must return an object or undefined`,{code:`INVALID_BUILDER_STATE`,suggest:`Return an object to add context, or return nothing for validation-only derive handlers`});await l({...t,...s})};break;case`middleware`:c=async e=>{await n.handler({args:i,flags:r,ctx:e,out:a,meta:o,next:async t=>{await l({...e,...t})}})};break}}await c({})}function f(e,t){return{exitCode:e.exitCode,stdout:t.stdout,stderr:t.stderr,activity:t.activity,error:e.error}}function p(e){let t=e.kind===`flag`?`flag --${e.name}`:`argument <${e.name}>`;return typeof e.message==`string`?`Warning: ${t} is deprecated: ${e.message}`:`Warning: ${t} is deprecated`}export{f as buildRunResult,c as executeCommand};
|
|
@@ -8,173 +8,173 @@ declare const definitionMetaSchemaDescriptions: {
|
|
|
8
8
|
readonly root: {
|
|
9
9
|
readonly description: "Runtime descriptor for the CLI program.\n\nStores the program name, version, description, and registered commands.\\\nBuilt incrementally by CLIBuilder.";
|
|
10
10
|
readonly properties: {
|
|
11
|
-
readonly
|
|
11
|
+
readonly name: {
|
|
12
12
|
readonly description: "Program name (used in help text, usage lines, and completion scripts).";
|
|
13
13
|
};
|
|
14
|
-
readonly
|
|
14
|
+
readonly version: {
|
|
15
15
|
readonly description: "Program version (shown by `--version`).";
|
|
16
16
|
};
|
|
17
|
-
readonly
|
|
17
|
+
readonly description: {
|
|
18
18
|
readonly description: "Program description (shown in root help).";
|
|
19
19
|
};
|
|
20
|
-
readonly
|
|
20
|
+
readonly defaultCommand: {
|
|
21
21
|
readonly description: "Default command dispatched when no subcommand matches.\n\nWhen set, the CLI root behaves like a hybrid command group: subcommands\ndispatch by name as usual, but empty argv or flags-only argv falls\nthrough to this command instead of showing root help.\n\nSet via the .default() builder method.";
|
|
22
22
|
};
|
|
23
|
-
readonly
|
|
23
|
+
readonly commands: {
|
|
24
24
|
readonly description: "Registered commands (type-erased for heterogeneous storage).";
|
|
25
25
|
};
|
|
26
26
|
};
|
|
27
27
|
};
|
|
28
28
|
readonly defs: {
|
|
29
|
-
readonly
|
|
30
|
-
readonly description: "Runtime descriptor produced by CommandBuilder.\n\nConsumers (parser, help generator, CLI dispatcher) read this to\nunderstand the command's shape
|
|
29
|
+
readonly command: {
|
|
30
|
+
readonly description: "Runtime descriptor produced by CommandBuilder.\n\nConsumers (parser, help generator, CLI dispatcher) read this to\nunderstand the command's shape — flags, args, aliases, subcommands,\nmiddleware, and interactive resolver.";
|
|
31
31
|
readonly properties: {
|
|
32
|
-
readonly
|
|
32
|
+
readonly name: {
|
|
33
33
|
readonly description: "The command name (used for dispatch, e.g. `'deploy'`).";
|
|
34
34
|
};
|
|
35
|
-
readonly
|
|
35
|
+
readonly description: {
|
|
36
36
|
readonly description: "Human-readable description for help text.";
|
|
37
37
|
};
|
|
38
|
-
readonly
|
|
38
|
+
readonly aliases: {
|
|
39
39
|
readonly description: "Alternative names for this command.";
|
|
40
40
|
};
|
|
41
|
-
readonly
|
|
41
|
+
readonly hidden: {
|
|
42
42
|
readonly description: "Whether this command is hidden from help listings.";
|
|
43
43
|
};
|
|
44
|
-
readonly
|
|
44
|
+
readonly examples: {
|
|
45
45
|
readonly description: "Usage examples for help text.";
|
|
46
46
|
};
|
|
47
|
-
readonly
|
|
47
|
+
readonly flags: {
|
|
48
48
|
readonly description: "Named flag schemas, keyed by flag name.";
|
|
49
49
|
};
|
|
50
|
-
readonly
|
|
50
|
+
readonly args: {
|
|
51
51
|
readonly description: "Ordered positional arg entries (name + schema).";
|
|
52
52
|
};
|
|
53
|
-
readonly
|
|
54
|
-
readonly description: "Nested subcommand schemas (for help rendering and completion).\n\nPure data
|
|
53
|
+
readonly commands: {
|
|
54
|
+
readonly description: "Nested subcommand schemas (for help rendering and completion).\n\nPure data — no execution closures. Populated by `.command()` on\n`CommandBuilder`. Empty for leaf commands.";
|
|
55
55
|
};
|
|
56
56
|
};
|
|
57
57
|
};
|
|
58
|
-
readonly
|
|
58
|
+
readonly flag: {
|
|
59
59
|
readonly description: "The runtime descriptor stored inside every FlagBuilder. Consumers (parser,\nhelp generator, resolution chain) read this to understand the flag's shape\nwithout touching generics.";
|
|
60
60
|
readonly properties: {
|
|
61
|
-
readonly
|
|
61
|
+
readonly kind: {
|
|
62
62
|
readonly description: "What kind of value this flag accepts.";
|
|
63
63
|
};
|
|
64
|
-
readonly
|
|
65
|
-
readonly description: "Presence describes whether a flag value is guaranteed to exist when the\naction handler runs:\n\n- `'optional'`
|
|
64
|
+
readonly presence: {
|
|
65
|
+
readonly description: "Presence describes whether a flag value is guaranteed to exist when the\naction handler runs:\n\n- `'optional'` — not required; unresolved value follows the kind-specific\n optional fallback (`undefined` for most flags, `[]` for arrays)\n- `'required'` — must be supplied; error if missing\n- `'defaulted'` — always present (falls back to default value)";
|
|
66
66
|
};
|
|
67
|
-
readonly
|
|
67
|
+
readonly defaultValue: {
|
|
68
68
|
readonly description: "Runtime default value (if any).";
|
|
69
69
|
};
|
|
70
|
-
readonly
|
|
70
|
+
readonly aliases: {
|
|
71
71
|
readonly description: "Short/long aliases (e.g. `[{ name: 'f', hidden: false }]` for `--force`).";
|
|
72
72
|
};
|
|
73
|
-
readonly
|
|
73
|
+
readonly envVar: {
|
|
74
74
|
readonly description: "Environment variable name for v0.2+ resolution.";
|
|
75
75
|
};
|
|
76
|
-
readonly
|
|
76
|
+
readonly configPath: {
|
|
77
77
|
readonly description: "Dotted config path for v0.2+ resolution (e.g. `'deploy.region'`).";
|
|
78
78
|
};
|
|
79
|
-
readonly
|
|
79
|
+
readonly description: {
|
|
80
80
|
readonly description: "Human-readable description for help text.";
|
|
81
81
|
};
|
|
82
|
-
readonly
|
|
82
|
+
readonly enumValues: {
|
|
83
83
|
readonly description: "Allowed literal values when `kind === 'enum'`.";
|
|
84
84
|
};
|
|
85
|
-
readonly
|
|
85
|
+
readonly elementSchema: {
|
|
86
86
|
readonly description: "Element schema when `kind === 'array'`.";
|
|
87
87
|
};
|
|
88
|
-
readonly
|
|
88
|
+
readonly prompt: {
|
|
89
89
|
readonly description: "Interactive prompt configuration for v0.3+ resolution.";
|
|
90
90
|
};
|
|
91
|
-
readonly
|
|
92
|
-
readonly description: "Deprecation marker.\n\n- `undefined`
|
|
91
|
+
readonly deprecated: {
|
|
92
|
+
readonly description: "Deprecation marker.\n\n- `undefined` — not deprecated (default)\n- `true` — deprecated with no migration message\n- `string` — deprecated with a reason/migration message\n\nWhen a deprecated flag is used, a warning is emitted to stderr.\nHelp text shows `[deprecated]` or `[deprecated: <reason>]`.";
|
|
93
93
|
};
|
|
94
|
-
readonly
|
|
94
|
+
readonly propagate: {
|
|
95
95
|
readonly description: "Whether this flag propagates to subcommands in nested command trees.\n\nWhen `true`, the flag is automatically available to all descendant\ncommands. A child command that defines a flag with the same name\nshadows the propagated parent flag.";
|
|
96
96
|
};
|
|
97
97
|
};
|
|
98
98
|
};
|
|
99
|
-
readonly
|
|
99
|
+
readonly arg: {
|
|
100
100
|
readonly description: "The runtime descriptor stored inside every ArgBuilder. Consumers (parser,\nhelp generator) read this to understand the arg's shape without touching\ngenerics.";
|
|
101
101
|
readonly properties: {
|
|
102
|
-
readonly
|
|
102
|
+
readonly name: {
|
|
103
103
|
readonly description: "A named positional argument entry in the command schema.\n\nPairs a user-facing arg name with its ArgSchema descriptor.\nThe array ordering in CommandSchema.args determines CLI position.";
|
|
104
104
|
};
|
|
105
|
-
readonly
|
|
105
|
+
readonly kind: {
|
|
106
106
|
readonly description: "What kind of value this arg accepts.";
|
|
107
107
|
};
|
|
108
|
-
readonly
|
|
109
|
-
readonly description: "Presence describes whether a positional arg is guaranteed to exist when the\naction handler runs:\n\n- `'required'`
|
|
108
|
+
readonly presence: {
|
|
109
|
+
readonly description: "Presence describes whether a positional arg is guaranteed to exist when the\naction handler runs:\n\n- `'required'` — must be supplied; error if missing (default)\n- `'optional'` — may be `undefined` if not supplied\n- `'defaulted'` — always present (falls back to default value)";
|
|
110
110
|
};
|
|
111
|
-
readonly
|
|
111
|
+
readonly variadic: {
|
|
112
112
|
readonly description: "Whether this arg consumes all remaining positionals.";
|
|
113
113
|
};
|
|
114
|
-
readonly
|
|
114
|
+
readonly stdinMode: {
|
|
115
115
|
readonly description: "Whether this arg may read from stdin during resolution.";
|
|
116
116
|
};
|
|
117
|
-
readonly
|
|
117
|
+
readonly defaultValue: {
|
|
118
118
|
readonly description: "Runtime default value (if any).";
|
|
119
119
|
};
|
|
120
|
-
readonly
|
|
120
|
+
readonly description: {
|
|
121
121
|
readonly description: "Human-readable description for help text.";
|
|
122
122
|
};
|
|
123
|
-
readonly
|
|
123
|
+
readonly envVar: {
|
|
124
124
|
readonly description: "Environment variable name for env resolution.\n\nWhen set and the CLI value is absent, the resolver reads this env var\nand coerces the string to the arg's declared kind.";
|
|
125
125
|
};
|
|
126
|
-
readonly
|
|
126
|
+
readonly enumValues: {
|
|
127
127
|
readonly description: "Allowed literal values when `kind === 'enum'`.";
|
|
128
128
|
};
|
|
129
|
-
readonly
|
|
130
|
-
readonly description: "Deprecation marker.\n\n- `undefined`
|
|
129
|
+
readonly deprecated: {
|
|
130
|
+
readonly description: "Deprecation marker.\n\n- `undefined` — not deprecated (default)\n- `true` — deprecated with no migration message\n- `string` — deprecated with a reason/migration message\n\nWhen a deprecated arg is used, a warning is emitted to stderr.\nHelp text shows `[deprecated]` or `[deprecated: <reason>]`.";
|
|
131
131
|
};
|
|
132
132
|
};
|
|
133
133
|
};
|
|
134
|
-
readonly
|
|
134
|
+
readonly prompt: {
|
|
135
135
|
readonly description: "Discriminated union of all prompt configurations.\n\nUse the `kind` field to narrow:\n```ts\nif (config.kind === 'select') {\n config.choices // readonly SelectChoice[] | undefined\n}\n```";
|
|
136
136
|
readonly properties: {
|
|
137
|
-
readonly
|
|
138
|
-
readonly description: "The kind of interactive prompt to present.\n\n- `'confirm'`
|
|
137
|
+
readonly kind: {
|
|
138
|
+
readonly description: "The kind of interactive prompt to present.\n\n- `'confirm'` — yes/no boolean question\n- `'input'` — free-text string input\n- `'select'` — single selection from a list\n- `'multiselect'` — multiple selections from a list";
|
|
139
139
|
};
|
|
140
|
-
readonly
|
|
140
|
+
readonly message: {
|
|
141
141
|
readonly description: "The question displayed to the user.";
|
|
142
142
|
};
|
|
143
|
-
readonly
|
|
143
|
+
readonly placeholder: {
|
|
144
144
|
readonly description: "Placeholder text shown before user types (informational only).";
|
|
145
145
|
};
|
|
146
|
-
readonly
|
|
146
|
+
readonly choices: {
|
|
147
147
|
readonly description: "Available choices. When omitted for `enum` flags, the enum values\nfrom the flag schema are used automatically.";
|
|
148
148
|
};
|
|
149
|
-
readonly
|
|
149
|
+
readonly min: {
|
|
150
150
|
readonly description: "Minimum number of selections required.";
|
|
151
151
|
};
|
|
152
|
-
readonly
|
|
152
|
+
readonly max: {
|
|
153
153
|
readonly description: "Maximum number of selections allowed.";
|
|
154
154
|
};
|
|
155
155
|
};
|
|
156
156
|
};
|
|
157
|
-
readonly
|
|
157
|
+
readonly choice: {
|
|
158
158
|
readonly description: "A selectable option for SelectPromptConfig and MultiselectPromptConfig prompts.";
|
|
159
159
|
readonly properties: {
|
|
160
|
-
readonly
|
|
160
|
+
readonly value: {
|
|
161
161
|
readonly description: "The value returned when this choice is selected.";
|
|
162
162
|
};
|
|
163
|
-
readonly
|
|
163
|
+
readonly label: {
|
|
164
164
|
readonly description: "Display label shown to the user.";
|
|
165
165
|
};
|
|
166
|
-
readonly
|
|
166
|
+
readonly description: {
|
|
167
167
|
readonly description: "Optional description shown alongside the choice.";
|
|
168
168
|
};
|
|
169
169
|
};
|
|
170
170
|
};
|
|
171
|
-
readonly
|
|
171
|
+
readonly example: {
|
|
172
172
|
readonly description: "A single usage example shown in help text.";
|
|
173
173
|
readonly properties: {
|
|
174
|
-
readonly
|
|
174
|
+
readonly command: {
|
|
175
175
|
readonly description: "The command invocation (e.g. `'deploy production --force'`).";
|
|
176
176
|
};
|
|
177
|
-
readonly
|
|
177
|
+
readonly description: {
|
|
178
178
|
readonly description: "Optional description of what this example does.";
|
|
179
179
|
};
|
|
180
180
|
};
|