@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.
- package/README.md +3 -1
- package/dist/{adapter-YM5QGi3M.d.mts → adapter-DBeedKmD.d.mts} +5 -3
- package/dist/{completion-CUMeOnAz.mjs → completion-Bh-qywmB.mjs} +4 -4
- package/dist/completion.d.mts +1 -11
- package/dist/completion.mjs +1 -1
- package/dist/config-DruA8aFV.mjs +1 -0
- package/dist/config.d.mts +1 -1
- package/dist/config.mjs +1 -1
- package/dist/core-B9YNSJeA.mjs +19 -0
- package/dist/{index-Cap0MA2V.d.mts → index-AIC5Gler.d.mts} +18 -12
- package/dist/{index-BziI2aKc.d.mts → index-BIMjOsR6.d.mts} +316 -53
- package/dist/{index-3l8uj16E.d.mts → index-BidVVmln.d.mts} +51 -11
- package/dist/index-D683D09G.d.mts +129 -0
- package/dist/{index-DWsnGZlx.d.mts → index-DpslpOVV.d.mts} +160 -154
- package/dist/{index-BAj2y70U.d.mts → index-hzYPRc_O.d.mts} +65 -14
- package/dist/{index-Cp9kt2t-.d.mts → index-jq_FJRKt.d.mts} +1 -7
- package/dist/index.d.mts +18 -11
- package/dist/index.mjs +1 -1
- package/dist/json-schema-DF5fXdKQ.mjs +59 -0
- package/dist/json-schema.d.mts +2 -2
- package/dist/json-schema.mjs +1 -1
- package/dist/package-json-fYhxDdWD.mjs +3 -0
- package/dist/prompt.d.mts +32 -5
- package/dist/prompt.mjs +1 -1
- package/dist/runtime.d.mts +2 -2
- package/dist/runtime.mjs +1 -1
- package/dist/session-Crtzt7LY.mjs +1 -0
- package/dist/terminal-DRsRn4sc.mjs +7 -0
- package/dist/test-prompter-BLNGCOA_.mjs +1 -0
- package/dist/testkit.d.mts +5 -7
- package/dist/testkit.mjs +1 -1
- package/dist/version.d.mts +1 -3
- package/dist/version.mjs +1 -1
- package/dreamcli.schema.json +155 -3
- package/package.json +24 -24
- package/skills/cli-creation/SKILL.md +1 -1
- package/skills/cli-creation/scripts/scaffold_cli.py +12 -4
- package/dist/config-CrlScpYX.mjs +0 -1
- package/dist/core-DvXUolc_.mjs +0 -17
- package/dist/json-schema-DRlrz_IV.mjs +0 -52
- package/dist/package-json-BgE9YjjQ.mjs +0 -3
- package/dist/terminal-C8KTXjv5.mjs +0 -6
- package/dist/test-prompter-v__jT2yG.mjs +0 -1
|
@@ -1,7 +1,6 @@
|
|
|
1
|
-
import {
|
|
2
|
-
import "./index-
|
|
3
|
-
import { o as CLISchema } from "./index-
|
|
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:
|
|
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
|
-
|
|
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 };
|