@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
|
@@ -1,72 +0,0 @@
|
|
|
1
|
-
# completion — Shell completion script generation
|
|
2
|
-
|
|
3
|
-
Split into per-shell generators under `shells/`. Barrel `index.ts` re-exports public API and
|
|
4
|
-
dispatches via `generateCompletion()`.
|
|
5
|
-
|
|
6
|
-
## FILES
|
|
7
|
-
|
|
8
|
-
| File | Lines | Purpose |
|
|
9
|
-
| ---------------------- | ----: | -------------------------------------------------------- |
|
|
10
|
-
| `index.ts` | 80 | Barrel — `Shell` type, `SHELLS` constant, dispatch |
|
|
11
|
-
| `shells/shared.ts` | 160 | `CommandNode`, `walkCommandTree`, escaping, `versionTag` |
|
|
12
|
-
| `shells/bash.ts` | 275 | `generateBashCompletion()` + all bash helpers |
|
|
13
|
-
| `shells/zsh.ts` | 280 | `generateZshCompletion()` + all zsh helpers |
|
|
14
|
-
| `shells/fish.ts` | 25 | Stub — throws `UNSUPPORTED_OPERATION` |
|
|
15
|
-
| `shells/powershell.ts` | 25 | Stub — throws `UNSUPPORTED_OPERATION` |
|
|
16
|
-
|
|
17
|
-
## PUBLIC API
|
|
18
|
-
|
|
19
|
-
| Symbol | Exported from | Role |
|
|
20
|
-
| -------------------------- | ------------- | ------------------------------------------------ |
|
|
21
|
-
| `generateCompletion()` | `index.ts` | Shell-agnostic dispatch → per-shell generators |
|
|
22
|
-
| `generateBashCompletion()` | `index.ts` | Bash completion script from command tree |
|
|
23
|
-
| `generateZshCompletion()` | `index.ts` | Zsh completion script from command tree |
|
|
24
|
-
| `SHELLS` | `index.ts` | `readonly ['bash', 'zsh', 'fish', 'powershell']` |
|
|
25
|
-
| `CompletionOptions` | `index.ts` | Options type (re-exported from `shared.ts`) |
|
|
26
|
-
| `Shell` | `index.ts` | Union type of supported shells |
|
|
27
|
-
|
|
28
|
-
## ARCHITECTURE
|
|
29
|
-
|
|
30
|
-
1. Walk command tree → `CommandNode[]` (shared infrastructure in `shells/shared.ts`)
|
|
31
|
-
2. Per-shell generator receives `CLISchema` + `CompletionOptions`, calls `walkCommandTree()`
|
|
32
|
-
3. Emit shell-specific functions (one per command node)
|
|
33
|
-
4. Bash: `complete -F` with `compgen`; Zsh: `_arguments` + `_describe`
|
|
34
|
-
|
|
35
|
-
Handles nested command groups: `mycli db migrate` generates completions for each depth level.
|
|
36
|
-
|
|
37
|
-
## INTERNAL HELPERS (all `@internal`)
|
|
38
|
-
|
|
39
|
-
### `shells/shared.ts`
|
|
40
|
-
|
|
41
|
-
- `versionTag()` — build-time version string for script headers
|
|
42
|
-
- `CommandNode` — flattened tree node with propagated flag context
|
|
43
|
-
- `walkCommandTree()` — depth-first command tree walker
|
|
44
|
-
- `sanitizeShellIdentifier()`, `quoteShellArg()` — shell escaping
|
|
45
|
-
|
|
46
|
-
### `shells/bash.ts`
|
|
47
|
-
|
|
48
|
-
- `emitBashPathDetection`, `quoteShellCasePattern` — subcommand path detection
|
|
49
|
-
- `escapeForSingleQuote`, `escapeBashDollarQuote` — bash string escaping
|
|
50
|
-
- `formatBashEnumCompletion` — COMPREPLY for enum values
|
|
51
|
-
- `collectFlagWords`, `collectEnumCasesFromFlags`, `EnumCase` — flag extraction
|
|
52
|
-
|
|
53
|
-
### `shells/zsh.ts`
|
|
54
|
-
|
|
55
|
-
- `emitZshGroupFunction`, `emitZshLeafFunction` — helper function emitters
|
|
56
|
-
- `escapeZshDescription`, `escapeZshEnumValue` — zsh string escaping
|
|
57
|
-
- `buildZshFlagSpecsFromFlags`, `buildZshFlagSpecs` — `_arguments` spec builders
|
|
58
|
-
|
|
59
|
-
## GOTCHAS
|
|
60
|
-
|
|
61
|
-
- `shells/shared.ts` imports `cli/propagate.ts` directly (`@internal` file, not through cli barrel)
|
|
62
|
-
— needs `collectPropagatedFlags()` for flag inheritance in nested commands
|
|
63
|
-
- `biome-ignore noTemplateCurlyInString` in `shells/bash.ts` — emitting bash `${words[i]}` syntax
|
|
64
|
-
- Fish and PowerShell stubs throw `CLIError` with code `UNSUPPORTED_OPERATION`
|
|
65
|
-
- `CompletionOptions` lives in `shells/shared.ts`, re-exported through `index.ts`
|
|
66
|
-
|
|
67
|
-
## TEST FILES (2)
|
|
68
|
-
|
|
69
|
-
| File | Tests |
|
|
70
|
-
| ----------------------- | ----------------------------------------------------------- |
|
|
71
|
-
| `completion.test.ts` | ~1690 lines — largest test file; bash + zsh output matching |
|
|
72
|
-
| (cli-completion-e2e.ts) | Lives in `cli/` — end-to-end completion via CLI builder |
|
|
@@ -1,48 +0,0 @@
|
|
|
1
|
-
/**
|
|
2
|
-
* Shared test helpers for extracting structure from generated completion scripts.
|
|
3
|
-
*
|
|
4
|
-
* @module dreamcli/core/completion/completion-test-helpers
|
|
5
|
-
* @internal
|
|
6
|
-
*/
|
|
7
|
-
|
|
8
|
-
/**
|
|
9
|
-
* @internal
|
|
10
|
-
* Extract the root-level completion words from a bash completion script.
|
|
11
|
-
*
|
|
12
|
-
* Finds the last `compgen -W '...' -- "$cur"` block and returns the
|
|
13
|
-
* space-separated words as an array.
|
|
14
|
-
*
|
|
15
|
-
* @param script - The full generated bash completion script.
|
|
16
|
-
* @returns The root-level completion words.
|
|
17
|
-
*/
|
|
18
|
-
function extractBashRootWords(script: string): readonly string[] {
|
|
19
|
-
const matches = [...script.matchAll(/compgen -W '([^']*)' -- "\$cur"/g)];
|
|
20
|
-
const words = matches[matches.length - 1]?.[1];
|
|
21
|
-
if (words === undefined) {
|
|
22
|
-
throw new Error('Could not find root bash completion words');
|
|
23
|
-
}
|
|
24
|
-
return words.split(' ').filter(Boolean);
|
|
25
|
-
}
|
|
26
|
-
|
|
27
|
-
/**
|
|
28
|
-
* @internal
|
|
29
|
-
* Extract the body of the root zsh completion function from a zsh
|
|
30
|
-
* completion script.
|
|
31
|
-
*
|
|
32
|
-
* @param script - The full generated zsh completion script.
|
|
33
|
-
* @param funcName - The function name to locate (e.g. `'_mycli'`).
|
|
34
|
-
* @returns The function body (from signature through closing brace).
|
|
35
|
-
*/
|
|
36
|
-
function extractZshRootFunction(script: string, funcName: string): string {
|
|
37
|
-
const start = script.indexOf(`${funcName}() {`);
|
|
38
|
-
if (start === -1) {
|
|
39
|
-
throw new Error(`Could not find zsh root function '${funcName}'`);
|
|
40
|
-
}
|
|
41
|
-
const end = script.indexOf(`\n}\n\n${funcName} "$@"`, start);
|
|
42
|
-
if (end === -1) {
|
|
43
|
-
throw new Error(`Could not find end of zsh root function '${funcName}'`);
|
|
44
|
-
}
|
|
45
|
-
return script.slice(start, end + 2);
|
|
46
|
-
}
|
|
47
|
-
|
|
48
|
-
export { extractBashRootWords, extractZshRootFunction };
|
|
@@ -1,69 +0,0 @@
|
|
|
1
|
-
# output — OutputChannel, spinner/progress, TTY rendering
|
|
2
|
-
|
|
3
|
-
Three files: `writer.ts` (leaf, ~30 lines), `activity.ts` (handle classes, ~581 lines), `index.ts`
|
|
4
|
-
(OutputChannel + factories, ~570 lines).
|
|
5
|
-
|
|
6
|
-
Dependency graph (no cycles): `writer.ts` ← `activity.ts` ← `index.ts` → `writer.ts`.
|
|
7
|
-
|
|
8
|
-
## KEY TYPES
|
|
9
|
-
|
|
10
|
-
| Symbol | Visibility | Role |
|
|
11
|
-
| ----------------------- | ----------- | ------------------------------------------------ |
|
|
12
|
-
| `createOutput()` | **Public** | Factory → `Out` interface (mode-dispatched) |
|
|
13
|
-
| `createCaptureOutput()` | **Public** | Factory → `Out` + `CapturedOutput` (for testkit) |
|
|
14
|
-
| `OutputChannel` | `@internal` | Concrete class implementing `Out` |
|
|
15
|
-
| `CaptureOutputChannel` | `@internal` | Subclass capturing output + activity events |
|
|
16
|
-
|
|
17
|
-
## OUTPUT MODES
|
|
18
|
-
|
|
19
|
-
| Mode | `out.log` | `out.json` | Spinner/Progress |
|
|
20
|
-
| ------- | ---------- | ---------- | ---------------- |
|
|
21
|
-
| Normal | → stdout | → stdout | TTY handles |
|
|
22
|
-
| JSON | → stderr | → stdout | Noop handles |
|
|
23
|
-
| Quiet | suppressed | → stdout | Noop handles |
|
|
24
|
-
| Non-TTY | → stdout | → stdout | Static handles |
|
|
25
|
-
| Capture | → array | → array | Capture handles |
|
|
26
|
-
|
|
27
|
-
## ACTIVITY HANDLES
|
|
28
|
-
|
|
29
|
-
Four handle tiers per activity type (spinner + progress):
|
|
30
|
-
|
|
31
|
-
| Handle class | When used | Behavior |
|
|
32
|
-
| ---------------------- | ---------- | --------------------------------------------- |
|
|
33
|
-
| `noopSpinnerHandle` | JSON/quiet | Silent, all methods no-op |
|
|
34
|
-
| `StaticSpinnerHandle` | non-TTY | Writes start/succeed/fail as plain text lines |
|
|
35
|
-
| `TTYSpinnerHandle` | TTY | Braille animation, cursor control, erase line |
|
|
36
|
-
| `CaptureSpinnerHandle` | testkit | Records `ActivityEvent[]` for assertions |
|
|
37
|
-
|
|
38
|
-
Same pattern for `*ProgressHandle` (bar rendering, percentage, indeterminate pulse).
|
|
39
|
-
|
|
40
|
-
Active handle tracking: only one spinner/progress at a time per `OutputChannel`. Starting a new one
|
|
41
|
-
implicitly stops the previous. `stopActive()` public method for explicit cleanup.
|
|
42
|
-
|
|
43
|
-
All activity handle output (static and TTY) routes to **stderr** — stdout reserved for data.
|
|
44
|
-
|
|
45
|
-
## AMBIENT DECLARATIONS
|
|
46
|
-
|
|
47
|
-
`setInterval`/`clearInterval` declared as ambient functions in `activity.ts` (not from
|
|
48
|
-
`@types/node`) — zero-dep library targeting ES2022 without DOM or Node lib typings.
|
|
49
|
-
|
|
50
|
-
## TEST FILES (6)
|
|
51
|
-
|
|
52
|
-
| File | Tests | Focus |
|
|
53
|
-
| ---------------------------------- | ----: | ----------------------------------------------------- |
|
|
54
|
-
| `output.test.ts` | 49 | Core OutputChannel: log/warn/error, modes |
|
|
55
|
-
| `output-tty.test.ts` | 20 | TTY-specific rendering, color, formatting |
|
|
56
|
-
| `output-table.test.ts` | 16 | Table output in various modes |
|
|
57
|
-
| `output-spinner.test.ts` | 45 | Spinner handles: noop/static/TTY/capture, fake timers |
|
|
58
|
-
| `output-progress.test.ts` | 40 | Progress handles: noop/static/TTY/capture, fake timer |
|
|
59
|
-
| `output-activity-dispatch.test.ts` | 32 | OutputChannel wiring: mode dispatch, overlap, testkit |
|
|
60
|
-
|
|
61
|
-
## GOTCHAS
|
|
62
|
-
|
|
63
|
-
- Imports `schema/activity.ts` directly for activity types, `schema/command.ts` for `Out` — bypasses
|
|
64
|
-
barrel to avoid circular dep
|
|
65
|
-
- `writer.ts` is a leaf: `WriteFn` type + `writeLine` helper. Shared by `index.ts` and `activity.ts`
|
|
66
|
-
- Terminal escape sequences (`HIDE_CURSOR`, `ERASE_LINE`, etc.) are `@internal` constants in
|
|
67
|
-
`activity.ts`
|
|
68
|
-
- Spinner/progress tests use `vi.useFakeTimers()` inline with `try/finally`
|
|
69
|
-
- `ActivityEvent` has 10 variants (including `progress:increment` distinct from `progress:update`)
|
|
@@ -1,69 +0,0 @@
|
|
|
1
|
-
# resolve — Flag/arg value resolution chain
|
|
2
|
-
|
|
3
|
-
Single file: `index.ts` — largest in the codebase (~940 lines).
|
|
4
|
-
|
|
5
|
-
## RESOLUTION ORDER
|
|
6
|
-
|
|
7
|
-
```
|
|
8
|
-
CLI argv → environment variable → config file → interactive prompt → default value
|
|
9
|
-
```
|
|
10
|
-
|
|
11
|
-
Each source tried in order; first non-undefined wins. Missing required values with no source trigger
|
|
12
|
-
`ValidationError`.
|
|
13
|
-
|
|
14
|
-
## KEY FUNCTIONS
|
|
15
|
-
|
|
16
|
-
| Function | Role |
|
|
17
|
-
| --------------------- | ------------------------------------------------------------ |
|
|
18
|
-
| `resolve()` | Main entry — orchestrates full resolution for a command |
|
|
19
|
-
| `resolveFlags()` | All flags: CLI → env → config → prompt → default |
|
|
20
|
-
| `resolveArgs()` | All args: parsed → default → required validation |
|
|
21
|
-
| `coerceValue()` | Unified raw value → flag's declared kind (env/config/prompt) |
|
|
22
|
-
| `resolveConfigPath()` | Dotted path lookup in config object |
|
|
23
|
-
|
|
24
|
-
## TWO-PASS ARCHITECTURE
|
|
25
|
-
|
|
26
|
-
1. **Pass 1** (all flags): CLI → env → config. Collect partial values.
|
|
27
|
-
2. **Interactive resolver call**: If command has `.interactive()`, invoke with partial flags.
|
|
28
|
-
3. **Pass 2** (unresolved flags): prompt → default → required validation.
|
|
29
|
-
|
|
30
|
-
Without interactive resolver, single-pass (per-flag prompts used directly).
|
|
31
|
-
|
|
32
|
-
## COERCION PATTERN
|
|
33
|
-
|
|
34
|
-
Single unified `coerceValue()` function with a `CoerceSource` discriminated union
|
|
35
|
-
(`{ kind: 'env'; envVar } | { kind: 'config'; configPath } | { kind: 'prompt' }`) parameterizing
|
|
36
|
-
source-specific behavior: string leniency, boolean truthy/falsy sets ('y'/'n' for prompt), array
|
|
37
|
-
trim-on-split (prompt only), and error message templates.
|
|
38
|
-
|
|
39
|
-
Returns two-state `CoerceResult` (`{ ok: true; value } | { ok: false; error: ValidationError }`).
|
|
40
|
-
The prompt caller wraps this in a three-state `PromptResolveResult` at its own call site.
|
|
41
|
-
|
|
42
|
-
Helpers: `sourceLabel()` (error message fragment), `sourceDetails()` (error detail keys),
|
|
43
|
-
`coercionError()` (builds ValidationError with source context).
|
|
44
|
-
|
|
45
|
-
## ERROR AGGREGATION
|
|
46
|
-
|
|
47
|
-
`resolveFlags()` and `resolveArgs()` collect all errors into an array, then throw a single
|
|
48
|
-
aggregated `ValidationError` via `throwAggregatedErrors()`. Users see all validation messages at
|
|
49
|
-
once.
|
|
50
|
-
|
|
51
|
-
## TEST FILES (7, aspect-split)
|
|
52
|
-
|
|
53
|
-
| File | Tests |
|
|
54
|
-
| ----------------------------- | ------------------------------------------ |
|
|
55
|
-
| `resolve.test.ts` | Core resolution logic, precedence rules |
|
|
56
|
-
| `resolve-errors.test.ts` | Validation errors, missing required values |
|
|
57
|
-
| `resolve-env.test.ts` | Environment variable resolution + coercion |
|
|
58
|
-
| `resolve-config.test.ts` | Config file resolution + dotted paths |
|
|
59
|
-
| `resolve-prompt.test.ts` | Prompt-based resolution |
|
|
60
|
-
| `resolve-interactive.test.ts` | Two-pass interactive mode (full flow) |
|
|
61
|
-
| `resolve-integration.test.ts` | Cross-concern integration |
|
|
62
|
-
|
|
63
|
-
## GOTCHAS
|
|
64
|
-
|
|
65
|
-
- ~940 lines — reduced from ~1.1k by unifying three coercion functions into one
|
|
66
|
-
- `ResolveOptions` injects everything: env, config, prompter, answers — never touches `process`
|
|
67
|
-
directly
|
|
68
|
-
- Imports `schema/prompt.ts` directly (not through barrel) — circular dep avoidance
|
|
69
|
-
- `DeprecationWarning` structs collected during resolution for deprecated flag/arg usage
|
|
@@ -1,61 +0,0 @@
|
|
|
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
|
|
@@ -1,55 +0,0 @@
|
|
|
1
|
-
# testkit — In-process test harness (public API)
|
|
2
|
-
|
|
3
|
-
Not just test utilities — first-class module exported from the package. Testkit symbols are
|
|
4
|
-
re-exported from the `dreamcli/testkit` subpath (curating barrel at `src/testkit.ts`). This internal
|
|
5
|
-
`core/testkit/` module is unchanged.
|
|
6
|
-
|
|
7
|
-
## CORE API
|
|
8
|
-
|
|
9
|
-
**`runCommand(cmd, argv, options?): Promise<RunResult>`**
|
|
10
|
-
|
|
11
|
-
Complete execution pipeline in-process: argv → parse → resolve → middleware chain → action handler →
|
|
12
|
-
captured output. Calls `out.stopActive()` in `finally` to clean up leaked spinner/progress timers.
|
|
13
|
-
|
|
14
|
-
**`RunResult`** (defined in `schema/run.ts`, re-exported here):
|
|
15
|
-
`{ exitCode, stdout: string[], stderr: string[], activity: ActivityEvent[], error? }`
|
|
16
|
-
|
|
17
|
-
**`RunOptions`** — the injectable testing seam:
|
|
18
|
-
|
|
19
|
-
| Option | Purpose |
|
|
20
|
-
| ----------- | ------------------------------------------------- |
|
|
21
|
-
| `env` | `Record<string, string>` — replaces `process.env` |
|
|
22
|
-
| `config` | JSON config object |
|
|
23
|
-
| `answers` | `Record<string, TestAnswer>` — prompt responses |
|
|
24
|
-
| `prompter` | Full `PromptEngine` override |
|
|
25
|
-
| `verbosity` | `'normal' \| 'quiet'` |
|
|
26
|
-
| `jsonMode` | boolean — enable JSON output |
|
|
27
|
-
| `isTTY` | boolean — simulate TTY |
|
|
28
|
-
| `help` | `HelpOptions` — help formatting (width, binName) |
|
|
29
|
-
|
|
30
|
-
## TEST FILES (7)
|
|
31
|
-
|
|
32
|
-
| File | Tests |
|
|
33
|
-
| -------------------------------- | --------------------------------------------- |
|
|
34
|
-
| `testkit.test.ts` | Core `runCommand()` behavior |
|
|
35
|
-
| `testkit-json.test.ts` | JSON mode output |
|
|
36
|
-
| `testkit-tty.test.ts` | TTY detection + behavior |
|
|
37
|
-
| `testkit-prompt.test.ts` | Prompt resolution via answers |
|
|
38
|
-
| `testkit-nesting.test.ts` | Nested command dispatch via testkit |
|
|
39
|
-
| `output-e2e.test.ts` | Full pipeline: output modes x verbosity x CLI |
|
|
40
|
-
| `middleware-context-e2e.test.ts` | Middleware composition + context typing |
|
|
41
|
-
|
|
42
|
-
## ASSERTIONS
|
|
43
|
-
|
|
44
|
-
- Output arrays include trailing `\n` — assert `['Hello\n']` not `['Hello']`
|
|
45
|
-
- JSON output: `JSON.parse(result.stdout[0] ?? '')` then `toEqual`
|
|
46
|
-
- Error checking: `result.error?.code` for structured errors
|
|
47
|
-
- Activity events: `result.activity` array of `ActivityEvent` discriminated unions
|
|
48
|
-
- Type testing: `expectTypeOf(ctx).toEqualTypeOf<Readonly<...>>()` in middleware E2E
|
|
49
|
-
|
|
50
|
-
## GOTCHAS
|
|
51
|
-
|
|
52
|
-
- `mergedSchema` field on `RunOptions` is `@internal` — used by CLI dispatch layer only
|
|
53
|
-
- `CaptureOutputChannel` (from output/) wired here for output + activity capture
|
|
54
|
-
- `formatRootHelp()` (in `cli/root-help.ts`) re-exported as `@internal` for CLI-level help rendering
|
|
55
|
-
- Direct imports: `schema/command.ts`, `schema/flag.ts`, `schema/arg.ts` (not through barrel)
|
package/src/runtime/AGENTS.md
DELETED
|
@@ -1,74 +0,0 @@
|
|
|
1
|
-
# runtime — Platform abstraction layer
|
|
2
|
-
|
|
3
|
-
Multi-file module. Not truly independent of core — imports `WriteFn` from `core/output/` and
|
|
4
|
-
`ReadFn` from `core/prompt/`.
|
|
5
|
-
|
|
6
|
-
Runtime symbols re-exported from `dreamcli/runtime` subpath (`src/runtime.ts`): `RuntimeAdapter`,
|
|
7
|
-
adapter factories, `ExitError`, detection. `createTestAdapter`/`TestAdapterOptions` are testkit-only
|
|
8
|
-
(exported from `dreamcli/testkit`, not `dreamcli/runtime`).
|
|
9
|
-
|
|
10
|
-
## FILES
|
|
11
|
-
|
|
12
|
-
| File | Status | Lines | Purpose |
|
|
13
|
-
| -------------------- | ---------- | ----: | ------------------------------------------------------------------- |
|
|
14
|
-
| `adapter.ts` | **Active** | 120 | `RuntimeAdapter` interface — process/env/IO abstraction |
|
|
15
|
-
| `auto.ts` | **Active** | 64 | `createAdapter()` — auto-detecting adapter factory |
|
|
16
|
-
| `node.ts` | **Active** | 230 | `createNodeAdapter()` — Node.js implementation |
|
|
17
|
-
| `bun.ts` | **Active** | 20 | `createBunAdapter()` — delegates to Node adapter |
|
|
18
|
-
| `deno.ts` | **Active** | 318 | `createDenoAdapter()` — Deno namespace implementation |
|
|
19
|
-
| `detect.ts` | **Active** | 90 | `detectRuntime()` — Bun/Deno/Node feature detection |
|
|
20
|
-
| `node-builtins.d.ts` | Types | 45 | `@internal` — ambient decls for `node:readline`, `node:fs/promises` |
|
|
21
|
-
| `index.ts` | Barrel | 30 | Re-exports `RuntimeAdapter`, adapters, `ExitError` |
|
|
22
|
-
|
|
23
|
-
## `RuntimeAdapter` INTERFACE
|
|
24
|
-
|
|
25
|
-
```
|
|
26
|
-
argv: string[]
|
|
27
|
-
env: Record<string, string | undefined>
|
|
28
|
-
cwd: string
|
|
29
|
-
stdout: WriteFn
|
|
30
|
-
stderr: WriteFn
|
|
31
|
-
stdin: ReadFn
|
|
32
|
-
exit(code: number): never
|
|
33
|
-
isTTY: boolean
|
|
34
|
-
stdinIsTTY: boolean
|
|
35
|
-
homedir(): string
|
|
36
|
-
configDir(appName: string): string
|
|
37
|
-
readFile(path: string): Promise<string>
|
|
38
|
-
joinPath(...segments: string[]): string
|
|
39
|
-
```
|
|
40
|
-
|
|
41
|
-
## ADDING A NEW PLATFORM
|
|
42
|
-
|
|
43
|
-
1. Implement `RuntimeAdapter` in `{platform}.ts`
|
|
44
|
-
2. Add factory `create{Platform}Adapter()` to barrel
|
|
45
|
-
3. Add detection case in `detect.ts`
|
|
46
|
-
4. Wire auto-detection in `auto.ts`
|
|
47
|
-
5. Re-export from `src/runtime.ts`
|
|
48
|
-
|
|
49
|
-
## TEST FILES (5)
|
|
50
|
-
|
|
51
|
-
| File | Tests |
|
|
52
|
-
| ----------------- | --------------------------------------------------------- |
|
|
53
|
-
| `runtime.test.ts` | Node adapter, test adapter, `ExitError`, adapter contract |
|
|
54
|
-
| `detect.test.ts` | Runtime detection logic (globalThis feature probing) |
|
|
55
|
-
| `bun.test.ts` | Bun adapter delegation |
|
|
56
|
-
| `deno.test.ts` | Deno adapter (mock namespace, permission handling, stdin) |
|
|
57
|
-
| `auto.test.ts` | Auto-detecting adapter factory |
|
|
58
|
-
|
|
59
|
-
## GOTCHAS
|
|
60
|
-
|
|
61
|
-
- `globalThis as unknown as GlobalForDetect` in `detect.ts` — runtime boundary, justified cast
|
|
62
|
-
- `node.ts` has 7 `@internal` symbols: `NodeProcess`, `NodeSystemError`, `getNodeProcess`,
|
|
63
|
-
`isNodeSystemError`, `createNodeReadLine`, `resolveHomedir`, `resolveConfigDir`
|
|
64
|
-
- `createTestAdapter()` exported from `dreamcli/testkit` only, not `dreamcli/runtime`
|
|
65
|
-
- `ExitError` thrown by `adapter.exit()` — caught by CLI dispatch layer
|
|
66
|
-
- Empty-string env var fallbacks treated as unset in `node.ts`
|
|
67
|
-
- Win32 paths: `resolveConfigDir` strips trailing separator, `resolveHomedir` has
|
|
68
|
-
`HOMEDRIVE`+`HOMEPATH` fallback
|
|
69
|
-
- `deno.ts` has 7 `@internal` symbols: `DenoNamespace`, `isDenoErrorNamed`, `safeEnvToObject`,
|
|
70
|
-
`safeCwd`, `getDenoNamespace`, `readDenoStdinLine`, `resolveDenoHomedir`, `resolveDenoConfigDir`
|
|
71
|
-
- Deno.args pre-strips binary/script — adapter prepends synthetic `['deno', 'run']` for argv parity
|
|
72
|
-
- Permission-safe: env/cwd catch `PermissionDenied`, readFile returns null for both `NotFound` and
|
|
73
|
-
`PermissionDenied`
|
|
74
|
-
- Deno/web globals used by `deno.ts` come from `deno.jsonc` (`lib: ["deno.ns", "deno.shared_globals"]`)
|
|
@@ -1,40 +0,0 @@
|
|
|
1
|
-
/**
|
|
2
|
-
* Shared test helpers for runtime adapter tests.
|
|
3
|
-
*
|
|
4
|
-
* @internal — test-only, not exported from any public barrel.
|
|
5
|
-
* @module dreamcli/runtime/test-helpers
|
|
6
|
-
*/
|
|
7
|
-
|
|
8
|
-
import { vi } from 'vitest';
|
|
9
|
-
|
|
10
|
-
/**
|
|
11
|
-
* Create a minimal mock Deno namespace for adapter tests.
|
|
12
|
-
*
|
|
13
|
-
* Tests that exercise the Deno adapter path through `createAdapter()`
|
|
14
|
-
* can pass this namespace via the injected `globals` parameter instead
|
|
15
|
-
* of mutating `globalThis.Deno`.
|
|
16
|
-
*
|
|
17
|
-
* @returns A mock Deno namespace with stubbed I/O, env, and exit.
|
|
18
|
-
*/
|
|
19
|
-
export function createMockDenoNamespace() {
|
|
20
|
-
return {
|
|
21
|
-
build: { os: 'linux' as const },
|
|
22
|
-
args: [],
|
|
23
|
-
env: { get: () => undefined, toObject: () => ({}) },
|
|
24
|
-
cwd: () => '/deno/mock',
|
|
25
|
-
stdout: { writeSync: vi.fn(() => 0), isTerminal: () => false },
|
|
26
|
-
stderr: { writeSync: vi.fn(() => 0) },
|
|
27
|
-
stdin: {
|
|
28
|
-
isTerminal: () => false,
|
|
29
|
-
readable: {
|
|
30
|
-
getReader: () => ({
|
|
31
|
-
read: () => Promise.resolve({ done: true, value: undefined }),
|
|
32
|
-
releaseLock: () => {},
|
|
33
|
-
}),
|
|
34
|
-
},
|
|
35
|
-
},
|
|
36
|
-
exit: vi.fn() as unknown as (code: number) => never,
|
|
37
|
-
readTextFile: () => Promise.reject(Object.assign(new Error('not found'), { name: 'NotFound' })),
|
|
38
|
-
version: { deno: '2.6.0' },
|
|
39
|
-
};
|
|
40
|
-
}
|