@kjanat/dreamcli 0.0.0 → 1.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 +667 -0
- package/LICENSE +22 -0
- package/README.md +370 -0
- package/dist/adapter-B37d9oia.mjs +1 -0
- package/dist/adapter-CCSh5juX.cjs +1 -0
- package/dist/adapter-DIwO-q7K.d.mts +3447 -0
- package/dist/adapter-DQnxxLiE.d.cts +3447 -0
- package/dist/auto-5cjZaF9V.mjs +3 -0
- package/dist/auto-B0eSgoDw.cjs +3 -0
- package/dist/index.cjs +10 -0
- package/dist/index.d.cts +920 -0
- package/dist/index.d.mts +920 -0
- package/dist/index.mjs +10 -0
- package/dist/runtime.cjs +1 -0
- package/dist/runtime.d.cts +253 -0
- package/dist/runtime.d.mts +253 -0
- package/dist/runtime.mjs +1 -0
- package/dist/testkit-CEDYPvhF.mjs +14 -0
- package/dist/testkit-ClIKijxC.cjs +14 -0
- package/dist/testkit.cjs +1 -0
- package/dist/testkit.d.cts +25 -0
- package/dist/testkit.d.mts +25 -0
- package/dist/testkit.mjs +1 -0
- package/examples/basic.ts +33 -0
- package/examples/gh/package.json +48 -0
- package/examples/gh/src/commands/auth.ts +66 -0
- package/examples/gh/src/commands/issue.ts +120 -0
- package/examples/gh/src/commands/pr.ts +125 -0
- package/examples/gh/src/data/issues.yaml +5 -0
- package/examples/gh/src/data/issues.yaml.d.ts +17 -0
- package/examples/gh/src/data/pull-requests.yaml +7 -0
- package/examples/gh/src/data/pull-requests.yaml.d.ts +18 -0
- package/examples/gh/src/lib/auth.ts +37 -0
- package/examples/gh/src/lib/utils.ts +17 -0
- package/examples/gh/src/main.test.ts +306 -0
- package/examples/gh/src/main.ts +38 -0
- package/examples/gh/tsconfig.json +37 -0
- package/examples/interactive.ts +66 -0
- package/examples/json-mode.ts +93 -0
- package/examples/middleware.ts +71 -0
- package/examples/multi-command.ts +66 -0
- package/examples/spinner-progress.ts +49 -0
- package/examples/testing.ts +145 -0
- package/examples/tsconfig.json +17 -0
- package/package.json +123 -2
- package/src/core/cli/AGENTS.md +72 -0
- package/src/core/cli/dispatch.ts +282 -0
- package/src/core/cli/index.ts +1425 -0
- package/src/core/cli/plugin.ts +111 -0
- package/src/core/cli/propagate.ts +97 -0
- package/src/core/cli/root-help.ts +269 -0
- package/src/core/cli/root-surface.ts +74 -0
- package/src/core/completion/AGENTS.md +72 -0
- package/src/core/completion/completion-test-helpers.ts +48 -0
- package/src/core/completion/index.ts +82 -0
- package/src/core/completion/shells/bash.ts +456 -0
- package/src/core/completion/shells/fish.ts +24 -0
- package/src/core/completion/shells/powershell.ts +24 -0
- package/src/core/completion/shells/shared.ts +283 -0
- package/src/core/completion/shells/zsh.ts +376 -0
- package/src/core/config/index.ts +404 -0
- package/src/core/config/package-json.ts +216 -0
- package/src/core/errors/index.ts +178 -0
- package/src/core/help/index.ts +559 -0
- package/src/core/json-schema/index.ts +705 -0
- package/src/core/output/AGENTS.md +69 -0
- package/src/core/output/activity.ts +568 -0
- package/src/core/output/display-value.ts +48 -0
- package/src/core/output/index.ts +704 -0
- package/src/core/output/writer.ts +46 -0
- package/src/core/parse/index.ts +643 -0
- package/src/core/prompt/index.ts +566 -0
- package/src/core/resolve/AGENTS.md +69 -0
- package/src/core/resolve/index.ts +1331 -0
- package/src/core/schema/AGENTS.md +61 -0
- package/src/core/schema/activity.ts +237 -0
- package/src/core/schema/arg.ts +707 -0
- package/src/core/schema/command.ts +1263 -0
- package/src/core/schema/flag.ts +651 -0
- package/src/core/schema/index.ts +82 -0
- package/src/core/schema/middleware.ts +171 -0
- package/src/core/schema/prompt.ts +148 -0
- package/src/core/schema/run.ts +187 -0
- package/src/core/testkit/AGENTS.md +55 -0
- package/src/core/testkit/index.ts +365 -0
- package/src/index.ts +164 -0
- package/src/runtime/AGENTS.md +74 -0
- package/src/runtime/adapter.ts +300 -0
- package/src/runtime/auto.ts +110 -0
- package/src/runtime/bun.ts +55 -0
- package/src/runtime/deno.ts +355 -0
- package/src/runtime/detect.ts +102 -0
- package/src/runtime/index.ts +21 -0
- package/src/runtime/node-builtins.d.ts +23 -0
- package/src/runtime/node.ts +278 -0
- package/src/runtime/paths.ts +56 -0
- package/src/runtime/support.ts +119 -0
- package/src/runtime/test-helpers.ts +40 -0
- package/src/runtime.ts +31 -0
- package/src/testkit.ts +23 -0
- package/src/version.ts +20 -0
|
@@ -0,0 +1,61 @@
|
|
|
1
|
+
# schema — Command/Flag/Arg/Middleware builders + prompt config types
|
|
2
|
+
|
|
3
|
+
Only multi-file module in `core/`. All others use single `index.ts`.
|
|
4
|
+
|
|
5
|
+
## FILES
|
|
6
|
+
|
|
7
|
+
| File | Lines | Purpose |
|
|
8
|
+
| --------------- | ----: | ----------------------------------------------------------------------------------------------------------------------------------- |
|
|
9
|
+
| `command.ts` | 784 | `CommandBuilder<F, A, C>` — fluent builder + `Out` interface + command schema |
|
|
10
|
+
| `activity.ts` | 150 | Activity types — `Fallback`, `SpinnerHandle`, `ProgressHandle`, `SpinnerOptions`, `ProgressOptions`, `ActivityEvent`, `TableColumn` |
|
|
11
|
+
| `flag.ts` | 455 | `FlagBuilder` — `flag.string()`, `.boolean()`, `.number()`, `.count()`, `.enum()`, `.custom()` |
|
|
12
|
+
| `arg.ts` | 341 | `ArgBuilder` — `arg.string()`, `.number()`, `.enum()` |
|
|
13
|
+
| `middleware.ts` | 164 | `middleware<Output>(handler)` factory — phantom-branded `Middleware<Output>` type |
|
|
14
|
+
| `prompt.ts` | 70 | Prompt config types — `PromptConfig` discriminated union (4 kinds) |
|
|
15
|
+
| `run.ts` | 47 | `RunResult` — structured execution result (canonical definition, re-exported by testkit) |
|
|
16
|
+
| `index.ts` | 80 | Barrel — re-exports all public symbols |
|
|
17
|
+
|
|
18
|
+
## TYPE SYSTEM PATTERNS
|
|
19
|
+
|
|
20
|
+
- **`F` accumulator**: `{} & Record<name, InferFlag<...>>` grows per `.flag()` call
|
|
21
|
+
- **`A` accumulator**: same pattern for `.arg()`
|
|
22
|
+
- **`C` accumulator**: `Record<string, never>` replaced entirely on first `.middleware()`, then
|
|
23
|
+
intersection-grown via `WidenContext<C, Output>`
|
|
24
|
+
- **`{}` as identity element**: `biome-ignore noBannedTypes` on `CommandBuilder` class generic
|
|
25
|
+
defaults — justified, do not "fix"
|
|
26
|
+
- **Phantom brand**: `Middleware<Output>` carries type info at compile time, erased at runtime.
|
|
27
|
+
`_output` property is phantom — compile-time only. Same for `_value` on FlagBuilder/ArgBuilder.
|
|
28
|
+
- **Type erasure**: `eraseBuilder()` / `eraseCommand()` centralize `as unknown as` casts for
|
|
29
|
+
heterogeneous subcommand storage. These are the justified `as` cast sites.
|
|
30
|
+
|
|
31
|
+
## `command.ts` TYPE DENSITY
|
|
32
|
+
|
|
33
|
+
21+ type/interface exports split across `command.ts` and `activity.ts`:
|
|
34
|
+
|
|
35
|
+
- **Activity types** (`activity.ts`): `ActivityEvent` (10-variant DU), `SpinnerHandle`,
|
|
36
|
+
`ProgressHandle`, `SpinnerOptions`, `ProgressOptions`, `Fallback`, `TableColumn`
|
|
37
|
+
- **Output interface** (`command.ts`): `Out` (~110 lines JSDoc + signatures) — imports activity
|
|
38
|
+
types from `./activity.ts`
|
|
39
|
+
- **Command schema** (`command.ts`): `CommandSchema`, `ErasedCommand`, `ActionHandler`,
|
|
40
|
+
`ActionParams`, `InteractiveResolver`, `CommandExample`, etc.
|
|
41
|
+
|
|
42
|
+
Activity types live in `activity.ts` (still in schema/, not in output/) because `Out` needs them in
|
|
43
|
+
`CommandBuilder.action()` signature. `command.ts` imports them from `./activity.ts`.
|
|
44
|
+
|
|
45
|
+
## ADDING A FLAG TYPE
|
|
46
|
+
|
|
47
|
+
1. Add variant to `FlagKind` union in `flag.ts`
|
|
48
|
+
2. Add factory method on `FlagBuilder`
|
|
49
|
+
3. Update `InferFlag` conditional type
|
|
50
|
+
4. Wire through `resolve/` (add coercion case in the unified `coerceValue()` function)
|
|
51
|
+
5. Add tests in `flag.test.ts` + `resolve.test.ts`
|
|
52
|
+
|
|
53
|
+
## GOTCHAS
|
|
54
|
+
|
|
55
|
+
- `.middleware()` drops current handler (type signature changes) — intentional, forces
|
|
56
|
+
re-registration after middleware addition
|
|
57
|
+
- Prompt types consumed directly by `core/prompt/` and `core/resolve/` (bypasses barrel to avoid
|
|
58
|
+
circular dep through `schema → prompt → schema` path)
|
|
59
|
+
- `deprecated()` modifier on both FlagBuilder and ArgBuilder — collects `DeprecationWarning` structs
|
|
60
|
+
during resolution
|
|
61
|
+
- Prompt types in `prompt.ts` re-exported through `flag.ts`, not through `prompt.ts` in the barrel
|
|
@@ -0,0 +1,237 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Activity types — spinner and progress bar handles, options, events.
|
|
3
|
+
*
|
|
4
|
+
* These types define the contract for `Out.spinner()` and `Out.progress()`
|
|
5
|
+
* lifecycle management. Implementations live in `core/output/activity.ts`.
|
|
6
|
+
*
|
|
7
|
+
* @module dreamcli/core/schema/activity
|
|
8
|
+
*/
|
|
9
|
+
|
|
10
|
+
// --- Fallback strategy
|
|
11
|
+
|
|
12
|
+
/**
|
|
13
|
+
* Non-TTY fallback strategy for spinners and progress bars.
|
|
14
|
+
*
|
|
15
|
+
* - `'silent'` — no output at all (default). Ideal for CI where decorative
|
|
16
|
+
* output is noise.
|
|
17
|
+
* - `'static'` — emit plain text via `out.log()` / `out.error()` at
|
|
18
|
+
* lifecycle boundaries (start, succeed, fail). No animation.
|
|
19
|
+
*/
|
|
20
|
+
type Fallback = 'silent' | 'static';
|
|
21
|
+
|
|
22
|
+
// --- Spinner
|
|
23
|
+
|
|
24
|
+
/** Options for {@link Out.spinner}. */
|
|
25
|
+
interface SpinnerOptions {
|
|
26
|
+
/**
|
|
27
|
+
* Fallback strategy when `!isTTY` or `jsonMode`.
|
|
28
|
+
* @defaultValue `'silent'`
|
|
29
|
+
*/
|
|
30
|
+
readonly fallback?: Fallback;
|
|
31
|
+
}
|
|
32
|
+
|
|
33
|
+
/**
|
|
34
|
+
* Handle returned by {@link Out.spinner} for lifecycle control.
|
|
35
|
+
*
|
|
36
|
+
* Terminal methods (`succeed`, `fail`, `stop`) are idempotent — calling any
|
|
37
|
+
* of them after the handle is already stopped is a no-op, not an error.
|
|
38
|
+
*/
|
|
39
|
+
interface SpinnerHandle {
|
|
40
|
+
/** Update the spinner text (no-op if stopped). */
|
|
41
|
+
update(text: string): void;
|
|
42
|
+
/** Stop with a success symbol and optional final text. */
|
|
43
|
+
succeed(text?: string): void;
|
|
44
|
+
/** Stop with a failure symbol and optional final text. */
|
|
45
|
+
fail(text?: string): void;
|
|
46
|
+
/** Stop the spinner without a status symbol. */
|
|
47
|
+
stop(): void;
|
|
48
|
+
/**
|
|
49
|
+
* Wrap a promise: auto-succeed on resolve, auto-fail on reject.
|
|
50
|
+
*
|
|
51
|
+
* @returns The resolved value of the wrapped promise.
|
|
52
|
+
*/
|
|
53
|
+
wrap<T>(
|
|
54
|
+
promise: Promise<T>,
|
|
55
|
+
options?: {
|
|
56
|
+
readonly succeed?: string;
|
|
57
|
+
readonly fail?: string;
|
|
58
|
+
},
|
|
59
|
+
): Promise<T>;
|
|
60
|
+
}
|
|
61
|
+
|
|
62
|
+
// --- Progress
|
|
63
|
+
|
|
64
|
+
/** Options for {@link Out.progress}. */
|
|
65
|
+
interface ProgressOptions {
|
|
66
|
+
/**
|
|
67
|
+
* Total units of work. When provided, the bar shows a determinate
|
|
68
|
+
* percentage. When omitted, the bar pulses in indeterminate mode.
|
|
69
|
+
*/
|
|
70
|
+
readonly total?: number;
|
|
71
|
+
/** Label displayed alongside the progress bar. */
|
|
72
|
+
readonly label?: string;
|
|
73
|
+
/**
|
|
74
|
+
* Fallback strategy when `!isTTY` or `jsonMode`.
|
|
75
|
+
* @defaultValue `'silent'`
|
|
76
|
+
*/
|
|
77
|
+
readonly fallback?: Fallback;
|
|
78
|
+
}
|
|
79
|
+
|
|
80
|
+
/**
|
|
81
|
+
* Handle returned by {@link Out.progress} for lifecycle control.
|
|
82
|
+
*
|
|
83
|
+
* Terminal methods (`done`, `fail`) are idempotent — calling any
|
|
84
|
+
* of them after the handle is already stopped is a no-op.
|
|
85
|
+
*/
|
|
86
|
+
interface ProgressHandle {
|
|
87
|
+
/** Advance progress by `n` units (default 1). */
|
|
88
|
+
increment(n?: number): void;
|
|
89
|
+
/** Set progress to an absolute value. */
|
|
90
|
+
update(value: number): void;
|
|
91
|
+
/** Mark progress as complete with an optional final message. */
|
|
92
|
+
done(text?: string): void;
|
|
93
|
+
/** Mark progress as failed with an optional final message. */
|
|
94
|
+
fail(text?: string): void;
|
|
95
|
+
}
|
|
96
|
+
|
|
97
|
+
// --- Activity events
|
|
98
|
+
|
|
99
|
+
/**
|
|
100
|
+
* Discriminated union of spinner and progress lifecycle events.
|
|
101
|
+
*
|
|
102
|
+
* Captured by testkit in {@link RunResult.activity} for assertion
|
|
103
|
+
* without polluting stdout/stderr arrays.
|
|
104
|
+
*/
|
|
105
|
+
type ActivityEvent =
|
|
106
|
+
| {
|
|
107
|
+
/** Spinner created and started. */
|
|
108
|
+
readonly type: 'spinner:start';
|
|
109
|
+
/** Initial spinner text. */
|
|
110
|
+
readonly text: string;
|
|
111
|
+
}
|
|
112
|
+
| {
|
|
113
|
+
/** Spinner text changed. */
|
|
114
|
+
readonly type: 'spinner:update';
|
|
115
|
+
/** Updated spinner text. */
|
|
116
|
+
readonly text: string;
|
|
117
|
+
}
|
|
118
|
+
| {
|
|
119
|
+
/** Spinner completed successfully. */
|
|
120
|
+
readonly type: 'spinner:succeed';
|
|
121
|
+
/** Success message. */
|
|
122
|
+
readonly text: string;
|
|
123
|
+
}
|
|
124
|
+
| {
|
|
125
|
+
/** Spinner stopped with an error. */
|
|
126
|
+
readonly type: 'spinner:fail';
|
|
127
|
+
/** Failure message. */
|
|
128
|
+
readonly text: string;
|
|
129
|
+
}
|
|
130
|
+
| {
|
|
131
|
+
/** Spinner stopped without a final status. */
|
|
132
|
+
readonly type: 'spinner:stop';
|
|
133
|
+
}
|
|
134
|
+
| {
|
|
135
|
+
/** Progress bar created and started. */
|
|
136
|
+
readonly type: 'progress:start';
|
|
137
|
+
/** Bar label. */
|
|
138
|
+
readonly label: string;
|
|
139
|
+
/** Known total, or `undefined` for indeterminate. */
|
|
140
|
+
readonly total: number | undefined;
|
|
141
|
+
}
|
|
142
|
+
| {
|
|
143
|
+
/** Progress bar advanced. */
|
|
144
|
+
readonly type: 'progress:increment';
|
|
145
|
+
/** Amount advanced. */
|
|
146
|
+
readonly delta: number;
|
|
147
|
+
}
|
|
148
|
+
| {
|
|
149
|
+
/** Progress bar set to an absolute value. */
|
|
150
|
+
readonly type: 'progress:update';
|
|
151
|
+
/** New absolute value. */
|
|
152
|
+
readonly value: number;
|
|
153
|
+
}
|
|
154
|
+
| {
|
|
155
|
+
/** Progress bar completed. */
|
|
156
|
+
readonly type: 'progress:done';
|
|
157
|
+
/** Completion message, if any. */
|
|
158
|
+
readonly text: string | undefined;
|
|
159
|
+
}
|
|
160
|
+
| {
|
|
161
|
+
/** Progress bar stopped with an error. */
|
|
162
|
+
readonly type: 'progress:fail';
|
|
163
|
+
/** Failure message, if any. */
|
|
164
|
+
readonly text: string | undefined;
|
|
165
|
+
};
|
|
166
|
+
|
|
167
|
+
// --- Table column descriptor
|
|
168
|
+
|
|
169
|
+
/**
|
|
170
|
+
* Describes a single column in table output.
|
|
171
|
+
*
|
|
172
|
+
* @typeParam T - The row object type (inferred from the rows array).
|
|
173
|
+
*/
|
|
174
|
+
interface TableColumn<T extends Record<string, unknown>> {
|
|
175
|
+
/** Property key on the row objects to display in this column. */
|
|
176
|
+
readonly key: keyof T & string;
|
|
177
|
+
/**
|
|
178
|
+
* Header label for the column.
|
|
179
|
+
* @defaultValue the {@link TableColumn.key | key} value
|
|
180
|
+
*/
|
|
181
|
+
readonly header?: string;
|
|
182
|
+
}
|
|
183
|
+
|
|
184
|
+
/** Render format override for {@link Out.table}. */
|
|
185
|
+
type TableFormat = 'auto' | 'text' | 'json';
|
|
186
|
+
|
|
187
|
+
/** Output stream override for text table rendering. */
|
|
188
|
+
type TableStream = 'stdout' | 'stderr';
|
|
189
|
+
|
|
190
|
+
/**
|
|
191
|
+
* Per-call table output options.
|
|
192
|
+
*
|
|
193
|
+
* `format: 'auto'` preserves the current mode-dependent behavior.
|
|
194
|
+
* `format: 'json'` always emits a JSON array to stdout.
|
|
195
|
+
* `format: 'text'` always renders a human-readable table; when `stream` is
|
|
196
|
+
* omitted, text defaults to stdout in normal mode and stderr in jsonMode.
|
|
197
|
+
*/
|
|
198
|
+
/** Preserve the mode-dependent default — text tables in normal mode, JSON in `jsonMode`. */
|
|
199
|
+
interface TableOptionsAuto {
|
|
200
|
+
/**
|
|
201
|
+
* Follow the current output mode (text in normal, JSON in jsonMode).
|
|
202
|
+
* @defaultValue `'auto'`
|
|
203
|
+
*/
|
|
204
|
+
readonly format?: 'auto';
|
|
205
|
+
}
|
|
206
|
+
|
|
207
|
+
/** Force JSON array output to stdout regardless of output mode. */
|
|
208
|
+
interface TableOptionsJson {
|
|
209
|
+
/** Always emit a JSON array to stdout. */
|
|
210
|
+
readonly format: 'json';
|
|
211
|
+
}
|
|
212
|
+
|
|
213
|
+
/** Force human-readable text table output, optionally routed to a specific {@link TableStream}. */
|
|
214
|
+
interface TableOptionsText {
|
|
215
|
+
/** Always render a human-readable text table. */
|
|
216
|
+
readonly format: 'text';
|
|
217
|
+
/** Target stream for text output. Falls back to stdout (stderr in jsonMode). */
|
|
218
|
+
readonly stream?: TableStream;
|
|
219
|
+
}
|
|
220
|
+
|
|
221
|
+
/** Per-call rendering options for {@link Out.table}. */
|
|
222
|
+
type TableOptions = TableOptionsAuto | TableOptionsJson | TableOptionsText;
|
|
223
|
+
|
|
224
|
+
// --- Exports
|
|
225
|
+
|
|
226
|
+
export type {
|
|
227
|
+
ActivityEvent,
|
|
228
|
+
Fallback,
|
|
229
|
+
ProgressHandle,
|
|
230
|
+
ProgressOptions,
|
|
231
|
+
SpinnerHandle,
|
|
232
|
+
SpinnerOptions,
|
|
233
|
+
TableColumn,
|
|
234
|
+
TableFormat,
|
|
235
|
+
TableOptions,
|
|
236
|
+
TableStream,
|
|
237
|
+
};
|