@kjanat/dreamcli 2.0.1 → 2.2.0

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.
@@ -6,176 +6,176 @@
6
6
  */
7
7
  declare const definitionMetaSchemaDescriptions: {
8
8
  readonly root: {
9
- readonly description: 'Runtime descriptor for the CLI program.\n\nStores the program name, version, description, and registered commands.\\\nBuilt incrementally by CLIBuilder.';
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 name: {
12
- readonly description: 'Program name (used in help text, usage lines, and completion scripts).';
11
+ readonly "name": {
12
+ readonly description: "Program name (used in help text, usage lines, and completion scripts).";
13
13
  };
14
- readonly version: {
15
- readonly description: 'Program version (shown by `--version`).';
14
+ readonly "version": {
15
+ readonly description: "Program version (shown by `--version`).";
16
16
  };
17
- readonly description: {
18
- readonly description: 'Program description (shown in root help).';
17
+ readonly "description": {
18
+ readonly description: "Program description (shown in root help).";
19
19
  };
20
- readonly defaultCommand: {
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.';
20
+ readonly "defaultCommand": {
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 commands: {
24
- readonly description: 'Registered commands (type-erased for heterogeneous storage).';
23
+ readonly "commands": {
24
+ readonly description: "Registered commands (type-erased for heterogeneous storage).";
25
25
  };
26
26
  };
27
27
  };
28
28
  readonly defs: {
29
- readonly command: {
29
+ readonly "command": {
30
30
  readonly description: "Runtime descriptor produced by CommandBuilder.\n\nConsumers (parser, help generator, CLI dispatcher) read this to\nunderstand the command's shape \u2014 flags, args, aliases, subcommands,\nmiddleware, and interactive resolver.";
31
31
  readonly properties: {
32
- readonly name: {
32
+ readonly "name": {
33
33
  readonly description: "The command name (used for dispatch, e.g. `'deploy'`).";
34
34
  };
35
- readonly description: {
36
- readonly description: 'Human-readable description for help text.';
35
+ readonly "description": {
36
+ readonly description: "Human-readable description for help text.";
37
37
  };
38
- readonly aliases: {
39
- readonly description: 'Alternative names for this command.';
38
+ readonly "aliases": {
39
+ readonly description: "Alternative names for this command.";
40
40
  };
41
- readonly hidden: {
42
- readonly description: 'Whether this command is hidden from help listings.';
41
+ readonly "hidden": {
42
+ readonly description: "Whether this command is hidden from help listings.";
43
43
  };
44
- readonly examples: {
45
- readonly description: 'Usage examples for help text.';
44
+ readonly "examples": {
45
+ readonly description: "Usage examples for help text.";
46
46
  };
47
- readonly flags: {
48
- readonly description: 'Named flag schemas, keyed by flag name.';
47
+ readonly "flags": {
48
+ readonly description: "Named flag schemas, keyed by flag name.";
49
49
  };
50
- readonly args: {
51
- readonly description: 'Ordered positional arg entries (name + schema).';
50
+ readonly "args": {
51
+ readonly description: "Ordered positional arg entries (name + schema).";
52
52
  };
53
- readonly commands: {
54
- readonly description: 'Nested subcommand schemas (for help rendering and completion).\n\nPure data \u2014 no execution closures. Populated by `.command()` on\n`CommandBuilder`. Empty for leaf commands.';
53
+ readonly "commands": {
54
+ readonly description: "Nested subcommand schemas (for help rendering and completion).\n\nPure data \u2014 no execution closures. Populated by `.command()` on\n`CommandBuilder`. Empty for leaf commands.";
55
55
  };
56
56
  };
57
57
  };
58
- readonly flag: {
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 kind: {
62
- readonly description: 'What kind of value this flag accepts.';
61
+ readonly "kind": {
62
+ readonly description: "What kind of value this flag accepts.";
63
63
  };
64
- readonly presence: {
64
+ readonly "presence": {
65
65
  readonly description: "Presence describes whether a flag value is guaranteed to exist when the\naction handler runs:\n\n- `'optional'` \u2014 not required; unresolved value follows the kind-specific\n optional fallback (`undefined` for most flags, `[]` for arrays)\n- `'required'` \u2014 must be supplied; error if missing\n- `'defaulted'` \u2014 always present (falls back to default value)";
66
66
  };
67
- readonly defaultValue: {
68
- readonly description: 'Runtime default value (if any).';
67
+ readonly "defaultValue": {
68
+ readonly description: "Runtime default value (if any).";
69
69
  };
70
- readonly aliases: {
70
+ readonly "aliases": {
71
71
  readonly description: "Short/long aliases (e.g. `[{ name: 'f', hidden: false }]` for `--force`).";
72
72
  };
73
- readonly envVar: {
74
- readonly description: 'Environment variable name for v0.2+ resolution.';
73
+ readonly "envVar": {
74
+ readonly description: "Environment variable name for v0.2+ resolution.";
75
75
  };
76
- readonly configPath: {
76
+ readonly "configPath": {
77
77
  readonly description: "Dotted config path for v0.2+ resolution (e.g. `'deploy.region'`).";
78
78
  };
79
- readonly description: {
80
- readonly description: 'Human-readable description for help text.';
79
+ readonly "description": {
80
+ readonly description: "Human-readable description for help text.";
81
81
  };
82
- readonly enumValues: {
82
+ readonly "enumValues": {
83
83
  readonly description: "Allowed literal values when `kind === 'enum'`.";
84
84
  };
85
- readonly elementSchema: {
85
+ readonly "elementSchema": {
86
86
  readonly description: "Element schema when `kind === 'array'`.";
87
87
  };
88
- readonly prompt: {
89
- readonly description: 'Interactive prompt configuration for v0.3+ resolution.';
88
+ readonly "prompt": {
89
+ readonly description: "Interactive prompt configuration for v0.3+ resolution.";
90
90
  };
91
- readonly deprecated: {
92
- readonly description: 'Deprecation marker.\n\n- `undefined` \u2014 not deprecated (default)\n- `true` \u2014 deprecated with no migration message\n- `string` \u2014 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>]`.';
91
+ readonly "deprecated": {
92
+ readonly description: "Deprecation marker.\n\n- `undefined` \u2014 not deprecated (default)\n- `true` \u2014 deprecated with no migration message\n- `string` \u2014 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 propagate: {
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.';
94
+ readonly "propagate": {
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 arg: {
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 name: {
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.';
102
+ readonly "name": {
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 kind: {
106
- readonly description: 'What kind of value this arg accepts.';
105
+ readonly "kind": {
106
+ readonly description: "What kind of value this arg accepts.";
107
107
  };
108
- readonly presence: {
108
+ readonly "presence": {
109
109
  readonly description: "Presence describes whether a positional arg is guaranteed to exist when the\naction handler runs:\n\n- `'required'` \u2014 must be supplied; error if missing (default)\n- `'optional'` \u2014 may be `undefined` if not supplied\n- `'defaulted'` \u2014 always present (falls back to default value)";
110
110
  };
111
- readonly variadic: {
112
- readonly description: 'Whether this arg consumes all remaining positionals.';
111
+ readonly "variadic": {
112
+ readonly description: "Whether this arg consumes all remaining positionals.";
113
113
  };
114
- readonly stdinMode: {
115
- readonly description: 'Whether this arg may read from stdin during resolution.';
114
+ readonly "stdinMode": {
115
+ readonly description: "Whether this arg may read from stdin during resolution.";
116
116
  };
117
- readonly defaultValue: {
118
- readonly description: 'Runtime default value (if any).';
117
+ readonly "defaultValue": {
118
+ readonly description: "Runtime default value (if any).";
119
119
  };
120
- readonly description: {
121
- readonly description: 'Human-readable description for help text.';
120
+ readonly "description": {
121
+ readonly description: "Human-readable description for help text.";
122
122
  };
123
- readonly envVar: {
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 enumValues: {
126
+ readonly "enumValues": {
127
127
  readonly description: "Allowed literal values when `kind === 'enum'`.";
128
128
  };
129
- readonly deprecated: {
130
- readonly description: 'Deprecation marker.\n\n- `undefined` \u2014 not deprecated (default)\n- `true` \u2014 deprecated with no migration message\n- `string` \u2014 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>]`.';
129
+ readonly "deprecated": {
130
+ readonly description: "Deprecation marker.\n\n- `undefined` \u2014 not deprecated (default)\n- `true` \u2014 deprecated with no migration message\n- `string` \u2014 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 prompt: {
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 kind: {
137
+ readonly "kind": {
138
138
  readonly description: "The kind of interactive prompt to present.\n\n- `'confirm'` \u2014 yes/no boolean question\n- `'input'` \u2014 free-text string input\n- `'select'` \u2014 single selection from a list\n- `'multiselect'` \u2014 multiple selections from a list";
139
139
  };
140
- readonly message: {
141
- readonly description: 'The question displayed to the user.';
140
+ readonly "message": {
141
+ readonly description: "The question displayed to the user.";
142
142
  };
143
- readonly placeholder: {
144
- readonly description: 'Placeholder text shown before user types (informational only).';
143
+ readonly "placeholder": {
144
+ readonly description: "Placeholder text shown before user types (informational only).";
145
145
  };
146
- readonly choices: {
147
- readonly description: 'Available choices. When omitted for `enum` flags, the enum values\nfrom the flag schema are used automatically.';
146
+ readonly "choices": {
147
+ readonly description: "Available choices. When omitted for `enum` flags, the enum values\nfrom the flag schema are used automatically.";
148
148
  };
149
- readonly min: {
150
- readonly description: 'Minimum number of selections required.';
149
+ readonly "min": {
150
+ readonly description: "Minimum number of selections required.";
151
151
  };
152
- readonly max: {
153
- readonly description: 'Maximum number of selections allowed.';
152
+ readonly "max": {
153
+ readonly description: "Maximum number of selections allowed.";
154
154
  };
155
155
  };
156
156
  };
157
- readonly choice: {
158
- readonly description: 'A selectable option for SelectPromptConfig and MultiselectPromptConfig prompts.';
157
+ readonly "choice": {
158
+ readonly description: "A selectable option for SelectPromptConfig and MultiselectPromptConfig prompts.";
159
159
  readonly properties: {
160
- readonly value: {
161
- readonly description: 'The value returned when this choice is selected.';
160
+ readonly "value": {
161
+ readonly description: "The value returned when this choice is selected.";
162
162
  };
163
- readonly label: {
164
- readonly description: 'Display label shown to the user.';
163
+ readonly "label": {
164
+ readonly description: "Display label shown to the user.";
165
165
  };
166
- readonly description: {
167
- readonly description: 'Optional description shown alongside the choice.';
166
+ readonly "description": {
167
+ readonly description: "Optional description shown alongside the choice.";
168
168
  };
169
169
  };
170
170
  };
171
- readonly example: {
172
- readonly description: 'A single usage example shown in help text.';
171
+ readonly "example": {
172
+ readonly description: "A single usage example shown in help text.";
173
173
  readonly properties: {
174
- readonly command: {
174
+ readonly "command": {
175
175
  readonly description: "The command invocation (e.g. `'deploy production --force'`).";
176
176
  };
177
- readonly description: {
178
- readonly description: 'Optional description of what this example does.';
177
+ readonly "description": {
178
+ readonly description: "Optional description of what this example does.";
179
179
  };
180
180
  };
181
181
  };
@@ -1,4 +1,5 @@
1
- import { FlagSchema } from "../schema/flag.mjs";
1
+ import { PromptKind } from "../schema/prompt.mjs";
2
+ import { FlagKind, FlagSchema } from "../schema/flag.mjs";
2
3
  import { PromptEngine } from "../prompt/index.mjs";
3
4
  import { DeprecationWarning } from "./contracts.mjs";
4
5
  import { ErasedInteractiveResolver } from "../schema/command.mjs";
@@ -6,5 +7,7 @@ import { ErasedInteractiveResolver } from "../schema/command.mjs";
6
7
  //#region src/core/resolve/flags.d.ts
7
8
  /** Walk every declared flag through the resolution chain (cli -> env -> config -> prompt -> default), collecting deprecations and throwing aggregated errors. */
8
9
  declare function resolveFlags(flagSchemas: Readonly<Record<string, FlagSchema>>, parsedFlags: Readonly<Record<string, unknown>>, env: Readonly<Record<string, string | undefined>>, config: Readonly<Record<string, unknown>>, prompter: PromptEngine | undefined, interactive: ErasedInteractiveResolver | undefined, deprecations: DeprecationWarning[]): Promise<Readonly<Record<string, unknown>>>;
10
+ /** Maps each flag kind to the prompt kinds that produce compatible values. */
11
+ declare const COMPATIBLE_PROMPT_KINDS: Record<FlagKind, readonly PromptKind[]>;
9
12
  //#endregion
10
- export { resolveFlags };
13
+ export { COMPATIBLE_PROMPT_KINDS, resolveFlags };
@@ -1 +1 @@
1
- import{ValidationError as e}from"../errors/index.mjs";import{resolvePromptConfig as t}from"../prompt/index.mjs";import{coerceValue as n}from"./coerce.mjs";import{isNonEmpty as r,throwAggregatedErrors as i}from"./errors.mjs";import{resolveConfigPath as a}from"./config.mjs";async function o(t,o,l,u,d,f,p){let m={},h=[],g=new Set;for(let[e,r]of Object.entries(t)){let t=Object.hasOwn(o,e),i=o[e];if(t&&i!==void 0){r.deprecated!==void 0&&p.push({kind:`flag`,name:e,message:r.deprecated}),m[e]=i;continue}if(r.envVar!==void 0){let t=l[r.envVar];if(t!==void 0){let i=n(e,{kind:`env`,envVar:r.envVar},t,r);if(i.ok){r.deprecated!==void 0&&p.push({kind:`flag`,name:e,message:r.deprecated}),m[e]=i.value;continue}h.push(i.error),g.add(e);continue}}if(r.configPath!==void 0){let t=a(u,r.configPath);if(t!==void 0){let i=n(e,{kind:`config`,configPath:r.configPath},t,r);if(i.ok){r.deprecated!==void 0&&p.push({kind:`flag`,name:e,message:r.deprecated}),m[e]=i.value;continue}h.push(i.error),g.add(e)}}}let _=f===void 0?void 0:f({flags:m});for(let[n,r]of Object.entries(t)){if(Object.hasOwn(m,n)||g.has(n))continue;let t=_?.[n],i;if(i=t!=null&&t!==!1&&t!==0&&t!==``?t:t===!1?void 0:r.prompt,i!==void 0&&d!==void 0){let e=await s(n,r,i,d);if(e.ok){r.deprecated!==void 0&&p.push({kind:`flag`,name:n,message:r.deprecated}),m[n]=e.value;continue}if(e.error!==void 0){h.push(e.error);continue}}if(r.defaultValue!==void 0){m[n]=r.defaultValue;continue}if(r.kind===`array`&&r.presence!==`required`){m[n]=[];continue}if(r.presence===`required`){let t={flag:n,kind:r.kind};r.envVar!==void 0&&(t.envVar=r.envVar),r.configPath!==void 0&&(t.configPath=r.configPath),h.push(new e(`Missing required flag --${n}`,{code:`REQUIRED_FLAG`,details:t,suggest:c(n,r)}));continue}m[n]=void 0}return r(h)&&i(h),m}async function s(e,r,i,a){let o=t(i,r.enumValues),s=await a.promptOne(o);return s.answered?n(e,{kind:`prompt`},s.value,r):{ok:!1,error:void 0}}function c(e,t){let n=[];if(n.push(`Provide --${e}${t.kind===`boolean`?``:` <value>`}`),t.envVar!==void 0&&n.push(`set ${t.envVar}`),t.configPath!==void 0&&n.push(`add ${t.configPath} to config`),n.length<=1)return n.join(``);let r=n.slice(0,-1),i=n.slice(-1).join(``);return n.length===2?`${r.join(``)} or ${i}`:`${r.join(`, `)}, or ${i}`}export{o as resolveFlags};
1
+ import{ValidationError as e}from"../errors/index.mjs";import{resolvePromptConfig as t}from"../prompt/index.mjs";import{coerceValue as n}from"./coerce.mjs";import{isNonEmpty as r,throwAggregatedErrors as i}from"./errors.mjs";import{resolveConfigPath as a}from"./config.mjs";async function o(t,o,s,c,d,f,p){let m={},h=[],g=new Set;for(let[e,r]of Object.entries(t)){let t=Object.hasOwn(o,e),i=o[e];if(t&&i!==void 0){r.deprecated!==void 0&&p.push({kind:`flag`,name:e,message:r.deprecated}),m[e]=i;continue}if(r.envVar!==void 0){let t=s[r.envVar];if(t!==void 0){let i=n(e,{kind:`env`,envVar:r.envVar},t,r);if(i.ok){r.deprecated!==void 0&&p.push({kind:`flag`,name:e,message:r.deprecated}),m[e]=i.value;continue}h.push(i.error),g.add(e);continue}}if(r.configPath!==void 0){let t=a(c,r.configPath);if(t!==void 0){let i=n(e,{kind:`config`,configPath:r.configPath},t,r);if(i.ok){r.deprecated!==void 0&&p.push({kind:`flag`,name:e,message:r.deprecated}),m[e]=i.value;continue}h.push(i.error),g.add(e)}}}let _=f===void 0?void 0:f({flags:m});for(let[n,r]of Object.entries(t)){if(Object.hasOwn(m,n)||g.has(n))continue;let t=_?.[n],i;if(i=t!=null&&t!==!1&&t!==0&&t!==``?t:t===!1?void 0:r.prompt,i!==void 0&&d!==void 0){let e=await l(n,r,i,d);if(e.ok){r.deprecated!==void 0&&p.push({kind:`flag`,name:n,message:r.deprecated}),m[n]=e.value;continue}if(e.error!==void 0){h.push(e.error);continue}}if(r.defaultValue!==void 0){m[n]=r.defaultValue;continue}if(r.kind===`array`&&r.presence!==`required`){m[n]=[];continue}if(r.presence===`required`){let t={flag:n,kind:r.kind};r.envVar!==void 0&&(t.envVar=r.envVar),r.configPath!==void 0&&(t.configPath=r.configPath),h.push(new e(`Missing required flag --${n}`,{code:`REQUIRED_FLAG`,details:t,suggest:u(n,r)}));continue}m[n]=void 0}return r(h)&&i(h),m}const s={boolean:[`confirm`],string:[`input`,`select`],number:[`input`],enum:[`select`,`input`],array:[`multiselect`],custom:[`input`,`select`,`confirm`,`multiselect`]};function c(t,n,r){let i=s[n];if(!i.includes(r))return new e(`Prompt kind '${r}' is not compatible with ${n} flag --${t}. Use '${i[0]}' instead`,{code:`CONSTRAINT_VIOLATED`,details:{flag:t,flagKind:n,promptKind:r,allowed:i},suggest:`Change the prompt to { kind: '${i[0]}' } for --${t}`})}async function l(e,r,i,a){let o=c(e,r.kind,i.kind);if(o!==void 0)return{ok:!1,error:o};let s=t(i,r.enumValues),l=await a.promptOne(s);return l.answered?n(e,{kind:`prompt`},l.value,r):{ok:!1,error:void 0}}function u(e,t){let n=[];if(n.push(`Provide --${e}${t.kind===`boolean`?``:` <value>`}`),t.envVar!==void 0&&n.push(`set ${t.envVar}`),t.configPath!==void 0&&n.push(`add ${t.configPath} to config`),n.length<=1)return n.join(``);let r=n.slice(0,-1),i=n.slice(-1).join(``);return n.length===2?`${r.join(``)} or ${i}`:`${r.join(`, `)}, or ${i}`}export{o as resolveFlags};
@@ -33,6 +33,8 @@ interface FlagConfig {
33
33
  readonly presence: FlagPresence;
34
34
  /** What an unresolved optional flag becomes at the action boundary. */
35
35
  readonly optionalFallback: OptionalFallback;
36
+ /** The runtime kind discriminator, mirroring {@link FlagKind}. */
37
+ readonly flagKind: FlagKind;
36
38
  }
37
39
  /**
38
40
  * Advanced type helper used by {@linkcode FlagBuilder} modifiers to replace presence.
@@ -42,6 +44,7 @@ type WithPresence<C extends FlagConfig, P extends FlagPresence> = {
42
44
  readonly valueType: C['valueType'];
43
45
  readonly presence: P;
44
46
  readonly optionalFallback: C['optionalFallback'];
47
+ readonly flagKind: C['flagKind'];
45
48
  };
46
49
  /**
47
50
  * Compute the final value type from config — this is what handlers receive.
@@ -59,6 +62,27 @@ type ResolvedValue<C extends FlagConfig> = C['presence'] extends 'optional' ? C[
59
62
  type InferFlag<B> = B extends FlagBuilder<infer C extends FlagConfig> ? ResolvedValue<C> : never;
60
63
  /** Extract resolved value types from a record of builders. */
61
64
  type InferFlags<T extends Record<string, FlagBuilder<FlagConfig>>> = { [K in keyof T]: InferFlag<T[K]> };
65
+ /**
66
+ * Maps a {@linkcode FlagConfig} to the prompt config types that are compatible
67
+ * with the flag's kind. Prevents compile-time mismatches such as
68
+ * `flag.enum([…]).prompt({ kind: 'multiselect' })`.
69
+ *
70
+ * - `'boolean'` → {@link ConfirmPromptConfig}
71
+ * - `'string'` → {@link InputPromptConfig} | {@link SelectPromptConfig}
72
+ * - `'number'` → {@link InputPromptConfig}
73
+ * - `'enum'` → {@link SelectPromptConfig} | {@link InputPromptConfig}
74
+ * - `'array'` → {@link MultiselectPromptConfig}
75
+ * - `'custom'` → all prompt kinds ({@link PromptConfig})
76
+ */
77
+ type PromptConfigByFlagKind = {
78
+ readonly string: InputPromptConfig | SelectPromptConfig;
79
+ readonly number: InputPromptConfig;
80
+ readonly boolean: ConfirmPromptConfig;
81
+ readonly enum: SelectPromptConfig | InputPromptConfig;
82
+ readonly array: MultiselectPromptConfig;
83
+ readonly custom: PromptConfig;
84
+ };
85
+ type AllowedPromptConfig<C extends FlagConfig> = PromptConfigByFlagKind[C['flagKind']];
62
86
  /** All flag kind discriminators as a runtime array. */
63
87
  declare const FLAG_KINDS: readonly ['string', 'number', 'boolean', 'enum', 'array', 'custom'];
64
88
  /** Discriminator for the kind of value a flag accepts. */
@@ -330,7 +354,7 @@ declare class FlagBuilder<C extends FlagConfig> {
330
354
  * // $ mycli init --name foo → skips prompt, uses CLI value
331
355
  * ```
332
356
  */
333
- prompt(config: PromptConfig): FlagBuilder<C>;
357
+ prompt(config: AllowedPromptConfig<C>): FlagBuilder<C>;
334
358
  /**
335
359
  * Mark this flag as deprecated.
336
360
  *
@@ -388,6 +412,7 @@ interface FlagFactory {
388
412
  readonly valueType: string;
389
413
  readonly presence: 'optional';
390
414
  readonly optionalFallback: 'undefined';
415
+ readonly flagKind: 'string';
391
416
  }>;
392
417
  /**
393
418
  * Number-valued flag.
@@ -398,6 +423,7 @@ interface FlagFactory {
398
423
  readonly valueType: number;
399
424
  readonly presence: 'optional';
400
425
  readonly optionalFallback: 'undefined';
426
+ readonly flagKind: 'number';
401
427
  }>;
402
428
  /**
403
429
  * Boolean flag. Implicitly defaults to `false` — the only flag kind where
@@ -409,6 +435,7 @@ interface FlagFactory {
409
435
  readonly valueType: boolean;
410
436
  readonly presence: 'defaulted';
411
437
  readonly optionalFallback: 'undefined';
438
+ readonly flagKind: 'boolean';
412
439
  }>;
413
440
  /**
414
441
  * Enum flag with literal type inference.
@@ -429,6 +456,7 @@ interface FlagFactory {
429
456
  readonly valueType: T[number];
430
457
  readonly presence: 'optional';
431
458
  readonly optionalFallback: 'undefined';
459
+ readonly flagKind: 'enum';
432
460
  }>;
433
461
  /**
434
462
  * Array flag — collects multiple values of the same element type.
@@ -446,6 +474,7 @@ interface FlagFactory {
446
474
  readonly valueType: E['valueType'][];
447
475
  readonly presence: 'optional';
448
476
  readonly optionalFallback: 'empty-array';
477
+ readonly flagKind: 'array';
449
478
  }>;
450
479
  /**
451
480
  * Custom-parsed flag. The parse function receives the raw value and must
@@ -480,6 +509,7 @@ interface FlagFactory {
480
509
  readonly valueType: T;
481
510
  readonly presence: 'optional';
482
511
  readonly optionalFallback: 'undefined';
512
+ readonly flagKind: 'custom';
483
513
  }>;
484
514
  }
485
515
  /**
@@ -488,4 +518,4 @@ interface FlagFactory {
488
518
  */
489
519
  declare const flag: FlagFactory;
490
520
  //#endregion
491
- export { type ConfirmPromptConfig, FLAG_KINDS, FLAG_PRESENCES, type FlagAlias, FlagBuilder, type FlagConfig, type FlagFactory, type FlagKind, type FlagParseFn, type FlagPresence, type FlagSchema, type FlagSchemaOverrides, type InferFlag, type InferFlags, type InputPromptConfig, type MultiselectPromptConfig, type OptionalFallback, PROMPT_KINDS, type PromptConfig, type PromptConfigBase, type PromptKind, type PromptResult, type ResolvedValue, type SelectChoice, type SelectPromptConfig, type WithPresence, createSchema, flag, getFlagAliasNames, normalizeFlagAlias, normalizeFlagAliases };
521
+ export { type AllowedPromptConfig, type ConfirmPromptConfig, FLAG_KINDS, FLAG_PRESENCES, type FlagAlias, FlagBuilder, type FlagConfig, type FlagFactory, type FlagKind, type FlagParseFn, type FlagPresence, type FlagSchema, type FlagSchemaOverrides, type InferFlag, type InferFlags, type InputPromptConfig, type MultiselectPromptConfig, type OptionalFallback, PROMPT_KINDS, type PromptConfig, type PromptConfigBase, type PromptKind, type PromptResult, type ResolvedValue, type SelectChoice, type SelectPromptConfig, type WithPresence, createSchema, flag, getFlagAliasNames, normalizeFlagAlias, normalizeFlagAliases };
@@ -1 +1 @@
1
- const e=[{runtime:`node`,displayName:`Node.js`,minimum:`22.22.2`,engineRange:`>=22.22.2`,packageName:`@kjanat/dreamcli`,adapterName:`NodeAdapter`},{runtime:`bun`,displayName:`Bun`,minimum:`1.3.11`,engineRange:`>=1.3.11`,packageName:`@kjanat/dreamcli`,adapterName:`BunAdapter`},{runtime:`deno`,displayName:`Deno`,minimum:`2.6.0`,engineRange:`>=2.6.0`,packageName:`@kjanat/dreamcli`,adapterName:`DenoAdapter`}],t=/^(\d+)(?:\.(\d+))?(?:\.(\d+))?/;function n(t){for(let n of e)if(n.runtime===t)return n;throw Error(`Unknown supported runtime '${t}'`)}function r(e){let n=t.exec(e);if(n===null)return;let r=Number.parseInt(n[1]??``,10),i=n[2],a=i===void 0?0:Number.parseInt(i,10),o=n[3],s=o===void 0?0:Number.parseInt(o,10);if(!(Number.isNaN(r)||Number.isNaN(a)||Number.isNaN(s)))return{major:r,minor:a,patch:s}}function i(e,t){return e.major===t.major?e.minor===t.minor?e.patch-t.patch:e.minor-t.minor:e.major-t.major}function a(e){let t=n(e);return`${t.displayName} >= ${t.minimum}`}function o(e,t){let a=r(t),o=r(n(e).minimum);return a===void 0||o===void 0?!1:i(a,o)>=0}function s(e,t){if(t!==void 0&&!o(e,t))throw Error(`@kjanat/dreamcli requires ${a(e)}. Detected ${n(e).displayName} ${t}.`)}export{s as assertRuntimeVersionSupported};
1
+ const e=[{runtime:`node`,displayName:`Node.js`,minimum:`22.22.2`,engineRange:`>=22.22.2`,packageName:`@kjanat/dreamcli`,adapterName:`NodeAdapter`},{runtime:`bun`,displayName:`Bun`,minimum:`1.3`,engineRange:`>=1.3`,packageName:`@kjanat/dreamcli`,adapterName:`BunAdapter`},{runtime:`deno`,displayName:`Deno`,minimum:`2.6.0`,engineRange:`>=2.6.0`,packageName:`@kjanat/dreamcli`,adapterName:`DenoAdapter`}],t=/^(\d+)(?:\.(\d+))?(?:\.(\d+))?/;function n(t){for(let n of e)if(n.runtime===t)return n;throw Error(`Unknown supported runtime '${t}'`)}function r(e){let n=t.exec(e);if(n===null)return;let r=Number.parseInt(n[1]??``,10),i=n[2],a=i===void 0?0:Number.parseInt(i,10),o=n[3],s=o===void 0?0:Number.parseInt(o,10);if(!(Number.isNaN(r)||Number.isNaN(a)||Number.isNaN(s)))return{major:r,minor:a,patch:s}}function i(e,t){return e.major===t.major?e.minor===t.minor?e.patch-t.patch:e.minor-t.minor:e.major-t.major}function a(e){let t=n(e);return`${t.displayName} >= ${t.minimum}`}function o(e,t){let a=r(t),o=r(n(e).minimum);return a===void 0||o===void 0?!1:i(a,o)>=0}function s(e,t){if(t!==void 0&&!o(e,t))throw Error(`@kjanat/dreamcli requires ${a(e)}. Detected ${n(e).displayName} ${t}.`)}export{s as assertRuntimeVersionSupported};
package/dist/version.mjs CHANGED
@@ -1 +1 @@
1
- const e=`2.0.1`,t=`c94ef5e`;export{t as DREAMCLI_REVISION,e as DREAMCLI_VERSION};
1
+ const e=`2.2.0`,t=`2ca0220`;export{t as DREAMCLI_REVISION,e as DREAMCLI_VERSION};
@@ -30,14 +30,14 @@
30
30
  "@types/bun": "catalog:",
31
31
  "typescript": "catalog:"
32
32
  },
33
- "packageManager": "bun@1.3.11",
33
+ "packageManager": "bun@1.3.12",
34
34
  "engines": {
35
- "bun": ">=1.3.11"
35
+ "bun": "^1.3"
36
36
  },
37
37
  "devEngines": {
38
38
  "runtime": {
39
39
  "name": "bun",
40
- "version": ">=1.3.11",
40
+ "version": "^1.3",
41
41
  "onFail": "error"
42
42
  }
43
43
  }
@@ -0,0 +1,40 @@
1
+ # pwsh-demo
2
+
3
+ PowerShell completion playground for `@kjanat/dreamcli`.
4
+
5
+ This example is intentionally shaped to exercise a broad slice of the completion surface:
6
+
7
+ - Native PowerShell registration via `Register-ArgumentCompleter`
8
+ - Root-surface completion from a default command
9
+ - Top-level command aliases like `ship` and `st`
10
+ - Nested subcommands under `config`
11
+ - Enum flag value completion like `--region`, `--strategy`, `--view`, and `--profile`
12
+ - Hidden command and hidden flag-alias omission from completions
13
+
14
+ ## Try It
15
+
16
+ From this directory:
17
+
18
+ ```powershell
19
+ $env:PATH = "$(Get-Location);$env:PATH"
20
+ bun src/main.ts completions powershell | Out-String | Invoke-Expression
21
+ ```
22
+
23
+ Then try these interactively:
24
+
25
+ ```powershell
26
+ pwsh-demo de<Tab>
27
+ pwsh-demo ship --str<Tab>
28
+ pwsh-demo deploy --region <Tab>
29
+ pwsh-demo st --view <Tab>
30
+ pwsh-demo --pro<Tab>
31
+ pwsh-demo --profile q<Tab>
32
+ pwsh-demo --profile=q<Tab>
33
+ pwsh-demo config se<Tab>
34
+ ```
35
+
36
+ Or run the automated smoke check:
37
+
38
+ ```powershell
39
+ bun run smoke:powershell
40
+ ```
@@ -0,0 +1,47 @@
1
+ {
2
+ "name": "pwsh-demo",
3
+ "version": "0.0.0-example",
4
+ "private": true,
5
+ "description": "PowerShell completion playground for dreamcli",
6
+ "repository": {
7
+ "type": "git",
8
+ "url": "git+https://github.com/kjanat/dreamcli.git",
9
+ "directory": "examples/pwsh-demo"
10
+ },
11
+ "type": "module",
12
+ "module": "src/main.ts",
13
+ "bin": {
14
+ "pwsh-demo": "src/main.ts"
15
+ },
16
+ "files": [
17
+ "src",
18
+ "README.md",
19
+ "smoke-powershell.ps1",
20
+ "pwsh-demo.cmd",
21
+ "!src/**/*.test.ts"
22
+ ],
23
+ "scripts": {
24
+ "build": "bun build src/main.ts --install --outdir=dist --format=esm --target=node --external @kjanat/dreamcli",
25
+ "smoke:powershell": "pwsh -NoLogo -NoProfile -ExecutionPolicy Bypass -File ./smoke-powershell.ps1",
26
+ "test": "bun test",
27
+ "typecheck": "tsc --noEmit"
28
+ },
29
+ "dependencies": {
30
+ "@kjanat/dreamcli": "link:@kjanat/dreamcli"
31
+ },
32
+ "devDependencies": {
33
+ "@types/bun": "catalog:",
34
+ "typescript": "catalog:"
35
+ },
36
+ "packageManager": "bun@1.3.12",
37
+ "engines": {
38
+ "bun": "^1.3"
39
+ },
40
+ "devEngines": {
41
+ "runtime": {
42
+ "name": "bun",
43
+ "version": "^1.3",
44
+ "onFail": "error"
45
+ }
46
+ }
47
+ }
@@ -0,0 +1,3 @@
1
+ @echo off
2
+ bun --cwd "%~dp0." src\main.ts %*
3
+ exit /b %errorlevel%