@kjanat/dreamcli 1.0.0 → 2.0.1

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 (217) hide show
  1. package/CHANGELOG.md +63 -6
  2. package/LICENSE +1 -1
  3. package/README.md +296 -164
  4. package/dist/core/cli/dispatch.d.mts +85 -0
  5. package/dist/core/cli/dispatch.mjs +1 -0
  6. package/dist/core/cli/index.d.mts +418 -0
  7. package/dist/core/cli/index.mjs +1 -0
  8. package/dist/core/cli/planner.d.mts +143 -0
  9. package/dist/core/cli/planner.mjs +1 -0
  10. package/dist/core/cli/plugin.d.mts +94 -0
  11. package/dist/core/cli/plugin.mjs +1 -0
  12. package/dist/core/cli/propagate.d.mts +39 -0
  13. package/dist/core/cli/propagate.mjs +1 -0
  14. package/dist/core/cli/root-help.d.mts +28 -0
  15. package/dist/core/cli/root-help.mjs +7 -0
  16. package/dist/core/cli/root-surface.d.mts +42 -0
  17. package/dist/core/cli/root-surface.mjs +1 -0
  18. package/dist/core/cli/runtime-preflight.d.mts +149 -0
  19. package/dist/core/cli/runtime-preflight.mjs +1 -0
  20. package/dist/core/completion/index.d.mts +46 -0
  21. package/dist/core/completion/index.mjs +1 -0
  22. package/dist/core/completion/shells/bash.d.mts +24 -0
  23. package/dist/core/completion/shells/bash.mjs +3 -0
  24. package/dist/core/completion/shells/fish.d.mts +20 -0
  25. package/dist/core/completion/shells/fish.mjs +2 -0
  26. package/dist/core/completion/shells/powershell.d.mts +14 -0
  27. package/dist/core/completion/shells/powershell.mjs +2 -0
  28. package/dist/core/completion/shells/shared.d.mts +139 -0
  29. package/dist/core/completion/shells/shared.mjs +1 -0
  30. package/dist/core/completion/shells/zsh.d.mts +24 -0
  31. package/dist/core/completion/shells/zsh.mjs +2 -0
  32. package/dist/core/config/index.d.mts +161 -0
  33. package/dist/core/config/index.mjs +1 -0
  34. package/dist/core/config/package-json.d.mts +68 -0
  35. package/dist/core/config/package-json.mjs +1 -0
  36. package/dist/core/errors/index.d.mts +126 -0
  37. package/dist/core/errors/index.mjs +1 -0
  38. package/dist/core/execution/index.d.mts +49 -0
  39. package/dist/core/execution/index.mjs +1 -0
  40. package/dist/core/help/index.d.mts +49 -0
  41. package/dist/core/help/index.mjs +8 -0
  42. package/dist/core/json-schema/index.d.mts +109 -0
  43. package/dist/core/json-schema/index.mjs +55 -0
  44. package/dist/core/json-schema/meta-descriptions.generated.d.mts +185 -0
  45. package/dist/core/json-schema/meta-descriptions.generated.mjs +28 -0
  46. package/dist/core/output/activity.d.mts +194 -0
  47. package/dist/core/output/activity.mjs +1 -0
  48. package/dist/core/output/contracts.d.mts +88 -0
  49. package/dist/core/output/contracts.mjs +1 -0
  50. package/dist/core/output/display-value.d.mts +19 -0
  51. package/dist/core/output/display-value.mjs +1 -0
  52. package/dist/core/output/index.d.mts +280 -0
  53. package/dist/core/output/index.mjs +2 -0
  54. package/dist/core/output/renderers.d.mts +46 -0
  55. package/dist/core/output/renderers.mjs +1 -0
  56. package/dist/core/output/writer.d.mts +40 -0
  57. package/dist/core/output/writer.mjs +1 -0
  58. package/dist/core/parse/index.d.mts +79 -0
  59. package/dist/core/parse/index.mjs +1 -0
  60. package/dist/core/prompt/index.d.mts +205 -0
  61. package/dist/core/prompt/index.mjs +6 -0
  62. package/dist/core/resolve/args.d.mts +8 -0
  63. package/dist/core/resolve/args.mjs +1 -0
  64. package/dist/core/resolve/coerce.d.mts +22 -0
  65. package/dist/core/resolve/coerce.mjs +1 -0
  66. package/dist/core/resolve/config.d.mts +10 -0
  67. package/dist/core/resolve/config.mjs +1 -0
  68. package/dist/core/resolve/contracts.d.mts +112 -0
  69. package/dist/core/resolve/errors.d.mts +11 -0
  70. package/dist/core/resolve/errors.mjs +2 -0
  71. package/dist/core/resolve/flags.d.mts +10 -0
  72. package/dist/core/resolve/flags.mjs +1 -0
  73. package/dist/core/resolve/index.d.mts +42 -0
  74. package/dist/core/resolve/index.mjs +1 -0
  75. package/dist/core/resolve/property.d.mts +47 -0
  76. package/dist/core/resolve/property.mjs +1 -0
  77. package/dist/core/schema/activity.d.mts +169 -0
  78. package/dist/core/schema/arg.d.mts +559 -0
  79. package/dist/core/schema/arg.mjs +1 -0
  80. package/dist/core/schema/command.d.mts +960 -0
  81. package/dist/core/schema/command.mjs +1 -0
  82. package/dist/core/schema/flag.d.mts +491 -0
  83. package/dist/core/schema/flag.mjs +1 -0
  84. package/dist/core/schema/index.d.mts +8 -0
  85. package/dist/core/schema/middleware.d.mts +122 -0
  86. package/dist/core/schema/middleware.mjs +1 -0
  87. package/dist/core/schema/prompt.d.mts +117 -0
  88. package/dist/core/schema/run.d.mts +171 -0
  89. package/dist/core/schema-dsl/runtime.d.mts +144 -0
  90. package/dist/core/schema-dsl/runtime.mjs +2 -0
  91. package/dist/core/schema-dsl/to-json-schema.d.mts +30 -0
  92. package/dist/core/schema-dsl/to-json-schema.mjs +1 -0
  93. package/dist/core/testkit/index.d.mts +54 -0
  94. package/dist/core/testkit/index.mjs +1 -0
  95. package/dist/index.d.mts +28 -920
  96. package/dist/index.mjs +1 -10
  97. package/dist/runtime/adapter.d.mts +212 -0
  98. package/dist/{adapter-B37d9oia.mjs → runtime/adapter.mjs} +1 -1
  99. package/dist/runtime/auto.d.mts +26 -0
  100. package/dist/runtime/auto.mjs +1 -0
  101. package/dist/runtime/bun.d.mts +28 -0
  102. package/dist/runtime/bun.mjs +1 -0
  103. package/dist/runtime/deno.d.mts +76 -0
  104. package/dist/runtime/deno.mjs +2 -0
  105. package/dist/runtime/detect.d.mts +86 -0
  106. package/dist/runtime/detect.mjs +1 -0
  107. package/dist/runtime/index.d.mts +7 -0
  108. package/dist/runtime/node.d.mts +65 -0
  109. package/dist/runtime/node.mjs +2 -0
  110. package/dist/runtime/paths.d.mts +31 -0
  111. package/dist/runtime/paths.mjs +1 -0
  112. package/dist/runtime/support.d.mts +42 -0
  113. package/dist/runtime/support.mjs +1 -0
  114. package/dist/runtime.d.mts +6 -252
  115. package/dist/runtime.mjs +1 -1
  116. package/dist/testkit.d.mts +5 -24
  117. package/dist/testkit.mjs +1 -1
  118. package/dist/version.d.mts +16 -0
  119. package/dist/version.mjs +1 -0
  120. package/dreamcli.schema.json +338 -0
  121. package/examples/basic.ts +2 -2
  122. package/examples/gh/package.json +7 -11
  123. package/examples/gh/src/commands/auth.ts +2 -2
  124. package/examples/gh/src/commands/issue.ts +4 -4
  125. package/examples/gh/src/commands/pr.ts +4 -4
  126. package/examples/gh/src/docs.ts +11 -0
  127. package/examples/gh/src/lib/auth.ts +1 -1
  128. package/examples/gh/src/main.test.ts +6 -5
  129. package/examples/gh/src/main.ts +8 -6
  130. package/examples/interactive.ts +3 -3
  131. package/examples/json-mode.ts +4 -6
  132. package/examples/middleware.ts +3 -3
  133. package/examples/multi-command.ts +3 -3
  134. package/examples/spinner-progress.ts +5 -5
  135. package/examples/testing.ts +8 -6
  136. package/package.json +70 -44
  137. package/src/core/cli/dispatch.ts +4 -0
  138. package/src/core/cli/index.ts +185 -632
  139. package/src/core/cli/planner.ts +413 -0
  140. package/src/core/cli/plugin.ts +7 -1
  141. package/src/core/cli/propagate.ts +1 -1
  142. package/src/core/cli/runtime-preflight.ts +409 -0
  143. package/src/core/completion/index.ts +15 -9
  144. package/src/core/completion/shells/bash.ts +6 -3
  145. package/src/core/completion/shells/fish.ts +245 -10
  146. package/src/core/completion/shells/powershell.ts +390 -9
  147. package/src/core/completion/shells/shared.ts +4 -4
  148. package/src/core/completion/shells/zsh.ts +12 -7
  149. package/src/core/config/index.ts +7 -4
  150. package/src/core/config/package-json.ts +6 -2
  151. package/src/core/errors/index.ts +23 -8
  152. package/src/core/execution/index.ts +270 -0
  153. package/src/core/help/index.ts +13 -15
  154. package/src/core/json-schema/index.ts +193 -7
  155. package/src/core/json-schema/meta-descriptions.generated.ts +202 -0
  156. package/src/core/output/contracts.ts +194 -0
  157. package/src/core/output/index.ts +47 -82
  158. package/src/core/output/renderers.ts +125 -0
  159. package/src/core/parse/index.ts +39 -21
  160. package/src/core/prompt/index.ts +44 -27
  161. package/src/core/resolve/args.ts +144 -0
  162. package/src/core/resolve/coerce.ts +432 -0
  163. package/src/core/resolve/config.ts +26 -0
  164. package/src/core/resolve/contracts.ts +135 -0
  165. package/src/core/resolve/errors.ts +227 -0
  166. package/src/core/resolve/flags.ts +205 -0
  167. package/src/core/resolve/index.ts +41 -1264
  168. package/src/core/resolve/property.ts +99 -0
  169. package/src/core/schema/activity.ts +3 -0
  170. package/src/core/schema/arg.ts +26 -14
  171. package/src/core/schema/command.ts +265 -38
  172. package/src/core/schema/flag.ts +120 -15
  173. package/src/core/schema/index.ts +11 -2
  174. package/src/core/schema/middleware.ts +6 -6
  175. package/src/core/schema/prompt.ts +9 -1
  176. package/src/core/schema/run.ts +25 -17
  177. package/src/core/schema-dsl/index.ts +109 -0
  178. package/src/core/schema-dsl/parse.ts +262 -0
  179. package/src/core/schema-dsl/runtime.ts +609 -0
  180. package/src/core/schema-dsl/to-json-schema.ts +102 -0
  181. package/src/core/testkit/index.ts +55 -297
  182. package/src/index.ts +10 -4
  183. package/src/runtime/adapter.ts +13 -10
  184. package/src/runtime/auto.ts +3 -3
  185. package/src/runtime/bun.ts +4 -4
  186. package/src/runtime/deno.ts +43 -29
  187. package/src/runtime/detect.ts +4 -1
  188. package/src/runtime/index.ts +1 -1
  189. package/src/runtime/node.ts +43 -21
  190. package/src/runtime/paths.ts +9 -3
  191. package/src/runtime/support.ts +20 -4
  192. package/src/runtime.ts +1 -1
  193. package/src/testkit.ts +10 -8
  194. package/dist/adapter-CCSh5juX.cjs +0 -1
  195. package/dist/adapter-DIwO-q7K.d.mts +0 -3447
  196. package/dist/adapter-DQnxxLiE.d.cts +0 -3447
  197. package/dist/auto-5cjZaF9V.mjs +0 -3
  198. package/dist/auto-B0eSgoDw.cjs +0 -3
  199. package/dist/index.cjs +0 -10
  200. package/dist/index.d.cts +0 -920
  201. package/dist/runtime.cjs +0 -1
  202. package/dist/runtime.d.cts +0 -253
  203. package/dist/testkit-CEDYPvhF.mjs +0 -14
  204. package/dist/testkit-ClIKijxC.cjs +0 -14
  205. package/dist/testkit.cjs +0 -1
  206. package/dist/testkit.d.cts +0 -25
  207. package/examples/gh/tsconfig.json +0 -37
  208. package/examples/tsconfig.json +0 -17
  209. package/src/core/cli/AGENTS.md +0 -72
  210. package/src/core/completion/AGENTS.md +0 -72
  211. package/src/core/completion/completion-test-helpers.ts +0 -48
  212. package/src/core/output/AGENTS.md +0 -69
  213. package/src/core/resolve/AGENTS.md +0 -69
  214. package/src/core/schema/AGENTS.md +0 -61
  215. package/src/core/testkit/AGENTS.md +0 -55
  216. package/src/runtime/AGENTS.md +0 -74
  217. package/src/runtime/test-helpers.ts +0 -40
@@ -0,0 +1,8 @@
1
+ import{getFlagAliasNames as e}from"../schema/flag.mjs";import{formatDisplayValue as t}from"../output/display-value.mjs";function n(e){return{width:e?.width??80,binName:e?.binName,isDefaultHelp:e?.isDefaultHelp??!1}}function r(e,t){return e.length>=t?e:e+` `.repeat(t-e.length)}function i(e,t,n){if(e.length+n<=t)return e;let r=t-n;if(r<=0)return e;let i=e.split(` `),a=[],o=``;for(let e of i)o.length===0?o=e:o.length+1+e.length<=r?o+=` ${e}`:(a.push(o),o=e);o.length>0&&a.push(o);let s=` `.repeat(n);return a.map((e,t)=>t===0?e:`${s}${e}`).join(`
2
+ `)}function a(e){return typeof e==`string`?`[deprecated: ${e}]`:`[deprecated]`}function o(e){return e===void 0?`undefined`:e===null?`null`:t(e)}function s(t,n){let r=e(n,{kind:`short`}),i=e(n,{kind:`long`}),a=[...r.map(e=>`-${e}`),`--${t}`,...i.map(e=>`--${e}`)];return n.kind===`boolean`?a.join(`, `):`${a.join(`, `)} ${c(n)}`}function c(e){switch(e.kind){case`string`:return`<string>`;case`number`:return`<number>`;case`enum`:return`<${(e.enumValues??[]).join(`|`)}>`;case`array`:return`<${e.elementSchema===void 0?`value`:c(e.elementSchema).slice(1,-1)}>...`;case`boolean`:return``;case`custom`:return`<value>`}}function l(e){let t=[];return e.description!==void 0&&t.push(e.description),e.deprecated!==void 0&&t.push(a(e.deprecated)),e.envVar!==void 0&&t.push(`[env: ${e.envVar}]`),e.configPath!==void 0&&t.push(`[config: ${e.configPath}]`),e.prompt!==void 0&&t.push(`[prompt]`),e.presence===`required`?t.push(`[required]`):e.presence===`defaulted`&&e.kind!==`boolean`&&t.push(`(default: ${o(e.defaultValue)})`),t.join(` `)}function u(t){let n=Object.keys(t);if(n.length===0)return[];let r=[...n].sort((n,r)=>{let i=t[n],a=t[r];if(i===void 0||a===void 0)return 0;let o=e(i,{kind:`short`}).length>0,s=e(a,{kind:`short`}).length>0;return o&&!s?-1:!o&&s?1:n.localeCompare(r)}),i=[];for(let e of r){let n=t[e];n!==void 0&&i.push({left:s(e,n),description:l(n)})}return i}function d(e){let{name:t,schema:n}=e,r=n.kind===`enum`&&n.enumValues!==void 0?n.enumValues.join(`|`):t,i=n.variadic?`...`:``;return n.presence===`required`?`<${r}>${i}`:`[${r}]${i}`}function f(e){let t=[];return e.description!==void 0&&t.push(e.description),e.deprecated!==void 0&&t.push(a(e.deprecated)),e.envVar!==void 0&&t.push(`[env: ${e.envVar}]`),e.presence===`defaulted`&&t.push(`(default: ${o(e.defaultValue)})`),t.join(` `)}function p(e,t){let r=n(t),i=[];i.push(h(e,r)),e.description!==void 0&&i.push(e.description);let a=e.commands.filter(e=>!e.hidden);return a.length>0&&i.push(v(a,r)),e.args.length>0&&i.push(g(e.args,r)),Object.keys(e.flags).length>0&&i.push(_(e.flags,r)),e.examples.length>0&&i.push(y(e.examples)),i}function m(e,t){return`${p(e,t).join(`
3
+
4
+ `)}\n`}function h(e,t){let n=[`Usage:`],r=t.binName===void 0||t.isDefaultHelp&&t.binName===e.name?e.name:`${t.binName} ${e.name}`;n.push(r),e.commands.length>0&&n.push(`<command>`),Object.keys(e.flags).length>0&&n.push(`[flags]`);for(let t of e.args)n.push(d(t));return n.join(` `)}function g(e,t){let n=[`Arguments:`],a=0,o=[];for(let t of e){let e=` ${d(t)}`,n=f(t.schema);o.push({left:e,desc:n}),e.length>a&&(a=e.length)}let s=a+2;for(let{left:e,desc:a}of o)if(a.length===0)n.push(e);else{let o=r(e,s),c=i(a,t.width,s);n.push(`${o}${c}`)}return n.join(`
5
+ `)}function _(e,t){let n=[`Flags:`],a=u(e);if(a.length===0)return``;let o=0;for(let e of a){let t=` ${e.left}`;t.length>o&&(o=t.length)}let s=o+2;for(let e of a){let a=` ${e.left}`;if(e.description.length===0)n.push(a);else{let o=r(a,s),c=i(e.description,t.width,s);n.push(`${o}${c}`)}}return n.join(`
6
+ `)}function v(e,t){let n=[`Commands:`],a=0;for(let t of e)t.name.length>a&&(a=t.name.length);let o=2+a+2;for(let a of e){let e=` ${a.name}`,s=a.description??``;if(s.length===0)n.push(e);else{let a=r(e,o),c=i(s,t.width,o);n.push(`${a}${c}`)}}return n.join(`
7
+ `)}function y(e){let t=[`Examples:`];for(let n of e)n.description===void 0?t.push(` $ ${n.command}`):(t.push(` ${n.description}:`),t.push(` $ ${n.command}`));return t.join(`
8
+ `)}export{m as formatHelp,p as formatHelpSections};
@@ -0,0 +1,109 @@
1
+ import { CommandSchema } from "../schema/command.mjs";
2
+ import { CLISchema } from "../cli/index.mjs";
3
+
4
+ //#region src/core/json-schema/index.d.ts
5
+ /**
6
+ * Options for JSON Schema generation.
7
+ *
8
+ * Both {@link generateSchema} and {@link generateInputSchema} accept these
9
+ * options to control which parts of the CLI schema are included in the output.
10
+ */
11
+ interface JsonSchemaOptions {
12
+ /**
13
+ * Include commands marked as hidden.
14
+ *
15
+ * When `true` (default), hidden commands appear in the output with
16
+ * `hidden: true` (definition schema) or as valid branches (input schema).
17
+ * When `false`, hidden commands and their entire subtrees are excluded.
18
+ *
19
+ * @defaultValue `true`
20
+ */
21
+ readonly includeHidden?: boolean;
22
+ /**
23
+ * Include prompt configuration on flags.
24
+ *
25
+ * When `false`, prompt configs are omitted even if defined on flags.
26
+ * Useful for producing a schema focused on the non-interactive CLI
27
+ * surface only.
28
+ *
29
+ * Only affects {@link generateSchema} output — prompt configs are never
30
+ * included in {@link generateInputSchema} output.
31
+ *
32
+ * @defaultValue `true`
33
+ */
34
+ readonly includePrompts?: boolean;
35
+ }
36
+ /**
37
+ * Generate a definition metadata document describing the CLI's structure.
38
+ *
39
+ * Walks the full command tree and produces a plain JSON-serializable object
40
+ * representing all commands, subcommands, flags, args, and metadata.
41
+ * Non-serializable runtime values (parse functions, middleware handlers,
42
+ * interactive resolvers) are omitted.
43
+ *
44
+ * @param schema - The CLI schema from `CLIBuilder.schema`.
45
+ * @param options - Generation options.
46
+ * @returns A plain object suitable for `JSON.stringify()`.
47
+ *
48
+ * @example
49
+ * ```ts
50
+ * const app = cli('myapp').version('1.0.0').command(deploy);
51
+ * const definition = generateSchema(app.schema);
52
+ * writeFileSync('cli-schema.json', JSON.stringify(definition, null, 2));
53
+ * ```
54
+ */
55
+ declare function generateSchema(schema: CLISchema, options?: JsonSchemaOptions): Record<string, unknown>;
56
+ /**
57
+ * Generate a JSON Schema (draft 2020-12) for validating CLI input as JSON.
58
+ *
59
+ * Accepts either a full {@link CLISchema} (producing a discriminated union
60
+ * across all commands) or a single {@link CommandSchema} (producing a flat
61
+ * object schema for that command's flags and args).
62
+ *
63
+ * **Single command** — produces an object schema where flag/arg names are
64
+ * properties with appropriate JSON Schema types.
65
+ *
66
+ * **Multi-command CLI** — produces a `oneOf` discriminated union with a
67
+ * `command` property identifying each branch. Nested subcommands use
68
+ * dot-delimited paths (e.g. `"deploy.rollback"`).
69
+ *
70
+ * Only commands with action handlers are included (group commands without
71
+ * actions are not directly invocable and are skipped).
72
+ *
73
+ * @param schema - A CLI schema or a single command schema.
74
+ * @param options - Generation options.
75
+ * @returns A JSON Schema object suitable for `JSON.stringify()`.
76
+ *
77
+ * @example
78
+ * ```ts
79
+ * // Validate a config file against the CLI's input shape
80
+ * const inputSchema = generateInputSchema(app.schema);
81
+ * writeFileSync('input-schema.json', JSON.stringify(inputSchema, null, 2));
82
+ * ```
83
+ */
84
+ declare function generateInputSchema(schema: CLISchema | CommandSchema, options?: JsonSchemaOptions): Record<string, unknown>;
85
+ /**
86
+ * JSON Schema (draft 2020-12) that validates the output of {@link generateSchema}.
87
+ *
88
+ * Each `$defs` entry is defined once as a schema DSL string — the DSL
89
+ * parser produces a runtime AST, and {@link nodeToJsonSchema} converts
90
+ * that AST to a JSON Schema fragment. No probe fixtures, no override
91
+ * maps, no manually maintained type definitions.
92
+ *
93
+ * Hosted at {@link DEFINITION_SCHEMA_URL} for `$schema` resolution. Also
94
+ * exported so tooling can validate definition documents without a network
95
+ * round-trip.
96
+ *
97
+ * @example
98
+ * ```ts
99
+ * import Ajv from 'ajv/dist/2020';
100
+ * import { definitionMetaSchema, generateSchema } from '@kjanat/dreamcli';
101
+ *
102
+ * const ajv = new Ajv();
103
+ * const validate = ajv.compile(definitionMetaSchema);
104
+ * const valid = validate(generateSchema(myCli.schema));
105
+ * ```
106
+ */
107
+ declare const definitionMetaSchema: Record<string, unknown>;
108
+ //#endregion
109
+ export { type JsonSchemaOptions, definitionMetaSchema, generateInputSchema, generateSchema };
@@ -0,0 +1,55 @@
1
+ import{getFlagAliasNames as e}from"../schema/flag.mjs";import{parseSchema as t}from"../schema-dsl/runtime.mjs";import{nodeToJsonSchema as n}from"../schema-dsl/to-json-schema.mjs";import{definitionMetaSchemaDescriptions as r}from"./meta-descriptions.generated.mjs";function i(e){return{includeHidden:e?.includeHidden??!0,includePrompts:e?.includePrompts??!0}}const a=`https://cdn.jsdelivr.net/npm/@kjanat/dreamcli/dreamcli.schema.json`,o=`https://json-schema.org/draft/2020-12/schema`;function s(e){return typeof e==`object`&&!!e&&!Array.isArray(e)}function c(e,t){let n=i(t),r={$schema:a,name:e.name};return e.version!==void 0&&(r.version=e.version),e.description!==void 0&&(r.description=e.description),e.defaultCommand!==void 0&&(n.includeHidden||!e.defaultCommand.schema.hidden)&&(r.defaultCommand=e.defaultCommand.schema.name),r.commands=e.commands.filter(e=>n.includeHidden||!e.schema.hidden).map(e=>l(e.schema,n)),r}function l(e,t){let n={name:e.name};e.description!==void 0&&(n.description=e.description),e.aliases.length>0&&(n.aliases=[...e.aliases]),e.hidden&&(n.hidden=!0),e.examples.length>0&&(n.examples=e.examples.map(m));let r={};for(let[n,i]of Object.entries(e.flags))r[n]=u(i,t);return n.flags=r,n.args=e.args.map(d),n.commands=e.commands.filter(e=>t.includeHidden||!e.hidden).map(e=>l(e,t)),n}function u(t,n){let r={kind:t.kind,presence:t.presence};t.presence===`defaulted`&&w(t.defaultValue)&&(r.defaultValue=t.defaultValue);let i=e(t);return i.length>0&&(r.aliases=[...i]),t.envVar!==void 0&&(r.envVar=t.envVar),t.configPath!==void 0&&(r.configPath=t.configPath),t.description!==void 0&&(r.description=t.description),t.enumValues!==void 0&&(r.enumValues=[...t.enumValues]),t.elementSchema!==void 0&&(r.elementSchema=u(t.elementSchema,n)),n.includePrompts&&t.prompt!==void 0&&(r.prompt=f(t.prompt)),t.deprecated!==void 0&&(r.deprecated=t.deprecated),t.propagate&&(r.propagate=!0),r}function d(e){let{name:t,schema:n}=e,r={name:t,kind:n.kind,presence:n.presence};return n.variadic&&(r.variadic=!0),n.stdinMode&&(r.stdinMode=!0),n.presence===`defaulted`&&w(n.defaultValue)&&(r.defaultValue=n.defaultValue),n.description!==void 0&&(r.description=n.description),n.envVar!==void 0&&(r.envVar=n.envVar),n.enumValues!==void 0&&(r.enumValues=[...n.enumValues]),n.deprecated!==void 0&&(r.deprecated=n.deprecated),r}function f(e){let t={kind:e.kind,message:e.message};switch(e.kind){case`input`:e.placeholder!==void 0&&(t.placeholder=e.placeholder);break;case`select`:e.choices!==void 0&&(t.choices=e.choices.map(p));break;case`multiselect`:e.choices!==void 0&&(t.choices=e.choices.map(p)),e.min!==void 0&&(t.min=e.min),e.max!==void 0&&(t.max=e.max);break;case`confirm`:break}return t}function p(e){let t={value:e.value};return e.label!==void 0&&(t.label=e.label),e.description!==void 0&&(t.description=e.description),t}function m(e){let t={command:e.command};return e.description!==void 0&&(t.description=e.description),t}function h(e,t){let n=i(t);if(g(e))return{$schema:o,...v(e)};let r=[];for(let t of e.commands)!n.includeHidden&&t.schema.hidden||_(t.schema,``,r,n);if(r.length===1)return{$schema:o,...y(r[0]??{})};if(r.length>0){let t=e.defaultCommand!==void 0&&(n.includeHidden||!e.defaultCommand.schema.hidden)?e.defaultCommand.schema.name:void 0;return{$schema:o,oneOf:t===void 0?r:r.map(e=>b(e)===t?y(e):e)}}return{$schema:o,type:`object`}}function g(e){return`flags`in e&&`args`in e&&`middleware`in e&&`hasAction`in e}function _(e,t,n,r){let i=t?`${t}.${e.name}`:e.name;e.hasAction&&n.push(v(e,i));for(let t of e.commands)!r.includeHidden&&t.hidden||_(t,i,n,r)}function v(e,t){let n={},r=[];t!==void 0&&(n.command={const:t},r.push(`command`));for(let[t,i]of Object.entries(e.flags))n[t]=x(i),i.presence===`required`&&r.push(t);for(let t of e.args)n[t.name]=S(t.schema),t.schema.presence===`required`&&r.push(t.name);let i={type:`object`,properties:n,additionalProperties:!1};return r.length>0&&(i.required=r),i}function y(e){let t=e.properties,n=e.required,r=s(t)?{...t}:void 0,i=Array.isArray(n)?n.filter(e=>typeof e==`string`):void 0;r!==void 0&&delete r.command;let a=i?.filter(e=>e!==`command`),o={...e};return r!==void 0&&(o.properties=r),a!==void 0&&a.length>0?o.required=a:delete o.required,o}function b(e){let t=e.properties;if(!s(t))return;let n=t.command;return s(n)&&typeof n.const==`string`?n.const:void 0}function x(e){let t={};switch(e.kind){case`string`:t.type=`string`;break;case`number`:t.type=`number`;break;case`boolean`:t.type=`boolean`;break;case`enum`:t.type=`string`,e.enumValues!==void 0&&(t.enum=[...e.enumValues]);break;case`array`:t.type=`array`,e.elementSchema!==void 0&&(t.items=x(e.elementSchema));break;case`custom`:break}return e.description!==void 0&&(t.description=e.description),e.presence===`defaulted`&&w(e.defaultValue)&&(t.default=e.defaultValue),e.deprecated!==void 0&&(t.deprecated=e.deprecated),t}function S(e){let t=C(e),n=e.variadic?{type:`array`,items:t}:{...t};return e.description!==void 0&&(n.description=e.description),e.presence===`defaulted`&&w(e.defaultValue)&&(n.default=e.defaultValue),e.deprecated!==void 0&&(n.deprecated=e.deprecated),n}function C(e){switch(e.kind){case`string`:return{type:`string`};case`number`:return{type:`number`};case`enum`:{let t={type:`string`};return e.enumValues!==void 0&&(t.enum=[...e.enumValues]),t}case`custom`:return{}}}function w(e,t=new WeakSet){if(e===void 0)return!1;if(e===null)return!0;let n=typeof e;if(n===`string`||n===`boolean`)return!0;if(n===`number`)return Number.isFinite(e);if(n===`function`||n===`symbol`||n===`bigint`)return!1;if(Array.isArray(e)){if(t.has(e))return!1;t.add(e);try{return e.every(e=>w(e,t))}finally{t.delete(e)}}if(n===`object`){let n=e;if(!T(n)||t.has(n))return!1;t.add(n);try{return Object.values(n).every(e=>w(e,t))}finally{t.delete(n)}}return!1}function T(e){let t=Object.getPrototypeOf(e);return t===Object.prototype||t===null}function E(e){return n(t(e))}function D(e,t){let n=e.properties,r=typeof n==`object`&&n&&T(n)&&t.properties!==void 0?Object.fromEntries(Object.entries(n).map(([e,n])=>{let r=t.properties?.[e];return r===void 0||typeof n!=`object`||!n||!T(n)?[e,n]:[e,D(n,r)]})):void 0;return{...e,...t.description===void 0?{}:{description:t.description},...r===void 0?{}:{properties:r}}}function O(e,t){let n=D(e,t.root),r=n.$defs;return typeof r!=`object`||!r||!T(r)?n:{...n,$defs:Object.fromEntries(Object.entries(r).map(([e,n])=>{let r=t.defs[e];return r===void 0||typeof n!=`object`||!n||!T(n)?[e,n]:[e,D(n,r)]}))}}const k=O({$schema:o,$id:a,title:`@kjanat/dreamcli definition schema`,description:`Describes the structure of a CLI built with dreamcli — commands, flags, args, types, constraints, env bindings, and prompts.`,...E(`{
2
+ $schema: '${a}';
3
+ name: string;
4
+ version?: string;
5
+ description?: string;
6
+ defaultCommand?: string;
7
+ commands: @command[]
8
+ }`),$defs:{command:E(`{
9
+ name: string;
10
+ description?: string;
11
+ aliases?: string[];
12
+ hidden?: true;
13
+ examples?: @example[];
14
+ flags: Record<string, @flag>;
15
+ args: @arg[];
16
+ commands: @command[]
17
+ }`),flag:E(`{
18
+ kind: 'string' | 'number' | 'boolean' | 'enum' | 'array' | 'custom';
19
+ presence: 'optional' | 'required' | 'defaulted';
20
+ defaultValue?: unknown;
21
+ aliases?: string[];
22
+ envVar?: string;
23
+ configPath?: string;
24
+ description?: string;
25
+ enumValues?: string[];
26
+ elementSchema?: @flag;
27
+ prompt?: @prompt;
28
+ deprecated?: string | true;
29
+ propagate?: true
30
+ }`),arg:E(`{
31
+ name: string;
32
+ kind: 'string' | 'number' | 'enum' | 'custom';
33
+ presence: 'required' | 'optional' | 'defaulted';
34
+ variadic?: true;
35
+ stdinMode?: true;
36
+ defaultValue?: unknown;
37
+ description?: string;
38
+ envVar?: string;
39
+ enumValues?: string[];
40
+ deprecated?: string | true
41
+ }`),prompt:E(`{
42
+ kind: 'confirm' | 'input' | 'select' | 'multiselect';
43
+ message: string;
44
+ placeholder?: string;
45
+ choices?: @choice[];
46
+ min?: integer;
47
+ max?: integer
48
+ }`),choice:E(`{
49
+ value: string;
50
+ label?: string;
51
+ description?: string
52
+ }`),example:E(`{
53
+ command: string;
54
+ description?: string
55
+ }`)}},r);export{k as definitionMetaSchema,h as generateInputSchema,c as generateSchema};
@@ -0,0 +1,185 @@
1
+ //#region src/core/json-schema/meta-descriptions.generated.d.ts
2
+ /**
3
+ * Generated definition meta-schema descriptions from normalized TypeDoc output.
4
+ *
5
+ * @module
6
+ */
7
+ declare const definitionMetaSchemaDescriptions: {
8
+ readonly root: {
9
+ readonly description: 'Runtime descriptor for the CLI program.\n\nStores the program name, version, description, and registered commands.\\\nBuilt incrementally by CLIBuilder.';
10
+ readonly properties: {
11
+ readonly name: {
12
+ readonly description: 'Program name (used in help text, usage lines, and completion scripts).';
13
+ };
14
+ readonly version: {
15
+ readonly description: 'Program version (shown by `--version`).';
16
+ };
17
+ readonly description: {
18
+ readonly description: 'Program description (shown in root help).';
19
+ };
20
+ readonly defaultCommand: {
21
+ readonly description: 'Default command dispatched when no subcommand matches.\n\nWhen set, the CLI root behaves like a hybrid command group: subcommands\ndispatch by name as usual, but empty argv or flags-only argv falls\nthrough to this command instead of showing root help.\n\nSet via the .default() builder method.';
22
+ };
23
+ readonly commands: {
24
+ readonly description: 'Registered commands (type-erased for heterogeneous storage).';
25
+ };
26
+ };
27
+ };
28
+ readonly defs: {
29
+ readonly command: {
30
+ readonly description: "Runtime descriptor produced by CommandBuilder.\n\nConsumers (parser, help generator, CLI dispatcher) read this to\nunderstand the command's shape \u2014 flags, args, aliases, subcommands,\nmiddleware, and interactive resolver.";
31
+ readonly properties: {
32
+ readonly name: {
33
+ readonly description: "The command name (used for dispatch, e.g. `'deploy'`).";
34
+ };
35
+ readonly description: {
36
+ readonly description: 'Human-readable description for help text.';
37
+ };
38
+ readonly aliases: {
39
+ readonly description: 'Alternative names for this command.';
40
+ };
41
+ readonly hidden: {
42
+ readonly description: 'Whether this command is hidden from help listings.';
43
+ };
44
+ readonly examples: {
45
+ readonly description: 'Usage examples for help text.';
46
+ };
47
+ readonly flags: {
48
+ readonly description: 'Named flag schemas, keyed by flag name.';
49
+ };
50
+ readonly args: {
51
+ readonly description: 'Ordered positional arg entries (name + schema).';
52
+ };
53
+ readonly commands: {
54
+ readonly description: 'Nested subcommand schemas (for help rendering and completion).\n\nPure data \u2014 no execution closures. Populated by `.command()` on\n`CommandBuilder`. Empty for leaf commands.';
55
+ };
56
+ };
57
+ };
58
+ readonly flag: {
59
+ readonly description: "The runtime descriptor stored inside every FlagBuilder. Consumers (parser,\nhelp generator, resolution chain) read this to understand the flag's shape\nwithout touching generics.";
60
+ readonly properties: {
61
+ readonly kind: {
62
+ readonly description: 'What kind of value this flag accepts.';
63
+ };
64
+ readonly presence: {
65
+ readonly description: "Presence describes whether a flag value is guaranteed to exist when the\naction handler runs:\n\n- `'optional'` \u2014 not required; unresolved value follows the kind-specific\n optional fallback (`undefined` for most flags, `[]` for arrays)\n- `'required'` \u2014 must be supplied; error if missing\n- `'defaulted'` \u2014 always present (falls back to default value)";
66
+ };
67
+ readonly defaultValue: {
68
+ readonly description: 'Runtime default value (if any).';
69
+ };
70
+ readonly aliases: {
71
+ readonly description: "Short/long aliases (e.g. `[{ name: 'f', hidden: false }]` for `--force`).";
72
+ };
73
+ readonly envVar: {
74
+ readonly description: 'Environment variable name for v0.2+ resolution.';
75
+ };
76
+ readonly configPath: {
77
+ readonly description: "Dotted config path for v0.2+ resolution (e.g. `'deploy.region'`).";
78
+ };
79
+ readonly description: {
80
+ readonly description: 'Human-readable description for help text.';
81
+ };
82
+ readonly enumValues: {
83
+ readonly description: "Allowed literal values when `kind === 'enum'`.";
84
+ };
85
+ readonly elementSchema: {
86
+ readonly description: "Element schema when `kind === 'array'`.";
87
+ };
88
+ readonly prompt: {
89
+ readonly description: 'Interactive prompt configuration for v0.3+ resolution.';
90
+ };
91
+ readonly deprecated: {
92
+ readonly description: 'Deprecation marker.\n\n- `undefined` \u2014 not deprecated (default)\n- `true` \u2014 deprecated with no migration message\n- `string` \u2014 deprecated with a reason/migration message\n\nWhen a deprecated flag is used, a warning is emitted to stderr.\nHelp text shows `[deprecated]` or `[deprecated: <reason>]`.';
93
+ };
94
+ readonly propagate: {
95
+ readonly description: 'Whether this flag propagates to subcommands in nested command trees.\n\nWhen `true`, the flag is automatically available to all descendant\ncommands. A child command that defines a flag with the same name\nshadows the propagated parent flag.';
96
+ };
97
+ };
98
+ };
99
+ readonly arg: {
100
+ readonly description: "The runtime descriptor stored inside every ArgBuilder. Consumers (parser,\nhelp generator) read this to understand the arg's shape without touching\ngenerics.";
101
+ readonly properties: {
102
+ readonly name: {
103
+ readonly description: 'A named positional argument entry in the command schema.\n\nPairs a user-facing arg name with its ArgSchema descriptor.\nThe array ordering in CommandSchema.args determines CLI position.';
104
+ };
105
+ readonly kind: {
106
+ readonly description: 'What kind of value this arg accepts.';
107
+ };
108
+ readonly presence: {
109
+ readonly description: "Presence describes whether a positional arg is guaranteed to exist when the\naction handler runs:\n\n- `'required'` \u2014 must be supplied; error if missing (default)\n- `'optional'` \u2014 may be `undefined` if not supplied\n- `'defaulted'` \u2014 always present (falls back to default value)";
110
+ };
111
+ readonly variadic: {
112
+ readonly description: 'Whether this arg consumes all remaining positionals.';
113
+ };
114
+ readonly stdinMode: {
115
+ readonly description: 'Whether this arg may read from stdin during resolution.';
116
+ };
117
+ readonly defaultValue: {
118
+ readonly description: 'Runtime default value (if any).';
119
+ };
120
+ readonly description: {
121
+ readonly description: 'Human-readable description for help text.';
122
+ };
123
+ readonly envVar: {
124
+ readonly description: "Environment variable name for env resolution.\n\nWhen set and the CLI value is absent, the resolver reads this env var\nand coerces the string to the arg's declared kind.";
125
+ };
126
+ readonly enumValues: {
127
+ readonly description: "Allowed literal values when `kind === 'enum'`.";
128
+ };
129
+ readonly deprecated: {
130
+ readonly description: 'Deprecation marker.\n\n- `undefined` \u2014 not deprecated (default)\n- `true` \u2014 deprecated with no migration message\n- `string` \u2014 deprecated with a reason/migration message\n\nWhen a deprecated arg is used, a warning is emitted to stderr.\nHelp text shows `[deprecated]` or `[deprecated: <reason>]`.';
131
+ };
132
+ };
133
+ };
134
+ readonly prompt: {
135
+ readonly description: "Discriminated union of all prompt configurations.\n\nUse the `kind` field to narrow:\n```ts\nif (config.kind === 'select') {\n config.choices // readonly SelectChoice[] | undefined\n}\n```";
136
+ readonly properties: {
137
+ readonly kind: {
138
+ readonly description: "The kind of interactive prompt to present.\n\n- `'confirm'` \u2014 yes/no boolean question\n- `'input'` \u2014 free-text string input\n- `'select'` \u2014 single selection from a list\n- `'multiselect'` \u2014 multiple selections from a list";
139
+ };
140
+ readonly message: {
141
+ readonly description: 'The question displayed to the user.';
142
+ };
143
+ readonly placeholder: {
144
+ readonly description: 'Placeholder text shown before user types (informational only).';
145
+ };
146
+ readonly choices: {
147
+ readonly description: 'Available choices. When omitted for `enum` flags, the enum values\nfrom the flag schema are used automatically.';
148
+ };
149
+ readonly min: {
150
+ readonly description: 'Minimum number of selections required.';
151
+ };
152
+ readonly max: {
153
+ readonly description: 'Maximum number of selections allowed.';
154
+ };
155
+ };
156
+ };
157
+ readonly choice: {
158
+ readonly description: 'A selectable option for SelectPromptConfig and MultiselectPromptConfig prompts.';
159
+ readonly properties: {
160
+ readonly value: {
161
+ readonly description: 'The value returned when this choice is selected.';
162
+ };
163
+ readonly label: {
164
+ readonly description: 'Display label shown to the user.';
165
+ };
166
+ readonly description: {
167
+ readonly description: 'Optional description shown alongside the choice.';
168
+ };
169
+ };
170
+ };
171
+ readonly example: {
172
+ readonly description: 'A single usage example shown in help text.';
173
+ readonly properties: {
174
+ readonly command: {
175
+ readonly description: "The command invocation (e.g. `'deploy production --force'`).";
176
+ };
177
+ readonly description: {
178
+ readonly description: 'Optional description of what this example does.';
179
+ };
180
+ };
181
+ };
182
+ };
183
+ };
184
+ //#endregion
185
+ export { definitionMetaSchemaDescriptions };
@@ -0,0 +1,28 @@
1
+ const e={root:{description:`Runtime descriptor for the CLI program.
2
+
3
+ Stores the program name, version, description, and registered commands.\\
4
+ Built incrementally by CLIBuilder.`,properties:{name:{description:`Program name (used in help text, usage lines, and completion scripts).`},version:{description:"Program version (shown by `--version`)."},description:{description:`Program description (shown in root help).`},defaultCommand:{description:`Default command dispatched when no subcommand matches.
5
+
6
+ When set, the CLI root behaves like a hybrid command group: subcommands
7
+ dispatch by name as usual, but empty argv or flags-only argv falls
8
+ through to this command instead of showing root help.
9
+
10
+ Set via the .default() builder method.`},commands:{description:`Registered commands (type-erased for heterogeneous storage).`}}},defs:{command:{description:`Runtime descriptor produced by CommandBuilder.
11
+
12
+ Consumers (parser, help generator, CLI dispatcher) read this to
13
+ understand the command's shape — flags, args, aliases, subcommands,
14
+ middleware, and interactive resolver.`,properties:{name:{description:"The command name (used for dispatch, e.g. `'deploy'`)."},description:{description:`Human-readable description for help text.`},aliases:{description:`Alternative names for this command.`},hidden:{description:`Whether this command is hidden from help listings.`},examples:{description:`Usage examples for help text.`},flags:{description:`Named flag schemas, keyed by flag name.`},args:{description:`Ordered positional arg entries (name + schema).`},commands:{description:"Nested subcommand schemas (for help rendering and completion).\n\nPure data — no execution closures. Populated by `.command()` on\n`CommandBuilder`. Empty for leaf commands."}}},flag:{description:`The runtime descriptor stored inside every FlagBuilder. Consumers (parser,
15
+ help generator, resolution chain) read this to understand the flag's shape
16
+ without touching generics.`,properties:{kind:{description:`What kind of value this flag accepts.`},presence:{description:"Presence describes whether a flag value is guaranteed to exist when the\naction handler runs:\n\n- `'optional'` — not required; unresolved value follows the kind-specific\n optional fallback (`undefined` for most flags, `[]` for arrays)\n- `'required'` — must be supplied; error if missing\n- `'defaulted'` — always present (falls back to default value)"},defaultValue:{description:`Runtime default value (if any).`},aliases:{description:"Short/long aliases (e.g. `[{ name: 'f', hidden: false }]` for `--force`)."},envVar:{description:`Environment variable name for v0.2+ resolution.`},configPath:{description:"Dotted config path for v0.2+ resolution (e.g. `'deploy.region'`)."},description:{description:`Human-readable description for help text.`},enumValues:{description:"Allowed literal values when `kind === 'enum'`."},elementSchema:{description:"Element schema when `kind === 'array'`."},prompt:{description:`Interactive prompt configuration for v0.3+ resolution.`},deprecated:{description:"Deprecation marker.\n\n- `undefined` — not deprecated (default)\n- `true` — deprecated with no migration message\n- `string` — deprecated with a reason/migration message\n\nWhen a deprecated flag is used, a warning is emitted to stderr.\nHelp text shows `[deprecated]` or `[deprecated: <reason>]`."},propagate:{description:`Whether this flag propagates to subcommands in nested command trees.
17
+
18
+ When \`true\`, the flag is automatically available to all descendant
19
+ commands. A child command that defines a flag with the same name
20
+ shadows the propagated parent flag.`}}},arg:{description:`The runtime descriptor stored inside every ArgBuilder. Consumers (parser,
21
+ help generator) read this to understand the arg's shape without touching
22
+ generics.`,properties:{name:{description:`A named positional argument entry in the command schema.
23
+
24
+ Pairs a user-facing arg name with its ArgSchema descriptor.
25
+ The array ordering in CommandSchema.args determines CLI position.`},kind:{description:`What kind of value this arg accepts.`},presence:{description:"Presence describes whether a positional arg is guaranteed to exist when the\naction handler runs:\n\n- `'required'` — must be supplied; error if missing (default)\n- `'optional'` — may be `undefined` if not supplied\n- `'defaulted'` — always present (falls back to default value)"},variadic:{description:`Whether this arg consumes all remaining positionals.`},stdinMode:{description:`Whether this arg may read from stdin during resolution.`},defaultValue:{description:`Runtime default value (if any).`},description:{description:`Human-readable description for help text.`},envVar:{description:`Environment variable name for env resolution.
26
+
27
+ When set and the CLI value is absent, the resolver reads this env var
28
+ and coerces the string to the arg's declared kind.`},enumValues:{description:"Allowed literal values when `kind === 'enum'`."},deprecated:{description:"Deprecation marker.\n\n- `undefined` — not deprecated (default)\n- `true` — deprecated with no migration message\n- `string` — deprecated with a reason/migration message\n\nWhen a deprecated arg is used, a warning is emitted to stderr.\nHelp text shows `[deprecated]` or `[deprecated: <reason>]`."}}},prompt:{description:"Discriminated union of all prompt configurations.\n\nUse the `kind` field to narrow:\n```ts\nif (config.kind === 'select') {\n config.choices // readonly SelectChoice[] | undefined\n}\n```",properties:{kind:{description:"The kind of interactive prompt to present.\n\n- `'confirm'` — yes/no boolean question\n- `'input'` — free-text string input\n- `'select'` — single selection from a list\n- `'multiselect'` — multiple selections from a list"},message:{description:`The question displayed to the user.`},placeholder:{description:`Placeholder text shown before user types (informational only).`},choices:{description:"Available choices. When omitted for `enum` flags, the enum values\nfrom the flag schema are used automatically."},min:{description:`Minimum number of selections required.`},max:{description:`Maximum number of selections allowed.`}}},choice:{description:`A selectable option for SelectPromptConfig and MultiselectPromptConfig prompts.`,properties:{value:{description:`The value returned when this choice is selected.`},label:{description:`Display label shown to the user.`},description:{description:`Optional description shown alongside the choice.`}}},example:{description:`A single usage example shown in help text.`,properties:{command:{description:"The command invocation (e.g. `'deploy production --force'`)."},description:{description:`Optional description of what this example does.`}}}}};export{e as definitionMetaSchemaDescriptions};
@@ -0,0 +1,194 @@
1
+ import { ActivityEvent, ProgressHandle, ProgressOptions, SpinnerHandle } from "../schema/activity.mjs";
2
+ import { WriteFn } from "./writer.mjs";
3
+
4
+ //#region src/core/output/activity.d.ts
5
+ /**
6
+ * Noop spinner handle singleton.
7
+ *
8
+ * All methods are no-ops. Used when spinners should produce no output
9
+ * at all — `jsonMode`, or non-TTY with `fallback: 'silent'` (default).
10
+ *
11
+ * @internal
12
+ */
13
+ declare const noopSpinnerHandle: SpinnerHandle;
14
+ /**
15
+ * Noop progress handle singleton.
16
+ *
17
+ * All methods are no-ops. Used when progress bars should produce no
18
+ * output at all — `jsonMode`, or non-TTY with `fallback: 'silent'`.
19
+ *
20
+ * @internal
21
+ */
22
+ declare const noopProgressHandle: ProgressHandle;
23
+ /**
24
+ * Static spinner handle — emits plain text at lifecycle boundaries.
25
+ *
26
+ * Used in non-TTY environments with `fallback: 'static'`. No animation,
27
+ * no ANSI codes. Emits text on start and terminal events only.
28
+ *
29
+ * Terminal methods are idempotent — calling after stop is a no-op.
30
+ *
31
+ * @internal
32
+ */
33
+ declare class StaticSpinnerHandle implements SpinnerHandle {
34
+ private readonly write;
35
+ /** Whether the handle has been stopped (terminal state reached). */
36
+ private stopped;
37
+ constructor(text: string, write: WriteFn);
38
+ update(_text: string): void;
39
+ succeed(text?: string): void;
40
+ fail(text?: string): void;
41
+ stop(): void;
42
+ wrap<T>(promise: Promise<T>, options?: {
43
+ readonly succeed?: string;
44
+ readonly fail?: string;
45
+ }): Promise<T>;
46
+ }
47
+ /**
48
+ * Static progress handle — emits plain text at lifecycle boundaries.
49
+ *
50
+ * Used in non-TTY environments with `fallback: 'static'`. No animation,
51
+ * no progress bar rendering. Emits label on start, text on done/fail.
52
+ *
53
+ * Terminal methods are idempotent — calling after stop is a no-op.
54
+ *
55
+ * @internal
56
+ */
57
+ declare class StaticProgressHandle implements ProgressHandle {
58
+ private readonly write;
59
+ /** Whether the handle has been stopped (terminal state reached). */
60
+ private stopped;
61
+ constructor(label: string | undefined, write: WriteFn);
62
+ increment(_n?: number): void;
63
+ update(_value: number): void;
64
+ done(text?: string): void;
65
+ fail(text?: string): void;
66
+ }
67
+ /**
68
+ * TTY spinner handle — animated braille frames with ANSI line overwrite.
69
+ *
70
+ * Used in TTY environments (non-JSON mode). Renders a spinning indicator
71
+ * with configurable text, using `\r` + erase-line to overwrite in place.
72
+ * Hides the cursor during animation and restores it on any terminal method.
73
+ *
74
+ * Terminal methods (`succeed`, `fail`, `stop`) are idempotent — calling any
75
+ * of them after the handle is already stopped is a no-op.
76
+ *
77
+ * **Note:** If the process exits abnormally (e.g. `SIGKILL`) while a spinner
78
+ * is active, the cursor may remain hidden. Use {@link SpinnerHandle.wrap} to
79
+ * ensure cleanup on both success and failure paths.
80
+ *
81
+ * @internal
82
+ */
83
+ declare class TTYSpinnerHandle implements SpinnerHandle {
84
+ private readonly write;
85
+ /** Whether the handle has been stopped (terminal state reached). */
86
+ private stopped;
87
+ /** Animation timer handle — cleared on any terminal method. */
88
+ private timer;
89
+ /** Current position in the braille frame sequence. */
90
+ private frameIndex;
91
+ /** Current spinner text (mutable via `update()`). */
92
+ private text;
93
+ constructor(text: string, write: WriteFn);
94
+ /** Render the current frame + text, overwriting the current line. */
95
+ private render;
96
+ /** Clear the animation timer, erase the line, and restore the cursor. */
97
+ private cleanup;
98
+ update(text: string): void;
99
+ succeed(text?: string): void;
100
+ fail(text?: string): void;
101
+ stop(): void;
102
+ wrap<T>(promise: Promise<T>, options?: {
103
+ readonly succeed?: string;
104
+ readonly fail?: string;
105
+ }): Promise<T>;
106
+ }
107
+ /**
108
+ * TTY progress handle — bar rendering with ANSI line overwrite.
109
+ *
110
+ * Supports two modes:
111
+ * - **Determinate** (`total` provided) — renders `[████░░░░░░] 40% label`,
112
+ * re-rendered on each `increment()` / `update()` call. No timer.
113
+ * - **Indeterminate** (`total` omitted) — renders a pulsing highlight that
114
+ * bounces across the bar via `setInterval`.
115
+ *
116
+ * Terminal methods (`done`, `fail`) are idempotent — calling any of them
117
+ * after the handle is already stopped is a no-op.
118
+ *
119
+ * @internal
120
+ */
121
+ declare class TTYProgressHandle implements ProgressHandle {
122
+ private readonly write;
123
+ /** Whether the handle has been stopped (terminal state reached). */
124
+ private stopped;
125
+ /** Animation timer for indeterminate mode — `undefined` in determinate mode. */
126
+ private timer;
127
+ /** Current progress value (units completed). */
128
+ private current;
129
+ /** Total units of work (`undefined` = indeterminate mode). */
130
+ private readonly total;
131
+ /** Label displayed alongside the bar. */
132
+ private readonly label;
133
+ /** Pulse position for indeterminate animation (bouncing highlight). */
134
+ private pulsePos;
135
+ /** Pulse direction: 1 = forward, -1 = backward (for bounce). */
136
+ private pulseDir;
137
+ constructor(opts: ProgressOptions, write: WriteFn);
138
+ /** Advance the indeterminate pulse position with bounce logic. */
139
+ private advancePulse;
140
+ /** Render the progress bar, overwriting the current line. */
141
+ private render;
142
+ /** Render a determinate bar: `[████░░░░░░] 40%`. */
143
+ private renderDeterminate;
144
+ /** Render an indeterminate bar: pulsing highlight bouncing across empty segments. */
145
+ private renderIndeterminate;
146
+ /** Clear the animation timer, erase the line, and restore the cursor. */
147
+ private cleanup;
148
+ increment(n?: number): void;
149
+ update(value: number): void;
150
+ done(text?: string): void;
151
+ fail(text?: string): void;
152
+ }
153
+ /**
154
+ * Spinner handle that records lifecycle events to a shared `ActivityEvent[]`.
155
+ *
156
+ * Used by `createCaptureOutput()` so testkit can assert on spinner behaviour
157
+ * without polluting stdout/stderr arrays. Terminal methods are idempotent.
158
+ *
159
+ * @internal
160
+ */
161
+ declare class CaptureSpinnerHandle implements SpinnerHandle {
162
+ private readonly events;
163
+ /** Whether the handle has been stopped (terminal state reached). */
164
+ private stopped;
165
+ constructor(text: string, events: ActivityEvent[]);
166
+ update(text: string): void;
167
+ succeed(text?: string): void;
168
+ fail(text?: string): void;
169
+ stop(): void;
170
+ wrap<T>(promise: Promise<T>, options?: {
171
+ readonly succeed?: string;
172
+ readonly fail?: string;
173
+ }): Promise<T>;
174
+ }
175
+ /**
176
+ * Progress handle that records lifecycle events to a shared `ActivityEvent[]`.
177
+ *
178
+ * Used by `createCaptureOutput()` so testkit can assert on progress behaviour
179
+ * without polluting stdout/stderr arrays. Terminal methods are idempotent.
180
+ *
181
+ * @internal
182
+ */
183
+ declare class CaptureProgressHandle implements ProgressHandle {
184
+ private readonly events;
185
+ /** Whether the handle has been stopped (terminal state reached). */
186
+ private stopped;
187
+ constructor(opts: ProgressOptions, events: ActivityEvent[]);
188
+ increment(n?: number): void;
189
+ update(value: number): void;
190
+ done(text?: string): void;
191
+ fail(text?: string): void;
192
+ }
193
+ //#endregion
194
+ export { CaptureProgressHandle, CaptureSpinnerHandle, StaticProgressHandle, StaticSpinnerHandle, TTYProgressHandle, TTYSpinnerHandle, noopProgressHandle, noopSpinnerHandle };
@@ -0,0 +1 @@
1
+ import{writeLine as e}from"./writer.mjs";const t={update(){},succeed(){},fail(){},stop(){},wrap(e){return e}},n={increment(){},update(){},done(){},fail(){}};var r=class{stopped=!1;constructor(t,n){this.write=n,e(n,t)}update(e){}succeed(t){this.stopped||(this.stopped=!0,t!==void 0&&e(this.write,t))}fail(t){this.stopped||(this.stopped=!0,t!==void 0&&e(this.write,t))}stop(){this.stopped||=!0}async wrap(e,t){try{let n=await e;return this.succeed(t?.succeed),n}catch(e){throw this.fail(t?.fail),e}}},i=class{stopped=!1;constructor(t,n){this.write=n,t!==void 0&&e(n,t)}increment(e){}update(e){}done(t){this.stopped||(this.stopped=!0,t!==void 0&&e(this.write,t))}fail(t){this.stopped||(this.stopped=!0,t!==void 0&&e(this.write,t))}};const a=`\x1B[?25l`,o=`\x1B[?25h`,s=`\x1B[2K`,c=[`⠋`,`⠙`,`⠹`,`⠸`,`⠼`,`⠴`,`⠦`,`⠧`,`⠇`,`⠏`];var l=class{stopped=!1;timer;frameIndex=0;text;constructor(e,t){this.write=t,this.text=e,t(a),this.render(),this.timer=setInterval(()=>{this.frameIndex=(this.frameIndex+1)%c.length,this.render()},80)}render(){let e=c[this.frameIndex]??c[0];this.write(`\r${s}${e} ${this.text}`)}cleanup(){this.timer!==void 0&&(clearInterval(this.timer),this.timer=void 0),this.write(`\r${s}${o}`)}update(e){this.stopped||(this.text=e,this.render())}succeed(t){this.stopped||(this.stopped=!0,this.cleanup(),t!==void 0&&e(this.write,`✓ ${t}`))}fail(t){this.stopped||(this.stopped=!0,this.cleanup(),t!==void 0&&e(this.write,`✗ ${t}`))}stop(){this.stopped||(this.stopped=!0,this.cleanup())}async wrap(e,t){try{let n=await e;return this.succeed(t?.succeed),n}catch(e){throw this.fail(t?.fail),e}}},u=class{stopped=!1;timer;current=0;total;label;pulsePos=0;pulseDir=1;constructor(e,t){this.write=t,this.total=e.total,this.label=e.label??``,t(a),this.render(),this.total===void 0&&(this.timer=setInterval(()=>{this.advancePulse(),this.render()},80))}advancePulse(){this.pulsePos+=this.pulseDir,this.pulsePos+3>20?(this.pulseDir=-1,this.pulsePos=17):this.pulsePos<0&&(this.pulseDir=1,this.pulsePos=0)}render(){let e=this.total===void 0?this.renderIndeterminate():this.renderDeterminate(this.total),t=this.label.length>0?` ${this.label}`:``;this.write(`\r${s}${e}${t}`)}renderDeterminate(e){let t=e>0?Math.max(0,Math.min(this.current/e,1)):0,n=Math.round(t*20),r=20-n,i=Math.round(t*100);return`[${`█`.repeat(n)}${`░`.repeat(r)}] ${String(i)}%`}renderIndeterminate(){let e=``;for(let t=0;t<20;t++)e+=t>=this.pulsePos&&t<this.pulsePos+3?`█`:`░`;return`[${e}]`}cleanup(){this.timer!==void 0&&(clearInterval(this.timer),this.timer=void 0),this.write(`\r${s}${o}`)}increment(e){this.stopped||(this.current+=e??1,this.render())}update(e){this.stopped||(this.current=e,this.render())}done(t){this.stopped||(this.stopped=!0,this.cleanup(),t!==void 0&&e(this.write,`✓ ${t}`))}fail(t){this.stopped||(this.stopped=!0,this.cleanup(),t!==void 0&&e(this.write,`✗ ${t}`))}},d=class{stopped=!1;constructor(e,t){this.events=t,t.push({type:`spinner:start`,text:e})}update(e){this.stopped||this.events.push({type:`spinner:update`,text:e})}succeed(e){this.stopped||(this.stopped=!0,this.events.push({type:`spinner:succeed`,text:e??``}))}fail(e){this.stopped||(this.stopped=!0,this.events.push({type:`spinner:fail`,text:e??``}))}stop(){this.stopped||(this.stopped=!0,this.events.push({type:`spinner:stop`}))}async wrap(e,t){try{let n=await e;return this.succeed(t?.succeed),n}catch(e){throw this.fail(t?.fail),e}}},f=class{stopped=!1;constructor(e,t){this.events=t,t.push({type:`progress:start`,label:e.label??``,total:e.total})}increment(e){this.stopped||this.events.push({type:`progress:increment`,delta:e??1})}update(e){this.stopped||this.events.push({type:`progress:update`,value:e})}done(e){this.stopped||(this.stopped=!0,this.events.push({type:`progress:done`,text:e}))}fail(e){this.stopped||(this.stopped=!0,this.events.push({type:`progress:fail`,text:e}))}};export{f as CaptureProgressHandle,d as CaptureSpinnerHandle,i as StaticProgressHandle,r as StaticSpinnerHandle,u as TTYProgressHandle,l as TTYSpinnerHandle,n as noopProgressHandle,t as noopSpinnerHandle};