@kjanat/dreamcli 4.0.0-rc.3 → 4.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (212) hide show
  1. package/README.md +5 -7
  2. package/dist/{runtime/adapter.d.mts → adapter-YM5QGi3M.d.mts} +4 -4
  3. package/dist/completion-CUMeOnAz.mjs +6 -0
  4. package/dist/completion.d.mts +90 -0
  5. package/dist/completion.mjs +1 -0
  6. package/dist/config-CrlScpYX.mjs +1 -0
  7. package/dist/config.d.mts +2 -0
  8. package/dist/config.mjs +1 -0
  9. package/dist/core-DvXUolc_.mjs +17 -0
  10. package/dist/{core/json-schema/index.d.mts → index-3l8uj16E.d.mts} +43 -34
  11. package/dist/{core/cli/index.d.mts → index-BAj2y70U.d.mts} +116 -57
  12. package/dist/index-BziI2aKc.d.mts +5440 -0
  13. package/dist/index-Cap0MA2V.d.mts +277 -0
  14. package/dist/index-Cp9kt2t-.d.mts +370 -0
  15. package/dist/index-DWsnGZlx.d.mts +831 -0
  16. package/dist/index.d.mts +190 -41
  17. package/dist/index.mjs +1 -26
  18. package/dist/json-schema-DRlrz_IV.mjs +52 -0
  19. package/dist/json-schema.d.mts +2 -0
  20. package/dist/json-schema.mjs +1 -0
  21. package/dist/package-json-BgE9YjjQ.mjs +3 -0
  22. package/dist/prompt.d.mts +48 -0
  23. package/dist/prompt.mjs +1 -0
  24. package/dist/rolldown-runtime-G4Kt5YOX.mjs +1 -0
  25. package/dist/runtime.d.mts +2 -6
  26. package/dist/runtime.mjs +1 -6
  27. package/dist/terminal-C8KTXjv5.mjs +6 -0
  28. package/dist/test-prompter-v__jT2yG.mjs +1 -0
  29. package/dist/testkit.d.mts +54 -6
  30. package/dist/testkit.mjs +1 -5
  31. package/dist/version.mjs +1 -7
  32. package/dreamcli.schema.json +697 -538
  33. package/package.json +29 -7
  34. package/skills/cli-creation/SKILL.md +16 -11
  35. package/CHANGELOG.md +0 -1116
  36. package/dist/core/cli/builtins.d.mts +0 -117
  37. package/dist/core/cli/builtins.mjs +0 -135
  38. package/dist/core/cli/compiled.d.mts +0 -66
  39. package/dist/core/cli/compiled.mjs +0 -76
  40. package/dist/core/cli/dispatch.d.mts +0 -115
  41. package/dist/core/cli/dispatch.mjs +0 -205
  42. package/dist/core/cli/help-links.d.mts +0 -27
  43. package/dist/core/cli/help-links.mjs +0 -41
  44. package/dist/core/cli/index.mjs +0 -1271
  45. package/dist/core/cli/planner.d.mts +0 -174
  46. package/dist/core/cli/planner.mjs +0 -323
  47. package/dist/core/cli/plugin.d.mts +0 -94
  48. package/dist/core/cli/plugin.mjs +0 -41
  49. package/dist/core/cli/propagate.d.mts +0 -39
  50. package/dist/core/cli/propagate.mjs +0 -57
  51. package/dist/core/cli/reserved-flags.d.mts +0 -19
  52. package/dist/core/cli/reserved-flags.mjs +0 -158
  53. package/dist/core/cli/root-help.d.mts +0 -53
  54. package/dist/core/cli/root-help.mjs +0 -221
  55. package/dist/core/cli/root-output-flags.d.mts +0 -74
  56. package/dist/core/cli/root-output-flags.mjs +0 -169
  57. package/dist/core/cli/root-surface.d.mts +0 -64
  58. package/dist/core/cli/root-surface.mjs +0 -28
  59. package/dist/core/cli/runtime-preflight.d.mts +0 -213
  60. package/dist/core/cli/runtime-preflight.mjs +0 -221
  61. package/dist/core/completion/index.d.mts +0 -76
  62. package/dist/core/completion/index.mjs +0 -90
  63. package/dist/core/completion/shells/bash.d.mts +0 -23
  64. package/dist/core/completion/shells/bash.mjs +0 -312
  65. package/dist/core/completion/shells/fish.d.mts +0 -19
  66. package/dist/core/completion/shells/fish.mjs +0 -164
  67. package/dist/core/completion/shells/powershell.d.mts +0 -13
  68. package/dist/core/completion/shells/powershell.mjs +0 -360
  69. package/dist/core/completion/shells/shared.d.mts +0 -164
  70. package/dist/core/completion/shells/shared.mjs +0 -147
  71. package/dist/core/completion/shells/zsh.d.mts +0 -23
  72. package/dist/core/completion/shells/zsh.mjs +0 -256
  73. package/dist/core/config/index.d.mts +0 -191
  74. package/dist/core/config/index.mjs +0 -285
  75. package/dist/core/config/package-json.d.mts +0 -179
  76. package/dist/core/config/package-json.mjs +0 -353
  77. package/dist/core/errors/index.d.mts +0 -125
  78. package/dist/core/errors/index.mjs +0 -87
  79. package/dist/core/execution/index.d.mts +0 -61
  80. package/dist/core/execution/index.mjs +0 -220
  81. package/dist/core/help/ansi.d.mts +0 -84
  82. package/dist/core/help/ansi.mjs +0 -121
  83. package/dist/core/help/index.d.mts +0 -149
  84. package/dist/core/help/index.mjs +0 -418
  85. package/dist/core/help/theme.d.mts +0 -86
  86. package/dist/core/help/theme.mjs +0 -69
  87. package/dist/core/json-schema/index.mjs +0 -1008
  88. package/dist/core/json-schema/meta-descriptions.generated.d.mts +0 -274
  89. package/dist/core/json-schema/meta-descriptions.generated.mjs +0 -136
  90. package/dist/core/output/activity.d.mts +0 -193
  91. package/dist/core/output/activity.mjs +0 -452
  92. package/dist/core/output/bind.d.mts +0 -37
  93. package/dist/core/output/bind.mjs +0 -56
  94. package/dist/core/output/contracts.d.mts +0 -82
  95. package/dist/core/output/contracts.mjs +0 -57
  96. package/dist/core/output/display-value.d.mts +0 -19
  97. package/dist/core/output/display-value.mjs +0 -32
  98. package/dist/core/output/index.d.mts +0 -344
  99. package/dist/core/output/index.mjs +0 -514
  100. package/dist/core/output/renderers.d.mts +0 -45
  101. package/dist/core/output/renderers.mjs +0 -46
  102. package/dist/core/output/writer.d.mts +0 -39
  103. package/dist/core/output/writer.mjs +0 -12
  104. package/dist/core/parse/index.d.mts +0 -178
  105. package/dist/core/parse/index.mjs +0 -850
  106. package/dist/core/parse/occurrences.d.mts +0 -90
  107. package/dist/core/parse/occurrences.mjs +0 -114
  108. package/dist/core/prompt/index.d.mts +0 -213
  109. package/dist/core/prompt/index.mjs +0 -348
  110. package/dist/core/read-flags/index.d.mts +0 -150
  111. package/dist/core/read-flags/index.mjs +0 -217
  112. package/dist/core/resolve/args.d.mts +0 -39
  113. package/dist/core/resolve/args.mjs +0 -182
  114. package/dist/core/resolve/coerce.d.mts +0 -79
  115. package/dist/core/resolve/coerce.mjs +0 -900
  116. package/dist/core/resolve/config.d.mts +0 -10
  117. package/dist/core/resolve/config.mjs +0 -19
  118. package/dist/core/resolve/contracts.d.mts +0 -146
  119. package/dist/core/resolve/errors.d.mts +0 -10
  120. package/dist/core/resolve/errors.mjs +0 -148
  121. package/dist/core/resolve/flags.d.mts +0 -74
  122. package/dist/core/resolve/flags.mjs +0 -246
  123. package/dist/core/resolve/index.d.mts +0 -44
  124. package/dist/core/resolve/index.mjs +0 -123
  125. package/dist/core/resolve/path-checks.d.mts +0 -48
  126. package/dist/core/resolve/path-checks.mjs +0 -102
  127. package/dist/core/resolve/redaction.d.mts +0 -13
  128. package/dist/core/resolve/redaction.mjs +0 -14
  129. package/dist/core/resolve/stages.d.mts +0 -86
  130. package/dist/core/resolve/stages.mjs +0 -170
  131. package/dist/core/resolve/standard.d.mts +0 -26
  132. package/dist/core/resolve/standard.mjs +0 -212
  133. package/dist/core/schema/activity.d.mts +0 -189
  134. package/dist/core/schema/arg.d.mts +0 -1461
  135. package/dist/core/schema/arg.mjs +0 -1139
  136. package/dist/core/schema/brand.d.mts +0 -17
  137. package/dist/core/schema/cardinality.d.mts +0 -302
  138. package/dist/core/schema/cardinality.mjs +0 -514
  139. package/dist/core/schema/command.d.mts +0 -1132
  140. package/dist/core/schema/command.mjs +0 -999
  141. package/dist/core/schema/flag.d.mts +0 -1495
  142. package/dist/core/schema/flag.mjs +0 -1207
  143. package/dist/core/schema/index.d.mts +0 -15
  144. package/dist/core/schema/index.mjs +0 -10
  145. package/dist/core/schema/middleware.d.mts +0 -129
  146. package/dist/core/schema/middleware.mjs +0 -41
  147. package/dist/core/schema/number-constraints.d.mts +0 -96
  148. package/dist/core/schema/number-constraints.mjs +0 -60
  149. package/dist/core/schema/prompt.d.mts +0 -135
  150. package/dist/core/schema/provenance.d.mts +0 -99
  151. package/dist/core/schema/provenance.mjs +0 -28
  152. package/dist/core/schema/run.d.mts +0 -211
  153. package/dist/core/schema/source.d.mts +0 -180
  154. package/dist/core/schema/source.mjs +0 -206
  155. package/dist/core/schema/standard.d.mts +0 -100
  156. package/dist/core/schema/standard.mjs +0 -15
  157. package/dist/core/schema/stdin.d.mts +0 -97
  158. package/dist/core/schema/stdin.mjs +0 -91
  159. package/dist/core/schema/string-constraints.d.mts +0 -108
  160. package/dist/core/schema/string-constraints.mjs +0 -86
  161. package/dist/core/schema/value-parsers.d.mts +0 -150
  162. package/dist/core/schema/value-parsers.mjs +0 -160
  163. package/dist/core/schema/value.d.mts +0 -243
  164. package/dist/core/schema/value.mjs +0 -573
  165. package/dist/core/testkit/index.d.mts +0 -63
  166. package/dist/core/testkit/index.mjs +0 -102
  167. package/dist/runtime/adapter.mjs +0 -92
  168. package/dist/runtime/auto.d.mts +0 -25
  169. package/dist/runtime/auto.mjs +0 -45
  170. package/dist/runtime/deno.d.mts +0 -99
  171. package/dist/runtime/deno.mjs +0 -265
  172. package/dist/runtime/detect.d.mts +0 -86
  173. package/dist/runtime/detect.mjs +0 -45
  174. package/dist/runtime/index.d.mts +0 -6
  175. package/dist/runtime/node.d.mts +0 -71
  176. package/dist/runtime/node.mjs +0 -228
  177. package/dist/runtime/paths.d.mts +0 -31
  178. package/dist/runtime/paths.mjs +0 -48
  179. package/dist/strings.d.mts +0 -27
  180. package/dist/strings.mjs +0 -22
  181. package/examples/basic.ts +0 -37
  182. package/examples/flag-types.ts +0 -79
  183. package/examples/gh/package.json +0 -45
  184. package/examples/gh/src/commands/auth.ts +0 -66
  185. package/examples/gh/src/commands/issue.ts +0 -120
  186. package/examples/gh/src/commands/pr.ts +0 -125
  187. package/examples/gh/src/data/issues.yaml +0 -5
  188. package/examples/gh/src/data/issues.yaml.d.ts +0 -17
  189. package/examples/gh/src/data/pull-requests.yaml +0 -7
  190. package/examples/gh/src/data/pull-requests.yaml.d.ts +0 -18
  191. package/examples/gh/src/docs.ts +0 -11
  192. package/examples/gh/src/lib/auth.ts +0 -37
  193. package/examples/gh/src/lib/utils.ts +0 -17
  194. package/examples/gh/src/main.test.ts +0 -307
  195. package/examples/gh/src/main.ts +0 -46
  196. package/examples/help-config.ts +0 -43
  197. package/examples/interactive.ts +0 -67
  198. package/examples/json-mode.ts +0 -95
  199. package/examples/middleware.ts +0 -71
  200. package/examples/multi-command.ts +0 -66
  201. package/examples/output-extras.ts +0 -46
  202. package/examples/parser-control.ts +0 -40
  203. package/examples/pwsh-demo/README.md +0 -40
  204. package/examples/pwsh-demo/package.json +0 -41
  205. package/examples/pwsh-demo/pwsh-demo.cmd +0 -3
  206. package/examples/pwsh-demo/smoke-powershell.ps1 +0 -218
  207. package/examples/pwsh-demo/src/main.test.ts +0 -45
  208. package/examples/pwsh-demo/src/main.ts +0 -140
  209. package/examples/spinner-progress.ts +0 -49
  210. package/examples/standard-schema.ts +0 -45
  211. package/examples/testing.ts +0 -147
  212. package/examples/transport-launcher.ts +0 -85
@@ -1,102 +0,0 @@
1
- import { requestsHelp } from "../parse/index.mjs";
2
- import { builtinEnabled } from "../cli/builtins.mjs";
3
- import { createCaptureOutput } from "../output/index.mjs";
4
- import { buildRunResult, executeCommand } from "../execution/index.mjs";
5
- import { readRootOutputFlags, resolveRootJsonMode, resolveRootVerbosity } from "../cli/root-output-flags.mjs";
6
- //#region src/core/testkit/index.ts
7
- /**
8
- * Run a command builder against the given argv with injected options.
9
- *
10
- * This is the testkit wrapper around the shared executor:
11
- * 1. Apply the CLI root-flag layer (detect/strip `--json` and `--quiet`/`-q`) so
12
- * copied real argv works
13
- * 2. Create or reuse capture output
14
- * 3. Build standalone schema/meta defaults when CLI dispatch did not
15
- * 4. Delegate parse -> resolve -> execute to the shared executor
16
- * 5. Return the structured result with captured buffers
17
- *
18
- * Errors are normalized by the shared executor into structured {@linkcode RunResult}s
19
- * with appropriate exit codes. The function never throws.
20
- *
21
- * @param cmd - The command builder (must have an action handler)
22
- * @param argv - Raw argv strings (NOT including the command name itself).
23
- * CLI-level `--json` and `--quiet`/`-q` before the `--` separator are honored
24
- * and stripped here, just like the real CLI root — so `['--json']` enables
25
- * JSON mode and `['--quiet']` sets quiet verbosity rather than failing as
26
- * unknown flags. Equivalent to `{ jsonMode: true }` / `{ verbosity: 'quiet' }`.
27
- * Both accept an explicit value (`--json=false`), and an invalid one fails
28
- * with the same `INVALID_VALUE` error the CLI root produces. Pass
29
- * `options.builtins` to mirror a CLI that released one of these tokens to its
30
- * commands.
31
- * @param options - Injectable runtime state
32
- * @returns Structured run result with exit code and captured output
33
- */
34
- async function runCommand(cmd, argv, options) {
35
- return runCommandInternal(cmd, argv, options);
36
- }
37
- /**
38
- * Execution body behind {@linkcode runCommand}, accepting the
39
- * framework-populated channel, capture, schema, and meta fields.
40
- *
41
- * @internal
42
- */
43
- async function runCommandInternal(cmd, argv, options) {
44
- const rootOutputFlags = readRootOutputFlags(argv, options?.builtins);
45
- const jsonMode = resolveRootJsonMode(rootOutputFlags, options?.jsonMode);
46
- const verbosity = resolveRootVerbosity(rootOutputFlags, options?.verbosity);
47
- const effectiveArgv = rootOutputFlags.argv;
48
- let out;
49
- let captured;
50
- if (options?.out !== void 0) {
51
- out = options.out;
52
- captured = options.captured ?? {
53
- stdout: [],
54
- stderr: [],
55
- activity: []
56
- };
57
- } else {
58
- const captureOptions = {
59
- ...verbosity !== void 0 ? { verbosity } : {},
60
- ...jsonMode ? { jsonMode } : {},
61
- ...options?.isTTY !== void 0 ? { isTTY: options.isTTY } : {}
62
- };
63
- [out, captured] = createCaptureOutput(Object.keys(captureOptions).length > 0 ? captureOptions : void 0);
64
- }
65
- if (rootOutputFlags.kind === "failed" && !(builtinEnabled(options?.builtins, "help") && requestsHelp(effectiveArgv))) {
66
- const { error } = rootOutputFlags;
67
- if (jsonMode) out.json({ error: error.toJSON() });
68
- else {
69
- out.error(error.message);
70
- if (error.suggest !== void 0) out.error(`Suggestion: ${error.suggest}`);
71
- }
72
- return buildRunResult({
73
- exitCode: error.exitCode,
74
- error
75
- }, captured);
76
- }
77
- const schema = options?.mergedSchema ?? cmd.schema;
78
- const meta = options?.meta ?? {
79
- name: schema.name,
80
- bin: options?.help?.binName ?? schema.name,
81
- version: void 0,
82
- command: schema.name
83
- };
84
- const effectiveOptions = options !== void 0 ? {
85
- ...options,
86
- ...jsonMode ? { jsonMode } : {}
87
- } : jsonMode ? { jsonMode } : void 0;
88
- const result = await executeCommand({
89
- command: {
90
- handler: cmd.handler,
91
- steps: cmd._executionSteps
92
- },
93
- argv: effectiveArgv,
94
- out,
95
- schema,
96
- meta,
97
- ...effectiveOptions !== void 0 ? { options: effectiveOptions } : {}
98
- });
99
- return buildRunResult(result, captured);
100
- }
101
- //#endregion
102
- export { runCommand, runCommandInternal };
@@ -1,92 +0,0 @@
1
- //#region src/runtime/adapter.ts
2
- /**
3
- * Error thrown by adapter implementations that model process exit as an
4
- * exception instead of terminating immediately.
5
- *
6
- * Runtime and CLI dispatch layers can catch this to perform real process
7
- * termination, while tests can assert on exit codes without killing the
8
- * runner:
9
- *
10
- * ```ts
11
- * try {
12
- * await cli.run({ adapter: createTestAdapter() });
13
- * } catch (e) {
14
- * if (e instanceof ExitError) expect(e.code).toBe(0);
15
- * }
16
- * ```
17
- */
18
- var ExitError = class extends Error {
19
- /** Error name — always `'ExitError'` for `instanceof` checks. */
20
- name = "ExitError";
21
- /** The exit code passed to `exit()`. */
22
- code;
23
- /** Create an ExitError for the given process exit code. */
24
- constructor(code) {
25
- super(`Process exited with code ${code}`);
26
- this.code = code;
27
- }
28
- };
29
- /** Noop writer — silently discards output. */
30
- const noopWrite = () => {};
31
- /** Noop reader — returns `null` (EOF) immediately. */
32
- const eofRead = () => Promise.resolve(null);
33
- /** Noop file reader — returns `null` (not found) for all paths. */
34
- const noopReadFile = () => Promise.resolve(null);
35
- /** Noop stat — reports `null` (nothing exists) for all paths. */
36
- const noopStat = () => Promise.resolve(null);
37
- /** Noop mkdir — resolves without creating anything. */
38
- const noopMkdir = () => Promise.resolve();
39
- /**
40
- * Create a test runtime adapter with injectable process state.
41
- *
42
- * Use this in `@kjanat/dreamcli/testkit` tests when you need to simulate argv,
43
- * environment variables, TTY state, stdin, or config-file reads without
44
- * touching the host process.
45
- *
46
- * @param options - Optional overrides for any adapter field.
47
- * @returns A {@linkcode RuntimeAdapter} suitable for test scenarios.
48
- *
49
- * @example
50
- * ```ts
51
- * const adapter = createTestAdapter({
52
- * argv: ['node', 'cli.js', 'deploy', '--force'],
53
- * env: { DEPLOY_REGION: 'us' },
54
- * });
55
- *
56
- * const result = await cli('mycli').run({ adapter });
57
- * ```
58
- */
59
- function createTestAdapter(options) {
60
- const stdinIsTTY = options?.stdinIsTTY ?? false;
61
- let stdinData = !stdinIsTTY ? options?.stdinData : void 0;
62
- return {
63
- argv: options?.argv ?? ["node", "test"],
64
- env: options?.env ?? {},
65
- cwd: options?.cwd ?? "/test",
66
- stdout: options?.stdout ?? noopWrite,
67
- stderr: options?.stderr ?? noopWrite,
68
- stdin: options?.stdin ?? eofRead,
69
- readStdin: () => {
70
- if (stdinData === void 0) return Promise.resolve(null);
71
- const result = stdinData;
72
- stdinData = void 0;
73
- return Promise.resolve(result);
74
- },
75
- isTTY: options?.isTTY ?? false,
76
- stdinIsTTY,
77
- getTerminalSize: () => options?.terminalSize,
78
- onTerminalResize: (listener) => options?.onTerminalResize?.(listener),
79
- exit: options?.exit ?? ((code) => {
80
- throw new ExitError(code);
81
- }),
82
- readFile: options?.readFile ?? noopReadFile,
83
- stat: options?.stat ?? noopStat,
84
- mkdir: options?.mkdir ?? noopMkdir,
85
- homedir: options?.homedir ?? "/home/test",
86
- configDir: options?.configDir ?? "/home/test/.config",
87
- userConfigDirs: options?.userConfigDirs ?? [options?.configDir ?? "/home/test/.config"],
88
- systemConfigDirs: options?.systemConfigDirs ?? []
89
- };
90
- }
91
- //#endregion
92
- export { ExitError, createTestAdapter };
@@ -1,25 +0,0 @@
1
- import { RuntimeAdapter } from "./adapter.mjs";
2
- import { GlobalForDetect } from "./detect.mjs";
3
- //#region src/runtime/auto.d.ts
4
- /**
5
- * Create a runtime adapter for the current environment.
6
- *
7
- * Detection order follows {@link detectRuntime}: Bun → Deno → Node → unknown.
8
- * Only Deno needs a distinct adapter; Bun, Node, and unknown runtimes all use
9
- * the Node adapter because they expose a Node-compatible `process` global.
10
- *
11
- * @param globals - Override `globalThis` for testing. Production callers
12
- * should omit this parameter.
13
- * @returns A {@linkcode RuntimeAdapter} for the detected runtime.
14
- *
15
- * @example
16
- * ```ts
17
- * import { cli } from '@kjanat/dreamcli';
18
- *
19
- * // Auto-detects Node/Bun/Deno and creates the right adapter
20
- * cli('mycli').run(); // uses createAdapter() internally
21
- * ```
22
- */
23
- declare function createAdapter(globals?: GlobalForDetect): RuntimeAdapter;
24
- //#endregion
25
- export { createAdapter };
@@ -1,45 +0,0 @@
1
- import { createDenoAdapter } from "./deno.mjs";
2
- import { detectRuntime } from "./detect.mjs";
3
- import { createNodeAdapter } from "./node.mjs";
4
- //#region src/runtime/auto.ts
5
- function isDenoNamespace(value) {
6
- if (typeof value !== "object" || value === null) return false;
7
- const candidate = value;
8
- return Array.isArray(candidate.args) && typeof candidate.cwd === "function" && typeof candidate.exit === "function" && typeof candidate.readTextFile === "function" && typeof candidate.env?.get === "function" && typeof candidate.env.toObject === "function" && typeof candidate.stdout?.writeSync === "function" && typeof candidate.stdout.isTerminal === "function" && typeof candidate.stderr?.writeSync === "function" && typeof candidate.stdin?.isTerminal === "function" && typeof candidate.stdin?.readable?.getReader === "function";
9
- }
10
- function getInjectedDenoNamespace(globals) {
11
- const candidate = globals.Deno;
12
- return isDenoNamespace(candidate) ? candidate : void 0;
13
- }
14
- /**
15
- * Create a runtime adapter for the current environment.
16
- *
17
- * Detection order follows {@link detectRuntime}: Bun → Deno → Node → unknown.
18
- * Only Deno needs a distinct adapter; Bun, Node, and unknown runtimes all use
19
- * the Node adapter because they expose a Node-compatible `process` global.
20
- *
21
- * @param globals - Override `globalThis` for testing. Production callers
22
- * should omit this parameter.
23
- * @returns A {@linkcode RuntimeAdapter} for the detected runtime.
24
- *
25
- * @example
26
- * ```ts
27
- * import { cli } from '@kjanat/dreamcli';
28
- *
29
- * // Auto-detects Node/Bun/Deno and creates the right adapter
30
- * cli('mycli').run(); // uses createAdapter() internally
31
- * ```
32
- */
33
- function createAdapter(globals) {
34
- const runtimeGlobals = globals ?? globalThis;
35
- const runtime = detectRuntime(runtimeGlobals);
36
- switch (runtime) {
37
- case "deno": return createDenoAdapter(getInjectedDenoNamespace(runtimeGlobals));
38
- case "bun":
39
- case "node":
40
- case "unknown": return createNodeAdapter();
41
- default: return runtime;
42
- }
43
- }
44
- //#endregion
45
- export { createAdapter };
@@ -1,99 +0,0 @@
1
- import { RuntimeAdapter } from "./adapter.mjs";
2
- //#region src/runtime/deno.d.ts
3
- /**
4
- * Minimal subset of the Deno namespace needed by the adapter.
5
- *
6
- * We avoid `@types/deno` to keep the core runtime-agnostic at the type level.
7
- * This interface declares only what `createDenoAdapter` actually reads.
8
- *
9
- * The `env` property is optional because it requires `--allow-env` permission.
10
- * When permission is denied, the adapter catches the error and falls back to
11
- * an empty env object.
12
- */
13
- interface DenoNamespace {
14
- /** Build target metadata (OS detection). */
15
- readonly build: {
16
- readonly os: 'darwin' | 'linux' | 'android' | 'windows' | 'freebsd' | 'netbsd' | 'aix' | 'solaris' | 'illumos';
17
- };
18
- /** Deno version info — used for minimum-version guard. */
19
- readonly version?: {
20
- readonly deno?: string;
21
- };
22
- /** Raw command-line args (excludes the binary/script — Deno pre-strips them). */
23
- readonly args: readonly string[];
24
- /** Environment variable access (requires `--allow-env`). */
25
- readonly env: {
26
- /** Get a single env var. Returns `undefined` if unset or permission denied. */
27
- get(key: string): string | undefined;
28
- /** Get all env vars as a plain object. Throws on permission denied. */
29
- toObject(): Record<string, string>;
30
- };
31
- /** Current working directory (may throw if `--allow-read` is denied for cwd). */
32
- cwd(): string;
33
- /** Standard output — synchronous byte writer with TTY detection. */
34
- readonly stdout: {
35
- /** Write raw bytes to stdout synchronously. */
36
- writeSync(p: Uint8Array): number;
37
- /** Whether stdout is connected to a TTY. */
38
- isTerminal(): boolean;
39
- };
40
- /** Current console dimensions. */
41
- consoleSize?(): {
42
- readonly columns: number;
43
- readonly rows: number;
44
- };
45
- /** Register a native signal listener. */
46
- addSignalListener?(signal: 'SIGWINCH', listener: () => void): void;
47
- /** Remove a native signal listener. */
48
- removeSignalListener?(signal: 'SIGWINCH', listener: () => void): void;
49
- /** Standard error — synchronous byte writer. */
50
- readonly stderr: {
51
- /** Write raw bytes to stderr synchronously. */
52
- writeSync(p: Uint8Array): number;
53
- };
54
- /** Standard input — TTY detection and readable byte stream. */
55
- readonly stdin: {
56
- /** Whether stdin is connected to a TTY. */
57
- isTerminal(): boolean;
58
- /** Readable stream for stdin bytes. */
59
- readonly readable: ReadableStream<Uint8Array>;
60
- };
61
- /** Exit the process with the given code. */
62
- exit(code: number): never;
63
- /** Read a file as UTF-8 text (requires `--allow-read`). */
64
- readTextFile(path: string): Promise<string>;
65
- /** Probe a filesystem path (requires `--allow-read`). */
66
- stat(path: string): Promise<{
67
- readonly isDirectory: boolean;
68
- }>;
69
- /** Create a directory (requires `--allow-write`). */
70
- mkdir(path: string, options?: {
71
- readonly recursive?: boolean;
72
- }): Promise<void>;
73
- }
74
- /**
75
- * Create a runtime adapter backed by the Deno namespace.
76
- *
77
- * Reads `Deno.args`, `Deno.env`, `Deno.cwd()`, and wraps Deno's stream-based
78
- * I/O into the {@linkcode WriteFn}/{@linkcode ReadFn} functions expected by the framework.
79
- *
80
- * Unlike Node/Bun, Deno strips the binary and script path from `Deno.args`.
81
- * The adapter prepends synthetic entries (`['deno', 'run']`) so the argv
82
- * shape matches the {@linkcode RuntimeAdapter} contract (binary + script + user args).
83
- *
84
- * @param ns - Override the Deno namespace (useful for testing the adapter itself).
85
- * @returns A {@linkcode RuntimeAdapter} backed by Deno's namespace APIs.
86
- *
87
- * @example
88
- * ```ts
89
- * import { cli } from '@kjanat/dreamcli';
90
- * import { createDenoAdapter } from '@kjanat/dreamcli/runtime';
91
- *
92
- * cli('mycli')
93
- * .command(deploy)
94
- * .run({ adapter: createDenoAdapter() });
95
- * ```
96
- */
97
- declare function createDenoAdapter(ns?: DenoNamespace): RuntimeAdapter;
98
- //#endregion
99
- export { type DenoNamespace, createDenoAdapter };
@@ -1,265 +0,0 @@
1
- import { resolveConfigDirectory, resolveHomeDirectory } from "./paths.mjs";
2
- //#region src/runtime/deno.ts
3
- /**
4
- * Detect whether an unknown thrown value is a Deno error by name.
5
- *
6
- * @internal
7
- */
8
- function isDenoErrorNamed(err, name) {
9
- if (typeof err !== "object" || err === null || !("name" in err)) return false;
10
- const candidate = err;
11
- return typeof candidate.name === "string" && candidate.name === name;
12
- }
13
- /**
14
- * Safely read all environment variables. Returns empty object if
15
- * `--allow-env` permission is not granted.
16
- *
17
- * @internal
18
- */
19
- function safeEnvToObject(deno) {
20
- try {
21
- return deno.env.toObject();
22
- } catch (err) {
23
- if (isDenoErrorNamed(err, "PermissionDenied")) return {};
24
- throw err;
25
- }
26
- }
27
- /**
28
- * Safely get the current working directory. Returns `/` if the cwd is
29
- * inaccessible due to missing permissions.
30
- *
31
- * @internal
32
- */
33
- function safeCwd(deno) {
34
- try {
35
- return deno.cwd();
36
- } catch (err) {
37
- if (isDenoErrorNamed(err, "PermissionDenied")) return "/";
38
- throw err;
39
- }
40
- }
41
- /**
42
- * Create a runtime adapter backed by the Deno namespace.
43
- *
44
- * Reads `Deno.args`, `Deno.env`, `Deno.cwd()`, and wraps Deno's stream-based
45
- * I/O into the {@linkcode WriteFn}/{@linkcode ReadFn} functions expected by the framework.
46
- *
47
- * Unlike Node/Bun, Deno strips the binary and script path from `Deno.args`.
48
- * The adapter prepends synthetic entries (`['deno', 'run']`) so the argv
49
- * shape matches the {@linkcode RuntimeAdapter} contract (binary + script + user args).
50
- *
51
- * @param ns - Override the Deno namespace (useful for testing the adapter itself).
52
- * @returns A {@linkcode RuntimeAdapter} backed by Deno's namespace APIs.
53
- *
54
- * @example
55
- * ```ts
56
- * import { cli } from '@kjanat/dreamcli';
57
- * import { createDenoAdapter } from '@kjanat/dreamcli/runtime';
58
- *
59
- * cli('mycli')
60
- * .command(deploy)
61
- * .run({ adapter: createDenoAdapter() });
62
- * ```
63
- */
64
- function createDenoAdapter(ns) {
65
- const d = ns ?? getDenoNamespace();
66
- const encoder = new TextEncoder();
67
- const argv = [
68
- "deno",
69
- "run",
70
- ...d.args
71
- ];
72
- const env = safeEnvToObject(d);
73
- const cwd = safeCwd(d);
74
- const stdoutWrite = (data) => {
75
- d.stdout.writeSync(encoder.encode(data));
76
- };
77
- const stderrWrite = (data) => {
78
- d.stderr.writeSync(encoder.encode(data));
79
- };
80
- const stdinRead = createDenoReadLine(d);
81
- const readFile = async (path) => {
82
- try {
83
- return await d.readTextFile(path);
84
- } catch (err) {
85
- if (isDenoErrorNamed(err, "NotFound")) return null;
86
- if (isDenoErrorNamed(err, "PermissionDenied")) return null;
87
- throw err;
88
- }
89
- };
90
- const stat = async (path) => {
91
- try {
92
- return (await d.stat(path)).isDirectory ? "directory" : "file";
93
- } catch (err) {
94
- if (isDenoErrorNamed(err, "NotFound")) return null;
95
- throw err;
96
- }
97
- };
98
- const homedir = resolveDenoHomedir(env, d.build.os === "windows");
99
- const configDir = resolveDenoConfigDir(env, homedir, d.build.os === "windows");
100
- const stdinIsTTY = d.stdin.isTerminal();
101
- return {
102
- argv,
103
- env,
104
- cwd,
105
- stdout: stdoutWrite,
106
- stderr: stderrWrite,
107
- stdin: stdinRead,
108
- readStdin: () => readDenoStdinAll(d, stdinIsTTY),
109
- isTTY: d.stdout.isTerminal(),
110
- stdinIsTTY,
111
- getTerminalSize: () => readDenoTerminalSize(d),
112
- onTerminalResize: (listener) => onDenoTerminalResize(d, listener),
113
- exit: (code) => d.exit(code),
114
- readFile,
115
- stat,
116
- mkdir: (path) => d.mkdir(path, { recursive: true }),
117
- homedir,
118
- configDir,
119
- userConfigDirs: d.build.os === "darwin" ? [configDir, `${homedir}/Library/Application Support`] : [configDir],
120
- systemConfigDirs: d.build.os === "windows" ? [] : ["/etc"]
121
- };
122
- }
123
- /** Normalize terminal dimensions and discard unusable values. @internal */
124
- function normalizeTerminalSize(columns, rows) {
125
- if (columns === void 0 || rows === void 0) return void 0;
126
- if (!Number.isFinite(columns) || !Number.isFinite(rows)) return void 0;
127
- if (columns <= 0 || rows <= 0) return void 0;
128
- return {
129
- columns,
130
- rows
131
- };
132
- }
133
- /** Read native Deno terminal dimensions. @internal */
134
- function readDenoTerminalSize(deno) {
135
- if (!deno.stdout.isTerminal() || deno.consoleSize === void 0) return void 0;
136
- try {
137
- const size = deno.consoleSize();
138
- return normalizeTerminalSize(size.columns, size.rows);
139
- } catch {
140
- return;
141
- }
142
- }
143
- /** Subscribe to native Deno resize signals where SIGWINCH exists. @internal */
144
- function onDenoTerminalResize(deno, listener) {
145
- if (!deno.stdout.isTerminal()) return void 0;
146
- if (deno.build.os === "windows") return void 0;
147
- if (deno.addSignalListener === void 0 || deno.removeSignalListener === void 0) return;
148
- try {
149
- deno.addSignalListener("SIGWINCH", listener);
150
- } catch {
151
- return;
152
- }
153
- return () => {
154
- deno.removeSignalListener?.("SIGWINCH", listener);
155
- };
156
- }
157
- /**
158
- * Access the global `Deno` namespace.
159
- *
160
- * Cast through `unknown` to avoid TypeScript errors when Deno types
161
- * aren't installed. Safe because this adapter is only used on Deno
162
- * where `globalThis.Deno` is always defined.
163
- *
164
- * @internal
165
- */
166
- function getDenoNamespace() {
167
- return globalThis.Deno;
168
- }
169
- /**
170
- * Read all of stdin as a single string (for piped data).
171
- *
172
- * Returns `null` immediately if stdin is a TTY — the user is typing
173
- * interactively, so there's no piped data to consume. When stdin is
174
- * piped, collects all chunks via the `ReadableStream` until EOF and
175
- * returns the decoded string, which may be empty for an empty pipe.
176
- *
177
- * @internal
178
- */
179
- async function readDenoStdinAll(deno, stdinIsTTY) {
180
- if (stdinIsTTY) return null;
181
- const reader = deno.stdin.readable.getReader();
182
- const decoder = new TextDecoder();
183
- const chunks = [];
184
- try {
185
- for (;;) {
186
- const { value, done } = await reader.read();
187
- if (done) {
188
- chunks.push(decoder.decode());
189
- break;
190
- }
191
- chunks.push(decoder.decode(value, { stream: true }));
192
- }
193
- } finally {
194
- reader.releaseLock();
195
- }
196
- return chunks.join("");
197
- }
198
- /**
199
- * Read a single line from Deno's stdin.
200
- *
201
- * Uses the `ReadableStream` API with a manual buffer to read until
202
- * a newline character is found. Returns `null` on EOF.
203
- *
204
- * This is intentionally simple — the terminal prompter handles retries
205
- * and validation.
206
- *
207
- * @internal
208
- */
209
- function createDenoReadLine(deno) {
210
- const decoder = new TextDecoder();
211
- let buffer = "";
212
- let done = false;
213
- return async () => {
214
- const reader = deno.stdin.readable.getReader();
215
- try {
216
- for (;;) {
217
- const newlineIndex = buffer.indexOf("\n");
218
- if (newlineIndex !== -1) {
219
- const line = buffer.slice(0, newlineIndex).replace(/\r$/, "");
220
- buffer = buffer.slice(newlineIndex + 1);
221
- return line;
222
- }
223
- if (done) {
224
- if (buffer.length === 0) return null;
225
- const line = buffer;
226
- buffer = "";
227
- return line;
228
- }
229
- const { value, done: readDone } = await reader.read();
230
- if (readDone) {
231
- buffer += decoder.decode();
232
- done = true;
233
- continue;
234
- }
235
- buffer += decoder.decode(value, { stream: true });
236
- }
237
- } finally {
238
- reader.releaseLock();
239
- }
240
- };
241
- }
242
- /**
243
- * Resolve the user's home directory from environment variables.
244
- *
245
- * Deno doesn't expose `os.homedir()` without `--allow-sys`, so we derive
246
- * it from env vars — same approach as the Node adapter.
247
- *
248
- * @internal
249
- */
250
- function resolveDenoHomedir(env, isWindows) {
251
- return resolveHomeDirectory(env, isWindows);
252
- }
253
- /**
254
- * Resolve the platform-specific user configuration directory.
255
- *
256
- * Uses `Deno.build.os` for platform detection, then applies the same fallback
257
- * chain as the Node adapter.
258
- *
259
- * @internal
260
- */
261
- function resolveDenoConfigDir(env, homedir, isWindows) {
262
- return resolveConfigDirectory(env, isWindows, homedir);
263
- }
264
- //#endregion
265
- export { createDenoAdapter };