@kjanat/dreamcli 1.0.0 → 2.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/CHANGELOG.md +45 -6
- package/LICENSE +1 -1
- package/README.md +296 -164
- package/dist/core/cli/dispatch.d.mts +85 -0
- package/dist/core/cli/dispatch.mjs +1 -0
- package/dist/core/cli/index.d.mts +418 -0
- package/dist/core/cli/index.mjs +1 -0
- package/dist/core/cli/planner.d.mts +143 -0
- package/dist/core/cli/planner.mjs +1 -0
- package/dist/core/cli/plugin.d.mts +94 -0
- package/dist/core/cli/plugin.mjs +1 -0
- package/dist/core/cli/propagate.d.mts +39 -0
- package/dist/core/cli/propagate.mjs +1 -0
- package/dist/core/cli/root-help.d.mts +28 -0
- package/dist/core/cli/root-help.mjs +7 -0
- package/dist/core/cli/root-surface.d.mts +42 -0
- package/dist/core/cli/root-surface.mjs +1 -0
- package/dist/core/cli/runtime-preflight.d.mts +149 -0
- package/dist/core/cli/runtime-preflight.mjs +1 -0
- package/dist/core/completion/index.d.mts +46 -0
- package/dist/core/completion/index.mjs +1 -0
- package/dist/core/completion/shells/bash.d.mts +24 -0
- package/dist/core/completion/shells/bash.mjs +3 -0
- package/dist/core/completion/shells/fish.d.mts +20 -0
- package/dist/core/completion/shells/fish.mjs +2 -0
- package/dist/core/completion/shells/powershell.d.mts +14 -0
- package/dist/core/completion/shells/powershell.mjs +2 -0
- package/dist/core/completion/shells/shared.d.mts +139 -0
- package/dist/core/completion/shells/shared.mjs +1 -0
- package/dist/core/completion/shells/zsh.d.mts +24 -0
- package/dist/core/completion/shells/zsh.mjs +2 -0
- package/dist/core/config/index.d.mts +161 -0
- package/dist/core/config/index.mjs +1 -0
- package/dist/core/config/package-json.d.mts +68 -0
- package/dist/core/config/package-json.mjs +1 -0
- package/dist/core/errors/index.d.mts +126 -0
- package/dist/core/errors/index.mjs +1 -0
- package/dist/core/execution/index.d.mts +49 -0
- package/dist/core/execution/index.mjs +1 -0
- package/dist/core/help/index.d.mts +49 -0
- package/dist/core/help/index.mjs +8 -0
- package/dist/core/json-schema/index.d.mts +109 -0
- package/dist/core/json-schema/index.mjs +55 -0
- package/dist/core/json-schema/meta-descriptions.generated.d.mts +185 -0
- package/dist/core/json-schema/meta-descriptions.generated.mjs +28 -0
- package/dist/core/output/activity.d.mts +194 -0
- package/dist/core/output/activity.mjs +1 -0
- package/dist/core/output/contracts.d.mts +88 -0
- package/dist/core/output/contracts.mjs +1 -0
- package/dist/core/output/display-value.d.mts +19 -0
- package/dist/core/output/display-value.mjs +1 -0
- package/dist/core/output/index.d.mts +280 -0
- package/dist/core/output/index.mjs +2 -0
- package/dist/core/output/renderers.d.mts +46 -0
- package/dist/core/output/renderers.mjs +1 -0
- package/dist/core/output/writer.d.mts +40 -0
- package/dist/core/output/writer.mjs +1 -0
- package/dist/core/parse/index.d.mts +79 -0
- package/dist/core/parse/index.mjs +1 -0
- package/dist/core/prompt/index.d.mts +205 -0
- package/dist/core/prompt/index.mjs +6 -0
- package/dist/core/resolve/args.d.mts +8 -0
- package/dist/core/resolve/args.mjs +1 -0
- package/dist/core/resolve/coerce.d.mts +22 -0
- package/dist/core/resolve/coerce.mjs +1 -0
- package/dist/core/resolve/config.d.mts +10 -0
- package/dist/core/resolve/config.mjs +1 -0
- package/dist/core/resolve/contracts.d.mts +112 -0
- package/dist/core/resolve/errors.d.mts +11 -0
- package/dist/core/resolve/errors.mjs +2 -0
- package/dist/core/resolve/flags.d.mts +10 -0
- package/dist/core/resolve/flags.mjs +1 -0
- package/dist/core/resolve/index.d.mts +42 -0
- package/dist/core/resolve/index.mjs +1 -0
- package/dist/core/resolve/property.d.mts +47 -0
- package/dist/core/resolve/property.mjs +1 -0
- package/dist/core/schema/activity.d.mts +169 -0
- package/dist/core/schema/arg.d.mts +559 -0
- package/dist/core/schema/arg.mjs +1 -0
- package/dist/core/schema/command.d.mts +960 -0
- package/dist/core/schema/command.mjs +1 -0
- package/dist/core/schema/flag.d.mts +491 -0
- package/dist/core/schema/flag.mjs +1 -0
- package/dist/core/schema/index.d.mts +8 -0
- package/dist/core/schema/middleware.d.mts +122 -0
- package/dist/core/schema/middleware.mjs +1 -0
- package/dist/core/schema/prompt.d.mts +117 -0
- package/dist/core/schema/run.d.mts +171 -0
- package/dist/core/schema-dsl/runtime.d.mts +144 -0
- package/dist/core/schema-dsl/runtime.mjs +2 -0
- package/dist/core/schema-dsl/to-json-schema.d.mts +30 -0
- package/dist/core/schema-dsl/to-json-schema.mjs +1 -0
- package/dist/core/testkit/index.d.mts +54 -0
- package/dist/core/testkit/index.mjs +1 -0
- package/dist/index.d.mts +28 -920
- package/dist/index.mjs +1 -10
- package/dist/runtime/adapter.d.mts +212 -0
- package/dist/{adapter-B37d9oia.mjs → runtime/adapter.mjs} +1 -1
- package/dist/runtime/auto.d.mts +26 -0
- package/dist/runtime/auto.mjs +1 -0
- package/dist/runtime/bun.d.mts +28 -0
- package/dist/runtime/bun.mjs +1 -0
- package/dist/runtime/deno.d.mts +76 -0
- package/dist/runtime/deno.mjs +2 -0
- package/dist/runtime/detect.d.mts +86 -0
- package/dist/runtime/detect.mjs +1 -0
- package/dist/runtime/index.d.mts +7 -0
- package/dist/runtime/node.d.mts +65 -0
- package/dist/runtime/node.mjs +2 -0
- package/dist/runtime/paths.d.mts +31 -0
- package/dist/runtime/paths.mjs +1 -0
- package/dist/runtime/support.d.mts +42 -0
- package/dist/runtime/support.mjs +1 -0
- package/dist/runtime.d.mts +6 -252
- package/dist/runtime.mjs +1 -1
- package/dist/testkit.d.mts +5 -24
- package/dist/testkit.mjs +1 -1
- package/dist/version.d.mts +16 -0
- package/dist/version.mjs +1 -0
- package/dreamcli.schema.json +338 -0
- package/examples/basic.ts +2 -2
- package/examples/gh/package.json +7 -11
- package/examples/gh/src/commands/auth.ts +2 -2
- package/examples/gh/src/commands/issue.ts +4 -4
- package/examples/gh/src/commands/pr.ts +4 -4
- package/examples/gh/src/docs.ts +11 -0
- package/examples/gh/src/lib/auth.ts +1 -1
- package/examples/gh/src/main.test.ts +6 -5
- package/examples/gh/src/main.ts +8 -6
- package/examples/interactive.ts +3 -3
- package/examples/json-mode.ts +4 -6
- package/examples/middleware.ts +3 -3
- package/examples/multi-command.ts +3 -3
- package/examples/spinner-progress.ts +5 -5
- package/examples/testing.ts +8 -6
- package/package.json +70 -44
- package/src/core/cli/dispatch.ts +4 -0
- package/src/core/cli/index.ts +185 -632
- package/src/core/cli/planner.ts +413 -0
- package/src/core/cli/plugin.ts +7 -1
- package/src/core/cli/propagate.ts +1 -1
- package/src/core/cli/runtime-preflight.ts +409 -0
- package/src/core/completion/index.ts +15 -9
- package/src/core/completion/shells/bash.ts +6 -3
- package/src/core/completion/shells/fish.ts +245 -10
- package/src/core/completion/shells/powershell.ts +390 -9
- package/src/core/completion/shells/shared.ts +4 -4
- package/src/core/completion/shells/zsh.ts +12 -7
- package/src/core/config/index.ts +7 -4
- package/src/core/config/package-json.ts +6 -2
- package/src/core/errors/index.ts +23 -8
- package/src/core/execution/index.ts +270 -0
- package/src/core/help/index.ts +13 -15
- package/src/core/json-schema/index.ts +193 -7
- package/src/core/json-schema/meta-descriptions.generated.ts +202 -0
- package/src/core/output/contracts.ts +194 -0
- package/src/core/output/index.ts +47 -82
- package/src/core/output/renderers.ts +125 -0
- package/src/core/parse/index.ts +39 -21
- package/src/core/prompt/index.ts +44 -27
- package/src/core/resolve/args.ts +144 -0
- package/src/core/resolve/coerce.ts +432 -0
- package/src/core/resolve/config.ts +26 -0
- package/src/core/resolve/contracts.ts +135 -0
- package/src/core/resolve/errors.ts +227 -0
- package/src/core/resolve/flags.ts +205 -0
- package/src/core/resolve/index.ts +41 -1264
- package/src/core/resolve/property.ts +99 -0
- package/src/core/schema/activity.ts +3 -0
- package/src/core/schema/arg.ts +26 -14
- package/src/core/schema/command.ts +265 -38
- package/src/core/schema/flag.ts +120 -15
- package/src/core/schema/index.ts +11 -2
- package/src/core/schema/middleware.ts +6 -6
- package/src/core/schema/prompt.ts +9 -1
- package/src/core/schema/run.ts +25 -17
- package/src/core/schema-dsl/index.ts +109 -0
- package/src/core/schema-dsl/parse.ts +262 -0
- package/src/core/schema-dsl/runtime.ts +609 -0
- package/src/core/schema-dsl/to-json-schema.ts +102 -0
- package/src/core/testkit/index.ts +55 -297
- package/src/index.ts +10 -4
- package/src/runtime/adapter.ts +13 -10
- package/src/runtime/auto.ts +3 -3
- package/src/runtime/bun.ts +4 -4
- package/src/runtime/deno.ts +43 -29
- package/src/runtime/detect.ts +4 -1
- package/src/runtime/index.ts +1 -1
- package/src/runtime/node.ts +43 -21
- package/src/runtime/paths.ts +9 -3
- package/src/runtime/support.ts +20 -4
- package/src/runtime.ts +1 -1
- package/src/testkit.ts +10 -8
- package/dist/adapter-CCSh5juX.cjs +0 -1
- package/dist/adapter-DIwO-q7K.d.mts +0 -3447
- package/dist/adapter-DQnxxLiE.d.cts +0 -3447
- package/dist/auto-5cjZaF9V.mjs +0 -3
- package/dist/auto-B0eSgoDw.cjs +0 -3
- package/dist/index.cjs +0 -10
- package/dist/index.d.cts +0 -920
- package/dist/runtime.cjs +0 -1
- package/dist/runtime.d.cts +0 -253
- package/dist/testkit-CEDYPvhF.mjs +0 -14
- package/dist/testkit-ClIKijxC.cjs +0 -14
- package/dist/testkit.cjs +0 -1
- package/dist/testkit.d.cts +0 -25
- package/examples/gh/tsconfig.json +0 -37
- package/examples/tsconfig.json +0 -17
- package/src/core/cli/AGENTS.md +0 -72
- package/src/core/completion/AGENTS.md +0 -72
- package/src/core/completion/completion-test-helpers.ts +0 -48
- package/src/core/output/AGENTS.md +0 -69
- package/src/core/resolve/AGENTS.md +0 -69
- package/src/core/schema/AGENTS.md +0 -61
- package/src/core/testkit/AGENTS.md +0 -55
- package/src/runtime/AGENTS.md +0 -74
- package/src/runtime/test-helpers.ts +0 -40
|
@@ -0,0 +1,88 @@
|
|
|
1
|
+
import { Fallback, TableOptions } from "../schema/activity.mjs";
|
|
2
|
+
|
|
3
|
+
//#region src/core/output/contracts.d.ts
|
|
4
|
+
/** Ordered output verbosity levels owned by the output policy layer. */
|
|
5
|
+
declare const OUTPUT_VERBOSITY_LEVELS: readonly ['normal', 'quiet'];
|
|
6
|
+
/** Stable output text streams. */
|
|
7
|
+
declare const OUTPUT_STREAMS: readonly ['stdout', 'stderr'];
|
|
8
|
+
/** Stable activity rendering modes. */
|
|
9
|
+
declare const ACTIVITY_RENDER_MODES: readonly ['noop', 'static', 'tty', 'capture'];
|
|
10
|
+
/** Stable activity cleanup actions. */
|
|
11
|
+
declare const ACTIVITY_CLEANUP_KINDS: readonly ['none', 'stop', 'done'];
|
|
12
|
+
/** Stable text verbosity labels. */
|
|
13
|
+
type Verbosity = (typeof OUTPUT_VERBOSITY_LEVELS)[number];
|
|
14
|
+
/** Stable output stream labels. */
|
|
15
|
+
type OutputStream = (typeof OUTPUT_STREAMS)[number];
|
|
16
|
+
/** Stable activity-render labels. */
|
|
17
|
+
type ActivityRenderMode = (typeof ACTIVITY_RENDER_MODES)[number];
|
|
18
|
+
/** Stable cleanup labels for tracked activity handles. */
|
|
19
|
+
type ActivityCleanupKind = (typeof ACTIVITY_CLEANUP_KINDS)[number];
|
|
20
|
+
/** Semantic output facts chosen before concrete rendering begins. */
|
|
21
|
+
interface OutputPolicy {
|
|
22
|
+
/** Whether `--json` was requested, routing structured data to stdout. */
|
|
23
|
+
readonly jsonMode: boolean;
|
|
24
|
+
/** Whether the output stream is connected to an interactive terminal. */
|
|
25
|
+
readonly isTTY: boolean;
|
|
26
|
+
/** Active verbosity level controlling which message categories emit. */
|
|
27
|
+
readonly verbosity: Verbosity;
|
|
28
|
+
}
|
|
29
|
+
/** Inputs for building an {@linkcode OutputPolicy} snapshot. */
|
|
30
|
+
interface ResolveOutputPolicyOptions {
|
|
31
|
+
/** Whether `--json` was requested on the command line. */
|
|
32
|
+
readonly jsonMode: boolean;
|
|
33
|
+
/** Whether the output stream is connected to an interactive terminal. */
|
|
34
|
+
readonly isTTY: boolean;
|
|
35
|
+
/** Verbosity level to apply for this channel instance. */
|
|
36
|
+
readonly verbosity: Verbosity;
|
|
37
|
+
}
|
|
38
|
+
/** Concrete activity policy chosen for spinner/progress creation. */
|
|
39
|
+
interface ActivityPolicy {
|
|
40
|
+
/** Render strategy for the activity indicator (never `'capture'` here). */
|
|
41
|
+
readonly mode: Exclude<ActivityRenderMode, 'capture'>;
|
|
42
|
+
/** Activity output always targets stderr to avoid polluting structured stdout. */
|
|
43
|
+
readonly stream: 'stderr';
|
|
44
|
+
/** Cleanup action the output layer must run when the handle is discarded. */
|
|
45
|
+
readonly cleanup: ActivityCleanupKind;
|
|
46
|
+
}
|
|
47
|
+
/** Stable output-policy facts the re-foundation workstream is freezing. */
|
|
48
|
+
interface OutputContract {
|
|
49
|
+
/** In JSON mode, stdout carries only machine-readable structured output. */
|
|
50
|
+
readonly jsonReservesStdoutForStructuredData: true;
|
|
51
|
+
/** Quiet verbosity suppresses `info()` messages entirely. */
|
|
52
|
+
readonly quietSuppressesInfo: true;
|
|
53
|
+
/** Spinner/progress writes go to stderr so stdout stays parseable. */
|
|
54
|
+
readonly activityUsesStderrOutsideCapture: true;
|
|
55
|
+
/** Animated TTY spinners require both a real terminal and non-JSON mode. */
|
|
56
|
+
readonly ttyActivityRequiresTTYAndNonJson: true;
|
|
57
|
+
/** Spinner handles clean up via `stop()` to clear the animation line. */
|
|
58
|
+
readonly spinnerCleanupUsesStop: true;
|
|
59
|
+
/** Progress handles clean up via `done()` to render the final state. */
|
|
60
|
+
readonly progressCleanupUsesDone: true;
|
|
61
|
+
}
|
|
62
|
+
/** Runtime-accessible copy of the frozen output-policy invariants. */
|
|
63
|
+
declare const outputContract: {
|
|
64
|
+
jsonReservesStdoutForStructuredData: true;
|
|
65
|
+
quietSuppressesInfo: true;
|
|
66
|
+
activityUsesStderrOutsideCapture: true;
|
|
67
|
+
ttyActivityRequiresTTYAndNonJson: true;
|
|
68
|
+
spinnerCleanupUsesStop: true;
|
|
69
|
+
progressCleanupUsesDone: true;
|
|
70
|
+
};
|
|
71
|
+
/** Build the stable output-policy snapshot for one channel instance. */
|
|
72
|
+
declare function resolveOutputPolicy(options: ResolveOutputPolicyOptions): OutputPolicy;
|
|
73
|
+
/** Resolve the default text stream for non-JSON structured output. */
|
|
74
|
+
declare function resolveTextStream(policy: OutputPolicy): OutputStream;
|
|
75
|
+
/** Whether `info()` messages should be emitted under the current policy. */
|
|
76
|
+
declare function shouldEmitInfo(policy: OutputPolicy): boolean;
|
|
77
|
+
/** Resolve the concrete table format under the current policy. */
|
|
78
|
+
declare function resolveTableFormat(policy: OutputPolicy, options?: TableOptions): 'text' | 'json';
|
|
79
|
+
/** Resolve the text-table stream after table-format selection. */
|
|
80
|
+
declare function resolveTableTextStream(policy: OutputPolicy, options?: TableOptions): OutputStream;
|
|
81
|
+
/** Resolve the non-capture activity mode shared by spinner and progress. */
|
|
82
|
+
declare function resolveActivityRenderMode(policy: OutputPolicy, fallback: Fallback): ActivityPolicy['mode'];
|
|
83
|
+
/** Resolve spinner activity policy including cleanup ownership. */
|
|
84
|
+
declare function resolveSpinnerPolicy(policy: OutputPolicy, fallback: Fallback): ActivityPolicy;
|
|
85
|
+
/** Resolve progress activity policy including cleanup ownership. */
|
|
86
|
+
declare function resolveProgressPolicy(policy: OutputPolicy, fallback: Fallback): ActivityPolicy;
|
|
87
|
+
//#endregion
|
|
88
|
+
export { ACTIVITY_CLEANUP_KINDS, ACTIVITY_RENDER_MODES, type ActivityCleanupKind, type ActivityPolicy, type ActivityRenderMode, OUTPUT_STREAMS, OUTPUT_VERBOSITY_LEVELS, type OutputContract, type OutputPolicy, type OutputStream, type ResolveOutputPolicyOptions, type Verbosity, outputContract, resolveActivityRenderMode, resolveOutputPolicy, resolveProgressPolicy, resolveSpinnerPolicy, resolveTableFormat, resolveTableTextStream, resolveTextStream, shouldEmitInfo };
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
function e(e){return{jsonMode:e.jsonMode,isTTY:e.isTTY,verbosity:e.verbosity}}function t(e){return e.jsonMode?`stderr`:`stdout`}function n(e){return e.verbosity!==`quiet`}function r(e,t){switch(t?.format){case`json`:return`json`;case`text`:return`text`;case`auto`:case void 0:return e.jsonMode?`json`:`text`}}function i(e,n){return n?.format===`text`&&`stream`in n&&n.stream!==void 0?n.stream:t(e)}function a(e,t){return e.jsonMode?`noop`:e.isTTY?`tty`:t===`static`?`static`:`noop`}function o(e,t){let n=a(e,t);return{mode:n,stream:`stderr`,cleanup:n===`noop`?`none`:`stop`}}function s(e,t){let n=a(e,t);return{mode:n,stream:`stderr`,cleanup:n===`noop`?`none`:`done`}}export{e as resolveOutputPolicy,s as resolveProgressPolicy,o as resolveSpinnerPolicy,r as resolveTableFormat,i as resolveTableTextStream,t as resolveTextStream,n as shouldEmitInfo};
|
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
//#region src/core/output/display-value.d.ts
|
|
2
|
+
/**
|
|
3
|
+
* Shared runtime-value formatting for human-readable output.
|
|
4
|
+
*
|
|
5
|
+
* Used by help text and table rendering so default values and structured cells
|
|
6
|
+
* stringify consistently across the CLI surface.
|
|
7
|
+
*
|
|
8
|
+
* @module dreamcli/core/output/display-value
|
|
9
|
+
* @internal
|
|
10
|
+
*/
|
|
11
|
+
/**
|
|
12
|
+
* Format an unknown runtime value for human-readable output.
|
|
13
|
+
*
|
|
14
|
+
* @param value - The value to format (any type).
|
|
15
|
+
* @returns A string representation suitable for table cells and help text.
|
|
16
|
+
*/
|
|
17
|
+
declare function formatDisplayValue(value: unknown): string;
|
|
18
|
+
//#endregion
|
|
19
|
+
export { formatDisplayValue };
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
function e(e){if(e==null)return``;if(typeof e==`string`||typeof e==`number`||typeof e==`boolean`||typeof e==`bigint`||typeof e==`symbol`)return String(e);if(e instanceof Date)return Number.isNaN(e.getTime())?`Invalid Date`:e.toISOString();if(typeof e==`function`)return e.name.length>0?`[Function: ${e.name}]`:`[Function]`;try{return JSON.stringify(e)??`[unserializable]`}catch{return`[unserializable]`}}export{e as formatDisplayValue};
|
|
@@ -0,0 +1,280 @@
|
|
|
1
|
+
import { ActivityEvent, ProgressHandle, ProgressOptions, SpinnerHandle, SpinnerOptions, TableColumn, TableOptions } from "../schema/activity.mjs";
|
|
2
|
+
import { WriteFn, writeLine } from "./writer.mjs";
|
|
3
|
+
import { CaptureProgressHandle, CaptureSpinnerHandle, StaticProgressHandle, StaticSpinnerHandle, TTYProgressHandle, TTYSpinnerHandle, noopProgressHandle, noopSpinnerHandle } from "./activity.mjs";
|
|
4
|
+
import { OutputPolicy, Verbosity } from "./contracts.mjs";
|
|
5
|
+
import { Out } from "../schema/command.mjs";
|
|
6
|
+
|
|
7
|
+
//#region src/core/output/index.d.ts
|
|
8
|
+
/**
|
|
9
|
+
* Configuration for creating an output channel.
|
|
10
|
+
*
|
|
11
|
+
* Every field is optional — sensible defaults are applied when omitted.
|
|
12
|
+
*/
|
|
13
|
+
interface OutputOptions {
|
|
14
|
+
/**
|
|
15
|
+
* Writer for stdout-bound messages (`log`, `info`, `json`).
|
|
16
|
+
* Defaults to `process.stdout.write` when running in Node/Bun.
|
|
17
|
+
*/
|
|
18
|
+
readonly stdout?: WriteFn;
|
|
19
|
+
/**
|
|
20
|
+
* Writer for stderr-bound messages (`warn`, `error`).
|
|
21
|
+
* In JSON mode, `log` and `info` are also redirected here so that
|
|
22
|
+
* stdout contains only structured JSON output.
|
|
23
|
+
* Defaults to `process.stderr.write` when running in Node/Bun.
|
|
24
|
+
*/
|
|
25
|
+
readonly stderr?: WriteFn;
|
|
26
|
+
/**
|
|
27
|
+
* Whether stdout is connected to a TTY.
|
|
28
|
+
* When `false`, output may omit ANSI codes and decorations.
|
|
29
|
+
* Defaults to `false` (safe default — non-TTY until proven otherwise).
|
|
30
|
+
*/
|
|
31
|
+
readonly isTTY?: boolean;
|
|
32
|
+
/**
|
|
33
|
+
* Verbosity level.
|
|
34
|
+
* - `'normal'` (default) — emit all messages
|
|
35
|
+
* - `'quiet'` — suppress `info` messages
|
|
36
|
+
*/
|
|
37
|
+
readonly verbosity?: Verbosity;
|
|
38
|
+
/**
|
|
39
|
+
* Enable JSON output mode.
|
|
40
|
+
*
|
|
41
|
+
* When `true`, `log` and `info` messages are redirected to stderr
|
|
42
|
+
* so that stdout is reserved exclusively for structured `json()` output.
|
|
43
|
+
* `warn` and `error` continue to write to stderr as normal.
|
|
44
|
+
*
|
|
45
|
+
* @defaultValue `false`
|
|
46
|
+
*/
|
|
47
|
+
readonly jsonMode?: boolean;
|
|
48
|
+
}
|
|
49
|
+
/** Fully resolved output options with no optional fields. */
|
|
50
|
+
interface ResolvedOutputOptions {
|
|
51
|
+
readonly stdout: WriteFn;
|
|
52
|
+
readonly stderr: WriteFn;
|
|
53
|
+
readonly isTTY: boolean;
|
|
54
|
+
readonly verbosity: Verbosity;
|
|
55
|
+
readonly jsonMode: boolean;
|
|
56
|
+
}
|
|
57
|
+
/**
|
|
58
|
+
* Concrete implementation of the {@linkcode Out} interface.
|
|
59
|
+
*
|
|
60
|
+
* Routes messages to the appropriate writer (stdout vs stderr) and
|
|
61
|
+
* respects the configured verbosity level.
|
|
62
|
+
*
|
|
63
|
+
* Handlers interact with this via the {@linkcode Out} interface — they never see
|
|
64
|
+
* {@linkcode OutputChannel} directly, which keeps the coupling minimal.
|
|
65
|
+
* Prefer {@link createOutput} unless you are extending the output layer.
|
|
66
|
+
*
|
|
67
|
+
* @internal
|
|
68
|
+
*/
|
|
69
|
+
declare class OutputChannel implements Out {
|
|
70
|
+
/** @internal Resolved configuration. */
|
|
71
|
+
readonly options: ResolvedOutputOptions;
|
|
72
|
+
/** Semantic output policy snapshot shared by routing helpers. */
|
|
73
|
+
readonly policy: OutputPolicy;
|
|
74
|
+
/** Whether JSON output mode is active. */
|
|
75
|
+
readonly jsonMode: boolean;
|
|
76
|
+
/**
|
|
77
|
+
* Whether stdout is connected to a TTY.
|
|
78
|
+
*
|
|
79
|
+
* When `jsonMode` is active, this reflects the underlying TTY status
|
|
80
|
+
* but decorative output should still be suppressed (jsonMode takes
|
|
81
|
+
* precedence).
|
|
82
|
+
*/
|
|
83
|
+
readonly isTTY: boolean;
|
|
84
|
+
constructor(options: ResolvedOutputOptions);
|
|
85
|
+
/**
|
|
86
|
+
* Write to stdout (normal output). Always emitted.
|
|
87
|
+
*
|
|
88
|
+
* In JSON mode, redirected to stderr so stdout is reserved for
|
|
89
|
+
* structured `json()` output only.
|
|
90
|
+
*/
|
|
91
|
+
log(message: string): void;
|
|
92
|
+
/**
|
|
93
|
+
* Informational message to stdout.
|
|
94
|
+
* Suppressed when verbosity is `'quiet'`.
|
|
95
|
+
*
|
|
96
|
+
* In JSON mode, redirected to stderr.
|
|
97
|
+
*/
|
|
98
|
+
info(message: string): void;
|
|
99
|
+
/** Warning to stderr. Always emitted. */
|
|
100
|
+
warn(message: string): void;
|
|
101
|
+
/** Error to stderr. Always emitted. */
|
|
102
|
+
error(message: string): void;
|
|
103
|
+
/**
|
|
104
|
+
* Emit a structured JSON value to stdout.
|
|
105
|
+
*
|
|
106
|
+
* Serialises `value` with `JSON.stringify` and writes to stdout
|
|
107
|
+
* regardless of JSON mode — `json()` always targets stdout.
|
|
108
|
+
*/
|
|
109
|
+
json(value: unknown): void;
|
|
110
|
+
/**
|
|
111
|
+
* Render tabular data.
|
|
112
|
+
*
|
|
113
|
+
* Default behavior matches the current output mode:
|
|
114
|
+
* - normal mode → text table to stdout
|
|
115
|
+
* - jsonMode → JSON array to stdout
|
|
116
|
+
*
|
|
117
|
+
* Per-call options can force text/json rendering and route text tables to
|
|
118
|
+
* stdout or stderr.
|
|
119
|
+
*/
|
|
120
|
+
table<T extends Record<string, unknown>>(rows: readonly T[], options: TableOptions): void;
|
|
121
|
+
table<T extends Record<string, unknown>>(rows: readonly T[], columns?: readonly TableColumn<T>[], options?: TableOptions): void;
|
|
122
|
+
/**
|
|
123
|
+
* Cleanup callback for the currently active spinner/progress handle.
|
|
124
|
+
*
|
|
125
|
+
* Set to `undefined` when no handle is active. The callback calls the
|
|
126
|
+
* appropriate terminal method (`.stop()` for spinners, `.done()` for
|
|
127
|
+
* progress) on the previous handle.
|
|
128
|
+
*
|
|
129
|
+
* @internal
|
|
130
|
+
*/
|
|
131
|
+
private activeCleanup;
|
|
132
|
+
/**
|
|
133
|
+
* Stop the currently active spinner/progress handle (if any).
|
|
134
|
+
*
|
|
135
|
+
* Called internally before creating a new handle to prevent overlap,
|
|
136
|
+
* and externally after handler execution to clean up leaked timers.
|
|
137
|
+
* Idempotent (safe to call when no handle is active).
|
|
138
|
+
*/
|
|
139
|
+
stopActive(): void;
|
|
140
|
+
/**
|
|
141
|
+
* Create a spinner handle.
|
|
142
|
+
*
|
|
143
|
+
* Mode dispatch:
|
|
144
|
+
* - `jsonMode` → noop (structured output only, spinners suppressed)
|
|
145
|
+
* - `isTTY` → animated TTY spinner (braille frames, ANSI overwrite)
|
|
146
|
+
* - `!isTTY && fallback: 'static'` → plain text at lifecycle boundaries
|
|
147
|
+
* - `!isTTY && fallback: 'silent'` (default) → noop
|
|
148
|
+
*
|
|
149
|
+
* All activity output (transient frames, terminal messages) routes to
|
|
150
|
+
* stderr so stdout remains clean for structured data and piping.
|
|
151
|
+
*
|
|
152
|
+
* If another spinner or progress handle is active, it is implicitly
|
|
153
|
+
* stopped before the new one starts.
|
|
154
|
+
*
|
|
155
|
+
* @virtual
|
|
156
|
+
*/
|
|
157
|
+
spinner(text: string, options?: SpinnerOptions): SpinnerHandle;
|
|
158
|
+
/**
|
|
159
|
+
* Create a progress handle.
|
|
160
|
+
*
|
|
161
|
+
* Mode dispatch:
|
|
162
|
+
* - `jsonMode` → noop (structured output only, progress suppressed)
|
|
163
|
+
* - `isTTY` → animated TTY progress bar (determinate or indeterminate)
|
|
164
|
+
* - `!isTTY && fallback: 'static'` → plain text at lifecycle boundaries
|
|
165
|
+
* - `!isTTY && fallback: 'silent'` (default) → noop
|
|
166
|
+
*
|
|
167
|
+
* All activity output (transient frames, terminal messages) routes to
|
|
168
|
+
* stderr so stdout remains clean for structured data and piping.
|
|
169
|
+
*
|
|
170
|
+
* If another spinner or progress handle is active, it is implicitly
|
|
171
|
+
* stopped before the new one starts.
|
|
172
|
+
*
|
|
173
|
+
* @virtual
|
|
174
|
+
*/
|
|
175
|
+
progress(opts: ProgressOptions): ProgressHandle;
|
|
176
|
+
}
|
|
177
|
+
/**
|
|
178
|
+
* Output channel variant that returns capture handles for spinner/progress.
|
|
179
|
+
*
|
|
180
|
+
* Extends {@linkcode OutputChannel} to override `spinner()` and `progress()`, routing
|
|
181
|
+
* activity events into a shared {@linkcode ActivityEvent | ActivityEvent[]} for testkit assertion.
|
|
182
|
+
* Text output (log/info/warn/error) is handled by the parent class.
|
|
183
|
+
*
|
|
184
|
+
* @internal
|
|
185
|
+
*/
|
|
186
|
+
declare class CaptureOutputChannel extends OutputChannel {
|
|
187
|
+
private readonly activity;
|
|
188
|
+
constructor(options: ResolvedOutputOptions, activity: ActivityEvent[]);
|
|
189
|
+
/**
|
|
190
|
+
* Return a {@link CaptureSpinnerHandle} that records events into the activity log.
|
|
191
|
+
* @override
|
|
192
|
+
*/
|
|
193
|
+
spinner(text: string, _options?: SpinnerOptions): SpinnerHandle;
|
|
194
|
+
/**
|
|
195
|
+
* Return a {@link CaptureProgressHandle} that records events into the activity log.
|
|
196
|
+
* @override
|
|
197
|
+
*/
|
|
198
|
+
progress(opts: ProgressOptions): ProgressHandle;
|
|
199
|
+
}
|
|
200
|
+
/**
|
|
201
|
+
* Create an output channel.
|
|
202
|
+
*
|
|
203
|
+
* Low-level factory: action handlers already receive `out` automatically from
|
|
204
|
+
* `cli()`, `.execute()`, and `runCommand()`. Call `createOutput()` when you
|
|
205
|
+
* are embedding DreamCLI primitives into a custom runtime or need a standalone
|
|
206
|
+
* output implementation outside the normal command pipeline.
|
|
207
|
+
*
|
|
208
|
+
* @param options - Optional configuration. When omitted, output is
|
|
209
|
+
* discarded (useful for silent test runs). Pass `stdout`/`stderr`
|
|
210
|
+
* writers to direct output somewhere useful.
|
|
211
|
+
*
|
|
212
|
+
* @returns An {@link Out} instance backed by an {@link OutputChannel}.
|
|
213
|
+
*
|
|
214
|
+
* @example
|
|
215
|
+
* ```ts
|
|
216
|
+
* // Production (wired by the runtime adapter)
|
|
217
|
+
* const out = createOutput({
|
|
218
|
+
* stdout: (s) => process.stdout.write(s),
|
|
219
|
+
* stderr: (s) => process.stderr.write(s),
|
|
220
|
+
* isTTY: process.stdout.isTTY === true,
|
|
221
|
+
* });
|
|
222
|
+
*
|
|
223
|
+
* // Test (capture output)
|
|
224
|
+
* const lines: string[] = [];
|
|
225
|
+
* const out = createOutput({
|
|
226
|
+
* stdout: (s) => lines.push(s),
|
|
227
|
+
* stderr: (s) => lines.push(s),
|
|
228
|
+
* });
|
|
229
|
+
* ```
|
|
230
|
+
*/
|
|
231
|
+
declare function createOutput(options?: OutputOptions): Out;
|
|
232
|
+
/** Captured output from a `createCaptureOutput` instance. */
|
|
233
|
+
interface CapturedOutput {
|
|
234
|
+
/**
|
|
235
|
+
* Lines written to stdout.
|
|
236
|
+
*
|
|
237
|
+
* In normal mode: `log`, `info`, and `json` output.
|
|
238
|
+
* In JSON mode: only `json` output (log/info redirected to stderr).
|
|
239
|
+
*/
|
|
240
|
+
readonly stdout: string[];
|
|
241
|
+
/**
|
|
242
|
+
* Lines written to stderr.
|
|
243
|
+
*
|
|
244
|
+
* In normal mode: `warn` and `error` output.
|
|
245
|
+
* In JSON mode: `warn`, `error`, `log`, and `info` output.
|
|
246
|
+
*/
|
|
247
|
+
readonly stderr: string[];
|
|
248
|
+
/**
|
|
249
|
+
* Activity events from spinner and progress handles.
|
|
250
|
+
*
|
|
251
|
+
* Captured separately from stdout/stderr to allow targeted assertions
|
|
252
|
+
* on activity lifecycle without parsing text output. Events are
|
|
253
|
+
* recorded in chronological order.
|
|
254
|
+
*/
|
|
255
|
+
readonly activity: ActivityEvent[];
|
|
256
|
+
}
|
|
257
|
+
/**
|
|
258
|
+
* Create an output channel that captures all output into arrays.
|
|
259
|
+
*
|
|
260
|
+
* Useful in tests to assert on what a handler wrote without touching
|
|
261
|
+
* real I/O.
|
|
262
|
+
*
|
|
263
|
+
* @param options - Optional {@link OutputOptions} (minus `stdout`/`stderr`,
|
|
264
|
+
* which are wired to the capture buffers automatically).
|
|
265
|
+
*
|
|
266
|
+
* @returns A tuple of `[out, captured]` — the {@link Out} channel and the
|
|
267
|
+
* {@link CapturedOutput} buffers.
|
|
268
|
+
*
|
|
269
|
+
* @example
|
|
270
|
+
* ```ts
|
|
271
|
+
* const [out, captured] = createCaptureOutput();
|
|
272
|
+
* out.log('hello');
|
|
273
|
+
* out.warn('danger');
|
|
274
|
+
* expect(captured.stdout).toEqual(['hello\n']);
|
|
275
|
+
* expect(captured.stderr).toEqual(['danger\n']);
|
|
276
|
+
* ```
|
|
277
|
+
*/
|
|
278
|
+
declare function createCaptureOutput(options?: Omit<OutputOptions, 'stdout' | 'stderr'>): [out: Out, captured: CapturedOutput];
|
|
279
|
+
//#endregion
|
|
280
|
+
export { CaptureOutputChannel, CaptureProgressHandle, CaptureSpinnerHandle, type CapturedOutput, OutputChannel, type OutputOptions, StaticProgressHandle, StaticSpinnerHandle, TTYProgressHandle, TTYSpinnerHandle, type Verbosity, type WriteFn, createCaptureOutput, createOutput, noopProgressHandle, noopSpinnerHandle, writeLine };
|
|
@@ -0,0 +1,2 @@
|
|
|
1
|
+
import{formatDisplayValue as e}from"./display-value.mjs";import{writeLine as t}from"./writer.mjs";import{CaptureProgressHandle as n,CaptureSpinnerHandle as r}from"./activity.mjs";import{resolveOutputPolicy as i,resolveProgressPolicy as a,resolveSpinnerPolicy as o,resolveTableFormat as s,resolveTableTextStream as c,resolveTextStream as l,shouldEmitInfo as u}from"./contracts.mjs";import{createProgressHandleFromPolicy as d,createSpinnerHandleFromPolicy as f,resolveWriterForStream as p}from"./renderers.mjs";const m=()=>{};function h(e){return{stdout:e?.stdout??m,stderr:e?.stderr??m,isTTY:e?.isTTY??!1,verbosity:e?.verbosity??`normal`,jsonMode:e?.jsonMode??!1}}var g=class{options;policy;jsonMode;isTTY;constructor(e){this.options=e,this.policy=i(e),this.jsonMode=e.jsonMode,this.isTTY=e.isTTY}log(e){t(p(this.options,l(this.policy)),e)}info(e){u(this.policy)&&t(p(this.options,l(this.policy)),e)}warn(e){t(this.options.stderr,e)}error(e){t(this.options.stderr,e)}json(e){t(this.options.stdout,JSON.stringify(e))}table(e,n,r){let{columns:i,options:a}=b(n,r),o=s(this.policy,a),c=i??v(e);if(o===`json`){this.json(x(e,c));return}let l=w(e,c);l.length!==0&&t(S(this.options,this.policy,o,a),l)}activeCleanup;stopActive(){this.activeCleanup!==void 0&&(this.activeCleanup(),this.activeCleanup=void 0)}spinner(e,t){let n=f(o(this.policy,t?.fallback??`silent`),e,this.options.stderr);return n.cleanup===void 0?n.handle:(this.stopActive(),this.activeCleanup=n.cleanup,n.handle)}progress(e){let t=d(a(this.policy,e.fallback??`silent`),e,this.options.stderr);return t.cleanup===void 0?t.handle:(this.stopActive(),this.activeCleanup=t.cleanup,t.handle)}},_=class extends g{constructor(e,t){super(e),this.activity=t}spinner(e,t){return new r(e,this.activity)}progress(e){return new n(e,this.activity)}};function v(e){let t=e[0];return t===void 0?[]:Object.keys(t).map(e=>({key:e}))}function y(e){return Array.isArray(e)}function b(e,t){return t===void 0?y(e)?{columns:e,options:t}:{columns:void 0,options:e}:{columns:y(e)?e:void 0,options:t}}function x(e,t){return e.map(e=>Object.fromEntries(t.map(t=>[t.key,e[t.key]])))}function S(e,t,n,r){return n===`json`?e.stdout:p(e,c(t,r))}function C(t){return e(t)}function w(e,t){if(e.length===0||t.length===0)return``;let n=t.map(e=>e.header??e.key),r=e.map(e=>t.map(t=>C(e[t.key]))),i=n.map((e,t)=>{let n=e.length;for(let e of r){let r=e[t];r!==void 0&&r.length>n&&(n=r.length)}return n});return[n.map((e,t)=>e.padEnd(i[t]??0)).join(` `),i.map(e=>`-`.repeat(e)).join(` `),...r.map(e=>e.map((e,t)=>e.padEnd(i[t]??0)).join(` `))].join(`
|
|
2
|
+
`)}function T(e){return new g(h(e))}function E(e){let t={stdout:[],stderr:[],activity:[]};return[new _(h({...e,stdout:e=>t.stdout.push(e),stderr:e=>t.stderr.push(e)}),t.activity),t]}export{E as createCaptureOutput,T as createOutput};
|
|
@@ -0,0 +1,46 @@
|
|
|
1
|
+
import { ProgressHandle, ProgressOptions, SpinnerHandle } from "../schema/activity.mjs";
|
|
2
|
+
import { WriteFn } from "./writer.mjs";
|
|
3
|
+
import { ActivityPolicy, OutputStream } from "./contracts.mjs";
|
|
4
|
+
|
|
5
|
+
//#region src/core/output/renderers.d.ts
|
|
6
|
+
/**
|
|
7
|
+
* Paired write functions for the two standard output streams.
|
|
8
|
+
*
|
|
9
|
+
* @internal
|
|
10
|
+
*/
|
|
11
|
+
interface OutputWriters {
|
|
12
|
+
/** Write function targeting standard output. */
|
|
13
|
+
readonly stdout: WriteFn;
|
|
14
|
+
/** Write function targeting standard error. */
|
|
15
|
+
readonly stderr: WriteFn;
|
|
16
|
+
}
|
|
17
|
+
/**
|
|
18
|
+
* Spinner handle paired with its optional teardown function.
|
|
19
|
+
*
|
|
20
|
+
* @internal
|
|
21
|
+
*/
|
|
22
|
+
interface SpinnerRenderResult {
|
|
23
|
+
/** The spinner handle exposed to command handlers. */
|
|
24
|
+
readonly handle: SpinnerHandle;
|
|
25
|
+
/** Defined only when the mode requires cleanup (TTY or static); `undefined` for noop. */
|
|
26
|
+
readonly cleanup: (() => void) | undefined;
|
|
27
|
+
}
|
|
28
|
+
/**
|
|
29
|
+
* Progress handle paired with its optional teardown function.
|
|
30
|
+
*
|
|
31
|
+
* @internal
|
|
32
|
+
*/
|
|
33
|
+
interface ProgressRenderResult {
|
|
34
|
+
/** The progress handle exposed to command handlers. */
|
|
35
|
+
readonly handle: ProgressHandle;
|
|
36
|
+
/** Defined only when the mode requires cleanup (TTY or static); `undefined` for noop. */
|
|
37
|
+
readonly cleanup: (() => void) | undefined;
|
|
38
|
+
}
|
|
39
|
+
/** Select the concrete {@linkcode WriteFn} for a given stream label. @internal */
|
|
40
|
+
declare function resolveWriterForStream(writers: OutputWriters, stream: OutputStream): WriteFn;
|
|
41
|
+
/** Create a spinner handle matching the resolved {@linkcode ActivityPolicy} mode. @internal */
|
|
42
|
+
declare function createSpinnerHandleFromPolicy(policy: ActivityPolicy, text: string, stderr: WriteFn): SpinnerRenderResult;
|
|
43
|
+
/** Create a progress handle matching the resolved {@linkcode ActivityPolicy} mode. @internal */
|
|
44
|
+
declare function createProgressHandleFromPolicy(policy: ActivityPolicy, options: ProgressOptions, stderr: WriteFn): ProgressRenderResult;
|
|
45
|
+
//#endregion
|
|
46
|
+
export { type OutputWriters, type ProgressRenderResult, type SpinnerRenderResult, createProgressHandleFromPolicy, createSpinnerHandleFromPolicy, resolveWriterForStream };
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
import{StaticProgressHandle as e,StaticSpinnerHandle as t,TTYProgressHandle as n,TTYSpinnerHandle as r,noopProgressHandle as i,noopSpinnerHandle as a}from"./activity.mjs";function o(e,t){return t===`stderr`?e.stderr:e.stdout}function s(e,n,i){if(e.mode===`noop`)return{handle:a,cleanup:void 0};if(e.mode===`tty`){let e=new r(n,i);return{handle:e,cleanup:()=>e.stop()}}let o=new t(n,i);return{handle:o,cleanup:()=>o.stop()}}function c(t,r,a){if(t.mode===`noop`)return{handle:i,cleanup:void 0};if(t.mode===`tty`){let e=new n(r,a);return{handle:e,cleanup:()=>e.done()}}let o=new e(r.label,a);return{handle:o,cleanup:()=>o.done()}}export{c as createProgressHandleFromPolicy,s as createSpinnerHandleFromPolicy,o as resolveWriterForStream};
|
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
//#region src/core/output/writer.d.ts
|
|
2
|
+
/**
|
|
3
|
+
* Minimal I/O seam — the only write primitive the output module depends on.
|
|
4
|
+
*
|
|
5
|
+
* Extracted to its own file so that both `index.ts` (OutputChannel) and
|
|
6
|
+
* `activity.ts` (handle classes) can import it without a circular dependency.
|
|
7
|
+
*
|
|
8
|
+
* @module dreamcli/core/output/writer
|
|
9
|
+
* @internal
|
|
10
|
+
*/
|
|
11
|
+
/**
|
|
12
|
+
* A function that writes a string somewhere.
|
|
13
|
+
*
|
|
14
|
+
* This is the only write primitive the output layer depends on.
|
|
15
|
+
* In production it usually wraps `process.stdout.write` or
|
|
16
|
+
* `process.stderr.write`; in tests it is often a simple string accumulator.
|
|
17
|
+
*
|
|
18
|
+
* The contract is intentionally tiny:
|
|
19
|
+
* - writes are synchronous fire-and-forget
|
|
20
|
+
* - callers decide whether to append a trailing newline
|
|
21
|
+
* - there is no backpressure or flush signal
|
|
22
|
+
*
|
|
23
|
+
* @example
|
|
24
|
+
* ```ts
|
|
25
|
+
* const lines: string[] = [];
|
|
26
|
+
* const write: WriteFn = (data) => {
|
|
27
|
+
* lines.push(data);
|
|
28
|
+
* };
|
|
29
|
+
* ```
|
|
30
|
+
*/
|
|
31
|
+
type WriteFn = (data: string) => void;
|
|
32
|
+
/**
|
|
33
|
+
* Write a message followed by a newline.
|
|
34
|
+
*
|
|
35
|
+
* @param write - The underlying write function.
|
|
36
|
+
* @param message - The text to write.
|
|
37
|
+
*/
|
|
38
|
+
declare function writeLine(write: WriteFn, message: string): void;
|
|
39
|
+
//#endregion
|
|
40
|
+
export { type WriteFn, writeLine };
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
function e(e,t){e(`${t}\n`)}export{e as writeLine};
|
|
@@ -0,0 +1,79 @@
|
|
|
1
|
+
import { CommandSchema } from "../schema/command.mjs";
|
|
2
|
+
|
|
3
|
+
//#region src/core/parse/index.d.ts
|
|
4
|
+
/**
|
|
5
|
+
* Token discriminated union.
|
|
6
|
+
*
|
|
7
|
+
* The tokenizer produces these from raw argv strings. The parser then
|
|
8
|
+
* interprets them against a command schema.
|
|
9
|
+
*/
|
|
10
|
+
type Token = {
|
|
11
|
+
readonly kind: 'long-flag';
|
|
12
|
+
readonly name: string;
|
|
13
|
+
readonly value: string | undefined;
|
|
14
|
+
} | {
|
|
15
|
+
readonly kind: 'short-flags';
|
|
16
|
+
readonly chars: string;
|
|
17
|
+
} | {
|
|
18
|
+
readonly kind: 'positional';
|
|
19
|
+
readonly value: string;
|
|
20
|
+
} | {
|
|
21
|
+
readonly kind: 'separator';
|
|
22
|
+
};
|
|
23
|
+
/**
|
|
24
|
+
* Tokenize raw argv into structured tokens.
|
|
25
|
+
*
|
|
26
|
+
* Low-level utility: most apps should use {@link parse}, `cli().run()`, or
|
|
27
|
+
* `runCommand()` instead of tokenizing manually. Reach for `tokenize()` when
|
|
28
|
+
* building custom tooling such as debuggers, inspectors, or parser tests.
|
|
29
|
+
*
|
|
30
|
+
* Rules:
|
|
31
|
+
* - `--` → separator (everything after is positional)
|
|
32
|
+
* - `--flag` → long flag, no inline value
|
|
33
|
+
* - `--flag=v` → long flag with inline value
|
|
34
|
+
* - `-abc` → short flags (expanded individually by parser)
|
|
35
|
+
* - `-` → positional (convention: stdin placeholder)
|
|
36
|
+
* - everything else → positional
|
|
37
|
+
*
|
|
38
|
+
* @param argv - Raw argument strings to tokenize
|
|
39
|
+
* @returns Ordered token array ready for {@link parse}
|
|
40
|
+
*
|
|
41
|
+
* @example
|
|
42
|
+
* ```ts
|
|
43
|
+
* tokenize(['deploy', '--force', '--region=eu', '-v']);
|
|
44
|
+
* ```
|
|
45
|
+
*/
|
|
46
|
+
declare function tokenize(argv: readonly string[]): readonly Token[];
|
|
47
|
+
/**
|
|
48
|
+
* Raw parsed values before resolution (defaults, env, config, etc.).
|
|
49
|
+
*
|
|
50
|
+
* Flag values are `unknown` because type coercion happens here but the
|
|
51
|
+
* generic type info lives in the schema builders, not at runtime.
|
|
52
|
+
*/
|
|
53
|
+
interface ParseResult {
|
|
54
|
+
/** Flag values keyed by canonical flag name. */
|
|
55
|
+
readonly flags: Readonly<Record<string, unknown>>;
|
|
56
|
+
/** Positional arg values keyed by arg name. */
|
|
57
|
+
readonly args: Readonly<Record<string, unknown>>;
|
|
58
|
+
}
|
|
59
|
+
/**
|
|
60
|
+
* Parse tokenized argv against a command schema.
|
|
61
|
+
*
|
|
62
|
+
* Low-level API: most apps should let `cli()` or `runCommand()` handle parsing
|
|
63
|
+
* automatically. Call `parse()` directly when you need raw parsed values before
|
|
64
|
+
* env/config/default resolution or when writing custom tooling around schemas.
|
|
65
|
+
*
|
|
66
|
+
* @param schema - The command schema to parse against
|
|
67
|
+
* @param argv - Raw argv strings (NOT including the command name itself)
|
|
68
|
+
* @returns Parsed flag and arg values
|
|
69
|
+
* @throws ParseError for unknown flags, missing values, type mismatches
|
|
70
|
+
*
|
|
71
|
+
* @example
|
|
72
|
+
* ```ts
|
|
73
|
+
* const parsed = parse(deploy.schema, ['production', '--force']);
|
|
74
|
+
* // => { args: { target: 'production' }, flags: { force: true } }
|
|
75
|
+
* ```
|
|
76
|
+
*/
|
|
77
|
+
declare function parse(schema: CommandSchema, argv: readonly string[]): ParseResult;
|
|
78
|
+
//#endregion
|
|
79
|
+
export { type ParseResult, type Token, parse, tokenize };
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
import{getFlagAliasNames as e}from"../schema/flag.mjs";import{ParseError as t}from"../errors/index.mjs";function n(e){let t=[],n=!1;for(let r of e){if(n){t.push({kind:`positional`,value:r});continue}if(r===`--`){t.push({kind:`separator`}),n=!0;continue}if(r.startsWith(`--`)){let e=r.indexOf(`=`);e===-1?t.push({kind:`long-flag`,name:r.slice(2),value:void 0}):t.push({kind:`long-flag`,name:r.slice(2,e),value:r.slice(e+1)});continue}if(r.startsWith(`-`)&&r.length>1){t.push({kind:`short-flags`,chars:r.slice(1)});continue}t.push({kind:`positional`,value:r})}return t}function r(t){let n=new Map;for(let[r,i]of Object.entries(t)){n.set(r,[r,i]);for(let t of e(i,{includeHidden:!0}))n.set(t,[r,i])}return n}function i(e){return e.kind!==`boolean`}function a(e,n,r,i=`--${e}`){switch(r.kind){case`string`:return n;case`number`:{let r=Number(n);if(Number.isNaN(r))throw new t(`Invalid number value '${n}' for flag ${i}`,{code:`INVALID_VALUE`,details:{flag:e,input:i,value:n,expected:`number`}});return r}case`boolean`:if(n===`true`||n===`1`)return!0;if(n===`false`||n===`0`)return!1;throw new t(`Invalid boolean value '${n}' for flag ${i}. Use true/false or 1/0`,{code:`INVALID_VALUE`,details:{flag:e,input:i,value:n,expected:`boolean`}});case`enum`:{let a=r.enumValues;if(a===void 0)throw new t(`Enum flag --${e} is misconfigured: no allowed values declared`,{code:`INVALID_SCHEMA`,details:{flag:e,kind:`enum`,missing:`enumValues`}});if(!a.includes(n))throw new t(`Invalid value '${n}' for flag ${i}. Allowed: ${a.join(`, `)}`,{code:`INVALID_VALUE`,details:{flag:e,input:i,value:n,allowed:a}});return n}case`array`:return r.elementSchema?a(e,n,r.elementSchema):n;case`custom`:if(!r.parseFn)return n;try{return r.parseFn(n)}catch(r){throw r instanceof t?r:new t(`Failed to parse flag ${i}: ${r instanceof Error?r.message:String(r)}`,{code:`INVALID_VALUE`,details:{flag:e,input:i,value:n},cause:r})}}}function o(e,n,r){switch(r.kind){case`string`:return n;case`number`:{let r=Number(n);if(Number.isNaN(r))throw new t(`Invalid number value '${n}' for argument <${e}>`,{code:`INVALID_VALUE`,details:{arg:e,value:n,expected:`number`}});return r}case`enum`:{let i=r.enumValues;if(i===void 0)throw new t(`Enum argument <${e}> is misconfigured: no allowed values declared`,{code:`INVALID_SCHEMA`,details:{arg:e,kind:`enum`,missing:`enumValues`}});if(!i.includes(n))throw new t(`Invalid value '${n}' for argument <${e}>. Allowed: ${i.join(`, `)}`,{code:`INVALID_VALUE`,details:{arg:e,value:n,allowed:i}});return n}case`custom`:if(!r.parseFn)return n;try{return r.parseFn(n)}catch(r){throw r instanceof t?r:new t(`Failed to parse argument <${e}>: ${r instanceof Error?r.message:String(r)}`,{code:`INVALID_VALUE`,details:{arg:e,value:n},cause:r})}}}function s(e,t){let i=n(t),a=r(e.flags),o={},s=[],u=0;for(;u<i.length;){let e=i[u];if(e===void 0)break;if(e.kind===`separator`){u++;continue}if(e.kind===`positional`){s.push(e.value),u++;continue}if(e.kind===`long-flag`){u=c(e,i,u,a,o);continue}u=l(e,i,u,a,o)}return{flags:o,args:d(e.args,s)}}function c(e,n,r,o,s){let c=o.get(e.name);if(!c){let n=f(e.name,o);throw new t(`Unknown flag --${e.name}${n?`. Did you mean --${n}?`:``}`,{code:`UNKNOWN_FLAG`,details:{flag:e.name,...n?{suggestion:n}:{}},...n?{suggest:`--${n}`}:{}})}let[l,d]=c;if(!i(d))return e.value===void 0?s[l]=!0:s[l]=a(l,e.value,d,`--${e.name}`),r+1;if(e.value!==void 0)return u(s,l,d,e.value),r+1;let p=n[r+1];if(!p||p.kind!==`positional`)throw new t(`Flag --${e.name} requires a value`,{code:`MISSING_VALUE`,details:{flag:l,input:e.name,kind:d.kind}});return u(s,l,d,p.value,`--${e.name}`),r+2}function l(e,n,r,a,o){let{chars:s}=e,c=r+1;for(let e=0;e<s.length;e++){let r=s.charAt(e),l=a.get(r);if(!l)throw new t(`Unknown flag -${r}`,{code:`UNKNOWN_FLAG`,details:{flag:r}});let[d,f]=l;if(!i(f)){o[d]=!0;continue}if(e<s.length-1){u(o,d,f,s.slice(e+1),`-${r}`);break}let p=n[c];if(!p||p.kind!==`positional`)throw new t(`Flag -${r} requires a value`,{code:`MISSING_VALUE`,details:{flag:d,input:r,kind:f.kind}});u(o,d,f,p.value,`-${r}`),c++}return c}function u(e,t,n,r,i=`--${t}`){let o=a(t,r,n,i);if(n.kind===`array`){let n=e[t];Array.isArray(n)?n.push(o):e[t]=[o]}else e[t]=o}function d(e,n){let r={},i=0;for(let t of e){if(t.schema.variadic){let e=n.slice(i);r[t.name]=e.map(e=>o(t.name,e,t.schema)),i=n.length;break}let e=n[i];e!==void 0&&(r[t.name]=o(t.name,e,t.schema),i++)}if(i<n.length){let r=n.slice(i);throw new t(`Unexpected positional argument${r.length>1?`s`:``}: ${r.join(`, `)}`,{code:`UNEXPECTED_POSITIONAL`,details:{excess:r,expected:e.length}})}return r}function f(e,t){let n,r=1/0,i=Math.max(2,Math.floor(e.length/2));for(let a of t.keys()){let o=t.get(a);if(o===void 0)continue;let[s,c]=o,l=c.aliases.find(e=>e.name===a);if(a.length<2||a!==s&&l?.hidden)continue;let u=p(e,a);u<r&&u<=i&&(r=u,n=a)}return n}function p(e,t){if(e===t)return 0;if(e.length===0)return t.length;if(t.length===0)return e.length;let n=e.length<=t.length?e:t,r=e.length<=t.length?t:e,i=n.length,a=r.length,o=Array.from({length:i+1},(e,t)=>t);for(let e=1;e<=a;e++){let t=o[0]??0;o[0]=e;for(let a=1;a<=i;a++){let i=n.charAt(a-1)===r.charAt(e-1)?0:1,s=Math.min((o[a]??0)+1,(o[a-1]??0)+1,t+i);t=o[a]??0,o[a]=s}}return o[i]??0}export{s as parse,n as tokenize};
|