@kjanat/dreamcli 4.1.0 → 5.0.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.
Files changed (43) hide show
  1. package/README.md +3 -1
  2. package/dist/{adapter-YM5QGi3M.d.mts → adapter-DBeedKmD.d.mts} +5 -3
  3. package/dist/{completion-CUMeOnAz.mjs → completion-Bh-qywmB.mjs} +4 -4
  4. package/dist/completion.d.mts +1 -11
  5. package/dist/completion.mjs +1 -1
  6. package/dist/config-DruA8aFV.mjs +1 -0
  7. package/dist/config.d.mts +1 -1
  8. package/dist/config.mjs +1 -1
  9. package/dist/core-B9YNSJeA.mjs +19 -0
  10. package/dist/{index-Cap0MA2V.d.mts → index-AIC5Gler.d.mts} +18 -12
  11. package/dist/{index-BziI2aKc.d.mts → index-BIMjOsR6.d.mts} +316 -53
  12. package/dist/{index-3l8uj16E.d.mts → index-BidVVmln.d.mts} +51 -11
  13. package/dist/index-D683D09G.d.mts +129 -0
  14. package/dist/{index-DWsnGZlx.d.mts → index-DpslpOVV.d.mts} +160 -154
  15. package/dist/{index-BAj2y70U.d.mts → index-hzYPRc_O.d.mts} +65 -14
  16. package/dist/{index-Cp9kt2t-.d.mts → index-jq_FJRKt.d.mts} +1 -7
  17. package/dist/index.d.mts +18 -11
  18. package/dist/index.mjs +1 -1
  19. package/dist/json-schema-DF5fXdKQ.mjs +59 -0
  20. package/dist/json-schema.d.mts +2 -2
  21. package/dist/json-schema.mjs +1 -1
  22. package/dist/package-json-fYhxDdWD.mjs +3 -0
  23. package/dist/prompt.d.mts +32 -5
  24. package/dist/prompt.mjs +1 -1
  25. package/dist/runtime.d.mts +2 -2
  26. package/dist/runtime.mjs +1 -1
  27. package/dist/session-Crtzt7LY.mjs +1 -0
  28. package/dist/terminal-DRsRn4sc.mjs +7 -0
  29. package/dist/test-prompter-BLNGCOA_.mjs +1 -0
  30. package/dist/testkit.d.mts +5 -7
  31. package/dist/testkit.mjs +1 -1
  32. package/dist/version.d.mts +1 -3
  33. package/dist/version.mjs +1 -1
  34. package/dreamcli.schema.json +155 -3
  35. package/package.json +24 -24
  36. package/skills/cli-creation/SKILL.md +1 -1
  37. package/skills/cli-creation/scripts/scaffold_cli.py +12 -4
  38. package/dist/config-CrlScpYX.mjs +0 -1
  39. package/dist/core-DvXUolc_.mjs +0 -17
  40. package/dist/json-schema-DRlrz_IV.mjs +0 -52
  41. package/dist/package-json-BgE9YjjQ.mjs +0 -3
  42. package/dist/terminal-C8KTXjv5.mjs +0 -6
  43. package/dist/test-prompter-v__jT2yG.mjs +0 -1
@@ -1,7 +1,6 @@
1
- import { Bt as FlagKind, Pn as NumberConstraints, Q as ArgKind, T as ExampleMeta, Ut as FlagPresence, b as CommandSchema, et as ArgPresence, jt as DuplicatePolicy, kn as PromptKind, vt as DuplicateKeys } from "./index-BziI2aKc.mjs";
2
- import "./index-DWsnGZlx.mjs";
3
- import { o as CLISchema } from "./index-BAj2y70U.mjs";
4
- //#region src/core/json-schema/constants.d.ts
1
+ import { Kt as FlagPresence, Nn as PromptKind, Pt as DuplicatePolicy, Rn as NumberConstraints, T as ExampleMeta, Ut as FlagKind, b as CommandSchema, rt as ArgPresence, tt as ArgKind, xt as DuplicateKeys } from "./index-BIMjOsR6.mjs";
2
+ import "./index-DpslpOVV.mjs";
3
+ import { o as CLISchema } from "./index-hzYPRc_O.mjs";
5
4
  /**
6
5
  * Identifiers of the definition document format.
7
6
  *
@@ -24,8 +23,6 @@ declare const DEFINITION_SCHEMA_URL = "https://dreamcli.kjanat.dev/schemas/defin
24
23
  * and `generateCommandSchema()` from `@kjanat/dreamcli/json-schema`.
25
24
  */
26
25
  declare const DEFINITION_SCHEMA_VERSION = 1;
27
- //#endregion
28
- //#region src/core/json-schema/index.d.ts
29
26
  /**
30
27
  * Options for JSON Schema generation.
31
28
  *
@@ -56,6 +53,17 @@ interface JsonSchemaOptions {
56
53
  * @defaultValue `true`
57
54
  */
58
55
  readonly includePrompts?: boolean;
56
+ /**
57
+ * CLI-wide env namespace recorded on the document, so a reader can tell
58
+ * `envVar: 'TOKEN'` that reads `FOO_TOKEN` from one that reads `TOKEN`.
59
+ *
60
+ * {@link generateSchema} defaults it to the CLI schema's own `envPrefix`.
61
+ * {@link generateCommandSchema} has no CLI to read it from, so pass the
62
+ * namespace the command runs under; `--help --json` does this itself.
63
+ *
64
+ * @defaultValue the CLI's `envPrefix` for {@link generateSchema}, none otherwise
65
+ */
66
+ readonly envPrefix?: string;
59
67
  }
60
68
  /**
61
69
  * A usage example inside a definition document.
@@ -78,14 +86,17 @@ type PromptChoiceFragmentV1 = {
78
86
  * Validation callbacks are dropped. Only the serializable description of the
79
87
  * prompt survives.
80
88
  */
81
- type PromptDefinitionFragmentV1 = {
82
- readonly kind: PromptKind;
89
+ type PromptDefinitionFragmentV1 = { [K in PromptKind]: {
90
+ readonly kind: K;
83
91
  readonly message: string;
84
92
  readonly placeholder?: string;
93
+ readonly trim?: boolean;
94
+ readonly empty?: K extends 'password' ? 'accept' | 'retry' : 'skip' | 'accept' | 'retry';
95
+ readonly sensitive?: boolean;
85
96
  readonly choices?: readonly PromptChoiceFragmentV1[];
86
97
  readonly min?: number;
87
98
  readonly max?: number;
88
- };
99
+ }; }[PromptKind];
89
100
  /**
90
101
  * Stdin binding of a flag or arg fragment.
91
102
  *
@@ -140,6 +151,21 @@ type FlagStringConstraintsFragmentV1 = {
140
151
  readonly flags: string;
141
152
  };
142
153
  };
154
+ /**
155
+ * Indexed environment family of a flag or arg fragment, in place of `envVar`.
156
+ *
157
+ * `count` names the variable holding the number of entries. A `value` family
158
+ * reads one variable per entry; a `fields` family reads one variable per record
159
+ * field, in the order written. Every template carries `{index}`, which expands
160
+ * to the zero-based entry index.
161
+ */
162
+ type EnvIndexedFragmentV1 = {
163
+ readonly count: string;
164
+ readonly value: string;
165
+ } | {
166
+ readonly count: string;
167
+ readonly fields: Readonly<Record<string, string>>;
168
+ };
143
169
  /** Filesystem expectations of a flag or arg fragment. */
144
170
  type FlagPathChecksFragmentV1 = {
145
171
  readonly mustExist: boolean;
@@ -154,6 +180,8 @@ type FlagElementFragmentV1 = {
154
180
  readonly aliases?: readonly string[];
155
181
  readonly stdin?: StdinBindingFragmentV1;
156
182
  readonly envVar?: string;
183
+ readonly envIndexed?: EnvIndexedFragmentV1;
184
+ readonly envAbsolute?: true;
157
185
  readonly configPath?: string;
158
186
  readonly description?: string;
159
187
  readonly enumValues?: readonly string[];
@@ -215,6 +243,8 @@ type ArgDefinitionFragmentV1 = {
215
243
  readonly sensitive?: true;
216
244
  readonly description?: string;
217
245
  readonly envVar?: string;
246
+ readonly envIndexed?: EnvIndexedFragmentV1;
247
+ readonly envAbsolute?: true;
218
248
  readonly configPath?: string;
219
249
  readonly enumValues?: readonly string[];
220
250
  readonly elementSchema?: ArgElementFragmentV1;
@@ -265,6 +295,12 @@ type DefinitionDocumentV1 = {
265
295
  readonly name: string;
266
296
  readonly version?: string;
267
297
  readonly description?: string;
298
+ /**
299
+ * CLI-wide env namespace. Each relative `envVar`, and each count and
300
+ * template of a relative `envIndexed`, reads with this prefix prepended; a
301
+ * fragment marked `envAbsolute` reads its names as written.
302
+ */
303
+ readonly envPrefix?: string;
268
304
  readonly defaultCommand?: CommandDefinitionFragmentV1;
269
305
  readonly commands: readonly CommandDefinitionFragmentV1[];
270
306
  };
@@ -278,6 +314,11 @@ type DefinitionDocumentV1 = {
278
314
  type CommandDefinitionDocumentV1 = CommandDefinitionFragmentV1 & {
279
315
  /** Definition document format version. */
280
316
  readonly schemaVersion: 1;
317
+ /**
318
+ * CLI-wide env namespace the command runs under, read the same way as
319
+ * {@link DefinitionDocumentV1.envPrefix}.
320
+ */
321
+ readonly envPrefix?: string;
281
322
  };
282
323
  /** The current whole-CLI definition document. */
283
324
  type DefinitionDocument = DefinitionDocumentV1;
@@ -395,5 +436,4 @@ declare function generateInputSchema(schema: CLISchema | CommandSchema, options?
395
436
  * ```
396
437
  */
397
438
  declare const definitionMetaSchema: Record<string, unknown>;
398
- //#endregion
399
- export { definitionMetaSchema as C, DEFINITION_SCHEMA_URL as D, generateSchema as E, DEFINITION_SCHEMA_VERSION as O, StdinBindingFragmentV1 as S, generateInputSchema as T, JsonSchemaOptions as _, CommandDefinitionFragmentV1 as a, SourceSplitFragmentV1 as b, ExampleDefinitionFragmentV1 as c, FlagNegationFragmentV1 as d, FlagPathChecksFragmentV1 as f, InputSchemaProperty as g, InputSchemaDocument as h, CommandDefinitionDocumentV1 as i, FlagDefinitionFragmentV1 as l, InputSchemaBranch as m, ArgElementFragmentV1 as n, DefinitionDocument as o, FlagStringConstraintsFragmentV1 as p, CommandDefinitionDocument as r, DefinitionDocumentV1 as s, ArgDefinitionFragmentV1 as t, FlagElementFragmentV1 as u, PromptChoiceFragmentV1 as v, generateCommandSchema as w, SplitPolicyFragmentV1 as x, PromptDefinitionFragmentV1 as y };
439
+ export { StdinBindingFragmentV1 as C, generateSchema as D, generateInputSchema as E, DEFINITION_SCHEMA_URL as O, SplitPolicyFragmentV1 as S, generateCommandSchema as T, InputSchemaProperty as _, CommandDefinitionFragmentV1 as a, PromptDefinitionFragmentV1 as b, EnvIndexedFragmentV1 as c, FlagElementFragmentV1 as d, FlagNegationFragmentV1 as f, InputSchemaDocument as g, InputSchemaBranch as h, CommandDefinitionDocumentV1 as i, DEFINITION_SCHEMA_VERSION as k, ExampleDefinitionFragmentV1 as l, FlagStringConstraintsFragmentV1 as m, ArgElementFragmentV1 as n, DefinitionDocument as o, FlagPathChecksFragmentV1 as p, CommandDefinitionDocument as r, DefinitionDocumentV1 as s, ArgDefinitionFragmentV1 as t, FlagDefinitionFragmentV1 as u, JsonSchemaOptions as v, definitionMetaSchema as w, SourceSplitFragmentV1 as x, PromptChoiceFragmentV1 as y };
@@ -0,0 +1,129 @@
1
+ /**
2
+ * Structured error types for DreamCLI.
3
+ *
4
+ * Base {@linkcode CLIError} carries stable code, exit code, suggestion, and structured
5
+ * details. {@linkcode ParseError} and {@linkcode ValidationError} derive from it with
6
+ * category-appropriate defaults.
7
+ *
8
+ * @module dreamcli/core/errors
9
+ */
10
+ /** Codes emitted during argv parsing. */
11
+ type ParseErrorCode = 'UNKNOWN_FLAG' | 'UNKNOWN_COMMAND' | 'MISSING_VALUE' | 'INVALID_VALUE' | 'INVALID_SCHEMA' | 'DUPLICATE_FLAG' | 'UNEXPECTED_POSITIONAL';
12
+ /** Codes emitted during post-parse validation / resolution. */
13
+ type ValidationErrorCode = 'REQUIRED_FLAG' | 'REQUIRED_ARG' | 'MISSING_STDIN' | 'INVALID_ENUM' | 'TYPE_MISMATCH' | 'CONSTRAINT_VIOLATED';
14
+ /** Any framework error code (extensible via `string & {}`). */
15
+ type ErrorCode = ParseErrorCode | ValidationErrorCode | (string & {});
16
+ /** Options accepted by the `CLIError` constructor. */
17
+ interface CLIErrorOptions {
18
+ /** Stable machine-readable identifier (e.g. `"UNKNOWN_FLAG"`). */
19
+ readonly code: ErrorCode;
20
+ /**
21
+ * Process exit code.
22
+ * @defaultValue `1`
23
+ */
24
+ readonly exitCode?: number;
25
+ /** One-liner actionable hint shown to the user. */
26
+ readonly suggest?: string;
27
+ /** Arbitrary structured payload (serialised in `--json` mode). */
28
+ readonly details?: Readonly<Record<string, unknown>>;
29
+ /** Original error, if this wraps another. */
30
+ readonly cause?: unknown;
31
+ }
32
+ /**
33
+ * Base structured error for DreamCLI.
34
+ *
35
+ * Every error surfaced by the framework extends this class, ensuring a
36
+ * consistent shape for rendering (TTY pretty-print, `--json`, test assertions).
37
+ */
38
+ declare class CLIError extends Error {
39
+ /** Error class name, always `'CLIError'` for the base class. @override */
40
+ readonly name: string;
41
+ /** Stable machine-readable identifier. */
42
+ readonly code: ErrorCode;
43
+ /** Process exit code (defaults to `1`). */
44
+ readonly exitCode: number;
45
+ /** One-liner actionable hint. */
46
+ readonly suggest: string | undefined;
47
+ /** Structured payload for machine output. */
48
+ readonly details: Readonly<Record<string, unknown>> | undefined;
49
+ /** Create a structured CLI error from a human message and machine-readable options. */
50
+ constructor(message: string, options: CLIErrorOptions);
51
+ /**
52
+ * Serialise to a plain object suitable for JSON output.
53
+ *
54
+ * `details` is projected onto JSON-representable values: bigints become
55
+ * decimal digits and entries JSON cannot carry are omitted. The error
56
+ * object itself keeps the runtime values.
57
+ *
58
+ * @sealed
59
+ */
60
+ toJSON(): CLIErrorJSON;
61
+ }
62
+ /** Shape returned by {@linkcode CLIError}.toJSON(). */
63
+ interface CLIErrorJSON {
64
+ /** Error class name (e.g. `'CLIError'`, `'ParseError'`). */
65
+ readonly name: string;
66
+ /** Stable machine-readable identifier for programmatic matching. */
67
+ readonly code: ErrorCode;
68
+ /** Human-readable description of what went wrong. */
69
+ readonly message: string;
70
+ /** Process exit code associated with this error. */
71
+ readonly exitCode: number;
72
+ /** Actionable hint shown to the user, when available. */
73
+ readonly suggest?: string;
74
+ /** Structured payload for machine consumers, when available. */
75
+ readonly details?: Readonly<Record<string, unknown>>;
76
+ }
77
+ /** Options for {@linkcode ParseError}. Code is narrowed to parse-specific codes. */
78
+ interface ParseErrorOptions extends Omit<CLIErrorOptions, 'code' | 'exitCode'> {
79
+ /** Parse-category error code (e.g. `'UNKNOWN_FLAG'`, `'MISSING_VALUE'`). */
80
+ readonly code: ParseErrorCode;
81
+ /**
82
+ * Process exit code for parse failures.
83
+ * @defaultValue `2`
84
+ */
85
+ readonly exitCode?: number;
86
+ }
87
+ /**
88
+ * Error thrown when argv tokenization / parsing fails.
89
+ *
90
+ * Exit code defaults to `2` (standard for CLI usage errors).
91
+ */
92
+ declare class ParseError extends CLIError {
93
+ /** Always `'ParseError'`. @override */
94
+ readonly name: "ParseError";
95
+ /** Narrowed to parse-category codes. */
96
+ readonly code: ParseErrorCode;
97
+ /** Create a parse error with exit code defaulting to `2`. */
98
+ constructor(message: string, options: ParseErrorOptions);
99
+ }
100
+ /** Options for {@linkcode ValidationError}. Code is narrowed to validation-specific codes. */
101
+ interface ValidationErrorOptions extends Omit<CLIErrorOptions, 'code' | 'exitCode'> {
102
+ /** Validation-category error code (e.g. `'REQUIRED_FLAG'`, `'INVALID_ENUM'`). */
103
+ readonly code: ValidationErrorCode;
104
+ /**
105
+ * Process exit code for validation failures.
106
+ * @defaultValue `2`
107
+ */
108
+ readonly exitCode?: number;
109
+ }
110
+ /**
111
+ * Error thrown when resolved values fail validation constraints.
112
+ *
113
+ * Exit code defaults to `2` (standard for CLI usage errors).
114
+ */
115
+ declare class ValidationError extends CLIError {
116
+ /** Always `'ValidationError'`. @override */
117
+ readonly name: "ValidationError";
118
+ /** Narrowed to validation-category codes. */
119
+ readonly code: ValidationErrorCode;
120
+ /** Create a validation error with exit code defaulting to `2`. */
121
+ constructor(message: string, options: ValidationErrorOptions);
122
+ }
123
+ /** Narrows an unknown value to `CLIError`. */
124
+ declare function isCLIError(value: unknown): value is CLIError;
125
+ /** Narrows an unknown value to `ParseError`. */
126
+ declare function isParseError(value: unknown): value is ParseError;
127
+ /** Narrows an unknown value to `ValidationError`. */
128
+ declare function isValidationError(value: unknown): value is ValidationError;
129
+ export { ParseError as a, ValidationError as c, isCLIError as d, isParseError as f, ErrorCode as i, ValidationErrorCode as l, CLIErrorJSON as n, ParseErrorCode as o, isValidationError as p, CLIErrorOptions as r, ParseErrorOptions as s, CLIError as t, ValidationErrorOptions as u };