@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,23 +0,0 @@
1
- import { CompletionOptions } from "./shared.mjs";
2
- import { CLISchema } from "../../cli/index.mjs";
3
- //#region src/core/completion/shells/zsh.d.ts
4
- /**
5
- * Generate a zsh completion script for the CLI.
6
- *
7
- * Use this when you want a zsh-specific script directly rather than routing
8
- * through {@link generateCompletion}. The generated script is compatible with
9
- * zsh's normal `#compdef` / `fpath` loading flow.
10
- *
11
- * @param schema - The CLI schema.
12
- * @param options - Optional generator configuration.
13
- * @returns A complete zsh completion script.
14
- *
15
- * @example
16
- * ```ts
17
- * const script = generateZshCompletion(app.schema);
18
- * // install with: mycli completions zsh > "${fpath[1]}/_mycli"
19
- * ```
20
- */
21
- declare function generateZshCompletion(schema: CLISchema, options?: CompletionOptions): string;
22
- //#endregion
23
- export { generateZshCompletion };
@@ -1,256 +0,0 @@
1
- import { CLIError } from "../../errors/index.mjs";
2
- import { getFlagAliasNames } from "../../schema/flag.mjs";
3
- import { flagExpectsValue } from "../../parse/index.mjs";
4
- import { getVisibleNegatedName, quoteShellArg, resolveRootCompletionSurface, sanitizeShellIdentifier, versionTag, walkCommandTree } from "./shared.mjs";
5
- import { resolvePlainHelpDescription } from "../../help/theme.mjs";
6
- //#region src/core/completion/shells/zsh.ts
7
- /**
8
- * Generate a zsh completion script for the CLI.
9
- *
10
- * Use this when you want a zsh-specific script directly rather than routing
11
- * through {@link generateCompletion}. The generated script is compatible with
12
- * zsh's normal `#compdef` / `fpath` loading flow.
13
- *
14
- * @param schema - The CLI schema.
15
- * @param options - Optional generator configuration.
16
- * @returns A complete zsh completion script.
17
- *
18
- * @example
19
- * ```ts
20
- * const script = generateZshCompletion(app.schema);
21
- * // install with: mycli completions zsh > "${fpath[1]}/_mycli"
22
- * ```
23
- */
24
- function generateZshCompletion(schema, options) {
25
- const prefix = options?.functionPrefix ?? schema.name;
26
- const funcName = `_${sanitizeShellIdentifier(prefix)}`;
27
- const rootSurface = resolveRootCompletionSurface(schema, options?.rootMode);
28
- const visibleCommands = rootSurface.visibleCommands;
29
- const nodes = walkCommandTree(visibleCommands);
30
- const lines = [];
31
- lines.push(`#compdef ${quoteShellArg(schema.name)}`);
32
- lines.push(`# Zsh completion for ${schema.name}`);
33
- lines.push(`# Generated by ${versionTag()}`);
34
- lines.push("#");
35
- lines.push(`# Usage: source <(${schema.name} completions zsh)`);
36
- lines.push("#");
37
- lines.push("# Install permanently:");
38
- lines.push(`# ${schema.name} completions zsh > "\${fpath[1]}/_${schema.name}"`);
39
- lines.push("# # Then restart your shell");
40
- lines.push("");
41
- const groupNodes = nodes.filter((n) => n.children.length > 0);
42
- const leafNodes = nodes.filter((n) => n.children.length === 0);
43
- for (const node of leafNodes) {
44
- if (node.path.length < 2) continue;
45
- emitZshLeafFunction(lines, `${funcName}_${node.path.map(sanitizeShellIdentifier).join("_")}`, node);
46
- }
47
- const sortedGroups = [...groupNodes].sort((a, b) => b.path.length - a.path.length);
48
- for (const node of sortedGroups) emitZshGroupFunction(lines, `${funcName}_${node.path.map(sanitizeShellIdentifier).join("_")}`, funcName, node);
49
- lines.push(`${funcName}() {`);
50
- if (visibleCommands.length > 0) {
51
- lines.push(" local -a subcmds");
52
- lines.push(" local line state");
53
- lines.push("");
54
- const rootFlagSpecs = buildZshFlagSpecsFromFlags({
55
- ...rootSurface.rootFlags,
56
- ...rootSurface.includeDefaultFlags ? rootSurface.defaultFlags : {}
57
- });
58
- lines.push(" _arguments -C \\");
59
- for (const spec of rootFlagSpecs) lines.push(`\t\t${spec} \\`);
60
- lines.push(" '1: :->subcmd' \\");
61
- lines.push(" '*::arg:->args'");
62
- lines.push("");
63
- lines.push(" case \"$state\" in");
64
- lines.push(" subcmd)");
65
- lines.push(" subcmds=(");
66
- appendZshCommandCandidates(lines, visibleCommands, " ");
67
- lines.push(" )");
68
- lines.push(" _describe 'command' subcmds");
69
- lines.push(" ;;");
70
- lines.push(" args)");
71
- lines.push(" case \"$line[1]\" in");
72
- for (const cmd of visibleCommands) {
73
- const allNames = [cmd.name, ...cmd.aliases].map(escapeZshCasePatternValue);
74
- const childCommands = cmd.commands.filter((c) => !c.hidden);
75
- lines.push(`\t\t\t\t${allNames.join("|")})`);
76
- if (childCommands.length > 0) {
77
- const helperName = `${funcName}_${sanitizeShellIdentifier(cmd.name)}`;
78
- lines.push(`\t\t\t\t\t${helperName}`);
79
- } else {
80
- const node = nodes.find((n) => n.path.length === 1 && n.schema.name === cmd.name);
81
- if (node === void 0) throw new CLIError(`Missing completion node for command '${cmd.name}'`, { code: "UNEXPECTED_ERROR" });
82
- const flagSpecs = buildZshFlagSpecsFromFlags(node.mergedFlags);
83
- if (flagSpecs.length > 0) {
84
- lines.push(" _arguments \\");
85
- for (let i = 0; i < flagSpecs.length; i++) {
86
- const trailing = i < flagSpecs.length - 1 ? " \\" : "";
87
- lines.push(`\t\t\t\t\t\t${flagSpecs[i]}${trailing}`);
88
- }
89
- }
90
- }
91
- lines.push(" ;;");
92
- }
93
- lines.push(" esac");
94
- lines.push(" ;;");
95
- lines.push(" esac");
96
- } else {
97
- const globalFlags = buildZshFlagSpecsFromFlags({
98
- ...rootSurface.rootFlags,
99
- ...rootSurface.includeDefaultFlags ? rootSurface.defaultFlags : {}
100
- });
101
- lines.push(" _arguments \\");
102
- for (let i = 0; i < globalFlags.length; i++) {
103
- const trailing = i < globalFlags.length - 1 ? " \\" : "";
104
- lines.push(`\t\t${globalFlags[i]}${trailing}`);
105
- }
106
- }
107
- lines.push("}");
108
- lines.push("");
109
- lines.push(`compdef ${funcName} ${quoteShellArg(schema.name)}`);
110
- lines.push("");
111
- return lines.join("\n");
112
- }
113
- /**
114
- * Emit a zsh helper function for a group command (has subcommands).
115
- *
116
- * Uses `_arguments -C` for its own flags plus subcommand dispatch.
117
- *
118
- * @internal
119
- */
120
- function emitZshGroupFunction(lines, helperName, rootFuncName, node) {
121
- lines.push(`${helperName}() {`);
122
- lines.push(" local -a subcmds");
123
- lines.push(" local line state");
124
- lines.push("");
125
- const flagSpecs = buildZshFlagSpecsFromFlags(node.mergedFlags);
126
- lines.push(" _arguments -C \\");
127
- for (const spec of flagSpecs) lines.push(`\t\t${spec} \\`);
128
- lines.push(" '1: :->subcmd' \\");
129
- lines.push(" '*::arg:->args'");
130
- lines.push("");
131
- lines.push(" case \"$state\" in");
132
- lines.push(" subcmd)");
133
- lines.push(" subcmds=(");
134
- appendZshCommandCandidates(lines, node.children, " ");
135
- lines.push(" )");
136
- lines.push(" _describe 'command' subcmds");
137
- lines.push(" ;;");
138
- lines.push(" args)");
139
- lines.push(" case \"$line[1]\" in");
140
- for (const child of node.children) {
141
- const allNames = [child.name, ...child.aliases].map(escapeZshCasePatternValue);
142
- const childFuncName = `${rootFuncName}_${[...node.path, child.name].map(sanitizeShellIdentifier).join("_")}`;
143
- lines.push(`\t\t\t\t${allNames.join("|")})`);
144
- lines.push(`\t\t\t\t\t${childFuncName}`);
145
- lines.push(" ;;");
146
- }
147
- lines.push(" esac");
148
- lines.push(" ;;");
149
- lines.push(" esac");
150
- lines.push("}");
151
- lines.push("");
152
- }
153
- /**
154
- * Emit a zsh helper function for a leaf command (no subcommands).
155
- *
156
- * Uses plain `_arguments` with the command's own flags plus propagated flags.
157
- *
158
- * @internal
159
- */
160
- function emitZshLeafFunction(lines, helperName, node) {
161
- const flagSpecs = buildZshFlagSpecsFromFlags(node.mergedFlags);
162
- lines.push(`${helperName}() {`);
163
- if (flagSpecs.length > 0) {
164
- lines.push(" _arguments \\");
165
- for (let i = 0; i < flagSpecs.length; i++) {
166
- const trailing = i < flagSpecs.length - 1 ? " \\" : "";
167
- lines.push(`\t\t${flagSpecs[i]}${trailing}`);
168
- }
169
- }
170
- lines.push("}");
171
- lines.push("");
172
- }
173
- function appendZshCommandCandidates(lines, commands, indent) {
174
- for (const command of commands) {
175
- const description = command.description ?? command.name;
176
- for (const alias of [command.name, ...command.aliases]) lines.push(`${indent}${quoteShellArg(`${alias}:${description}`)}`);
177
- }
178
- }
179
- /**
180
- * Escape a value for use in a zsh `case` pattern.
181
- *
182
- * Escapes glob metacharacters so arbitrary command and alias names match
183
- * literally rather than being interpreted as shell patterns.
184
- *
185
- * @internal
186
- */
187
- function escapeZshCasePatternValue(value) {
188
- if (/^[a-zA-Z0-9_\-.]+$/.test(value)) return value;
189
- return value.replace(/\\/g, "\\\\").replace(/'/g, "\\'").replace(/"/g, "\\\"").replace(/`/g, "\\`").replace(/\|/g, "\\|").replace(/\*/g, "\\*").replace(/\?/g, "\\?").replace(/\[/g, "\\[").replace(/\]/g, "\\]").replace(/\(/g, "\\(").replace(/\)/g, "\\)").replace(/\{/g, "\\{").replace(/\}/g, "\\}").replace(/\+/g, "\\+").replace(/!/g, "\\!").replace(/@/g, "\\@").replace(/#/g, "\\#").replace(/~/g, "\\~").replace(/\s/g, (match) => match === " " ? "\\ " : `\\${match}`);
190
- }
191
- /**
192
- * Escape a description for use inside a zsh `_arguments` flag spec.
193
- *
194
- * `]` closes the description segment, so it must be escaped. Backslashes are
195
- * escaped as well so descriptions with literal escapes remain stable.
196
- *
197
- * @internal
198
- */
199
- function escapeZshDescription(value) {
200
- return value.replace(/\\/g, "\\\\").replace(/\]/g, "\\]");
201
- }
202
- /**
203
- * Build `_arguments` flag spec strings from a merged flag record.
204
- *
205
- * Each flag produces one or more spec strings in zsh `_arguments` format:
206
- * - `'--name[description]'` for simple flags
207
- * - `'--name[description]:value:(v1 v2 v3)'` for enum flags
208
- * - `'(-s --name --alias)'{-s,--name,--alias}'[description]'` for flags with
209
- * visible aliases
210
- *
211
- * A visible negated spelling (`--no-name`) joins the flag's form group — the
212
- * two spellings are one logical flag, so completing one excludes the other.
213
- *
214
- * @internal
215
- */
216
- function buildZshFlagSpecsFromFlags(flags) {
217
- const specs = [];
218
- for (const [name, schema] of Object.entries(flags)) {
219
- const desc = escapeZshDescription(schema.description === void 0 ? name : resolvePlainHelpDescription(schema.description));
220
- const longFlag = `--${name}`;
221
- const shortFlags = getFlagAliasNames(schema, { kind: "short" }).map((alias) => `-${alias}`);
222
- const longAliases = getFlagAliasNames(schema, { kind: "long" }).map((alias) => `--${alias}`);
223
- const negated = getVisibleNegatedName(name, schema);
224
- const negatedForms = negated !== void 0 ? [`--${negated}`] : [];
225
- const allForms = [
226
- ...shortFlags,
227
- longFlag,
228
- ...longAliases,
229
- ...negatedForms
230
- ];
231
- let valuePart = "";
232
- if (!flagExpectsValue(schema)) {} else if (schema.kind === "enum" && schema.enumValues !== void 0) valuePart = `:value:(${schema.enumValues.map(escapeZshEnumValue).join(" ")})`;
233
- else valuePart = ":value:";
234
- if (allForms.length > 1) {
235
- const escapedForms = allForms.map(escapeZshCasePatternValue).join(",");
236
- specs.push(`${quoteShellArg(`(${allForms.join(" ")})`)}{${escapedForms}}${quoteShellArg(`[${desc}]${valuePart}`)}`);
237
- } else specs.push(quoteShellArg(`${longFlag}[${desc}]${valuePart}`));
238
- }
239
- return specs;
240
- }
241
- /**
242
- * Escape a single enum value for use inside a zsh `(v1 v2)` value list.
243
- *
244
- * Simple identifier-like values (matching `[a-zA-Z0-9_\-.]`) pass through
245
- * unescaped. Values containing spaces, quotes, backslashes, or parentheses
246
- * are escaped with backslash prefixes for each special character, which
247
- * is the standard mechanism within zsh parenthesized completion lists.
248
- *
249
- * @internal
250
- */
251
- function escapeZshEnumValue(value) {
252
- if (/^[a-zA-Z0-9_\-.]+$/.test(value)) return value;
253
- return value.replace(/\\/g, "\\\\").replace(/ /g, "\\ ").replace(/\(/g, "\\(").replace(/\)/g, "\\)");
254
- }
255
- //#endregion
256
- export { generateZshCompletion };
@@ -1,191 +0,0 @@
1
- import { RuntimeAdapter } from "../../runtime/adapter.mjs";
2
- import { ManifestDiscoveryOptions, PackageJsonAdapter, PackageJsonData, PackageRepository, PackageRepositoryUrlOptions, discoverManifest, inferCliName, packageRepositoryUrl } from "./package-json.mjs";
3
- //#region src/core/config/index.d.ts
4
- /**
5
- * Format loader — parses file content into a config object.
6
- *
7
- * Register custom config formats by providing file extensions and a parser.
8
- * Parsers may return any parsed value; {@link discoverConfig} validates that
9
- * the result is a plain object before feeding it into the resolution chain.
10
- *
11
- * Implementations should throw on syntax or shape errors; the caller wraps
12
- * those failures as {@link CLIError} with code `CONFIG_PARSE_ERROR`.
13
- */
14
- interface FormatLoader {
15
- /** File extensions this loader handles (without leading dot, e.g. `'toml'`). */
16
- readonly extensions: readonly string[];
17
- /**
18
- * Parse file content into a config value.
19
- *
20
- * Arrays, primitives, and `null` are allowed at this boundary so generic
21
- * parsers like `Bun.YAML.parse` can be passed directly. Those values are
22
- * still rejected by {@link discoverConfig}, which requires a plain object.
23
- */
24
- readonly parse: (content: string) => unknown;
25
- }
26
- /** Options for {@link discoverConfig}. */
27
- interface ConfigDiscoveryOptions {
28
- /**
29
- * Explicit config file path (`--config` override).
30
- * When provided, skips search — loads only this path.
31
- */
32
- readonly configPath?: string;
33
- /**
34
- * Additional format loaders (JSON is built-in).
35
- * Later loaders for the same extension win (allows override).
36
- */
37
- readonly loaders?: readonly FormatLoader[];
38
- /**
39
- * Custom search paths (absolute).
40
- * Replaces the default search paths when provided.
41
- * Probed in order; first found wins.
42
- */
43
- readonly searchPaths?: readonly string[];
44
- /**
45
- * Directory the project-scope ancestor walk starts from.
46
- * Anchors discovery to a location other than the process working
47
- * directory (e.g. the directory of a file an editor integration is
48
- * operating on).
49
- * @defaultValue `adapter.cwd`
50
- */
51
- readonly baseDir?: string;
52
- }
53
- /** Successful config discovery — file found and parsed. */
54
- interface ConfigFound {
55
- /** Discriminant — `true` indicates a config file was found and parsed successfully. */
56
- readonly found: true;
57
- /** Absolute path to the config file that was loaded. */
58
- readonly path: string;
59
- /** Parsed config data. */
60
- readonly data: Readonly<Record<string, unknown>>;
61
- /** File extension that determined the loader (e.g. `'json'`). */
62
- readonly format: string;
63
- }
64
- /** No config file found at any candidate path (not an error). */
65
- interface ConfigNotFound {
66
- /** Discriminant — `false` indicates no config file exists at any candidate path. */
67
- readonly found: false;
68
- }
69
- /** Discriminated result of config discovery. */
70
- type ConfigDiscoveryResult = ConfigFound | ConfigNotFound;
71
- /** Directory scopes feeding {@link buildConfigSearchPaths}. */
72
- interface ConfigSearchPathOptions {
73
- /** Directory the project-scope ancestor walk starts from. */
74
- readonly baseDir: string;
75
- /**
76
- * User-scope config roots, highest priority first
77
- * (XDG / AppData, plus `~/Library/Application Support` on macOS).
78
- */
79
- readonly userConfigDirs: readonly string[];
80
- /**
81
- * System-scope config roots (`/etc` on Linux and macOS).
82
- * @defaultValue `[]`
83
- */
84
- readonly systemConfigDirs?: readonly string[];
85
- /** Custom {@link FormatLoader}s whose extensions expand the search set. */
86
- readonly loaders?: readonly FormatLoader[];
87
- }
88
- /**
89
- * Build the default config search paths for an app.
90
- *
91
- * Advanced helper used by DreamCLI's config discovery. Most apps should call
92
- * `.config()` or {@link discoverConfig} instead of constructing search paths
93
- * manually. Exported for debugging, custom discovery flows, and help text.
94
- *
95
- * Search order (first match wins):
96
- * 1. Project scope — for `baseDir` and each ancestor directory up to the
97
- * filesystem root, nearest first:
98
- * 1. `{dir}/.{appName}.json` — dotfile
99
- * 2. `{dir}/{appName}.config.json` — explicit config
100
- * 3. `{dir}/.config/{appName}.json` — project `.config/` convention
101
- * 2. User scope — `{userConfigDir}/{appName}/config.json` for each entry of
102
- * `userConfigDirs`, in order.
103
- * 3. System scope — `{systemConfigDir}/{appName}/config.json` for each entry
104
- * of `systemConfigDirs`, in order.
105
- *
106
- * When custom {@link ConfigDiscoveryOptions.loaders | loaders} are registered,
107
- * each path pattern is repeated per supported extension (JSON always first).
108
- *
109
- * @param appName - CLI application name used to derive config filenames.
110
- * @param options - Directory scopes and loaders (see {@link ConfigSearchPathOptions}).
111
- * @returns Ordered list of candidate config file paths (first match wins).
112
- *
113
- * @example
114
- * ```ts
115
- * const paths = buildConfigSearchPaths('mycli', {
116
- * baseDir: '/repo/packages/app',
117
- * userConfigDirs: ['/home/me/.config'],
118
- * systemConfigDirs: ['/etc'],
119
- * });
120
- * ```
121
- */
122
- declare function buildConfigSearchPaths(appName: string, options: ConfigSearchPathOptions): readonly string[];
123
- /**
124
- * The subset of {@link RuntimeAdapter} needed for config discovery.
125
- *
126
- * Exported so custom hosts and tests can type the minimal adapter required by
127
- * {@link discoverConfig} without depending on the full runtime adapter shape.
128
- */
129
- type ConfigAdapter = Pick<RuntimeAdapter, 'readFile' | 'cwd' | 'configDir'> & Partial<Pick<RuntimeAdapter, 'userConfigDirs' | 'systemConfigDirs'>>;
130
- /**
131
- * Discover and load a config file.
132
- *
133
- * Low-level discovery helper behind `CLIBuilder.config()`. Most apps should
134
- * let the CLI runtime call this automatically; call it directly when testing
135
- * config behavior or building custom bootstrapping around {@linkcode RuntimeAdapter}.
136
- *
137
- * Pure function — all filesystem I/O flows through `adapter.readFile`.
138
- * Returns a discriminated union: `{ found: true, ... }` when a config
139
- * file was found and parsed, `{ found: false }` when no file exists.
140
- *
141
- * @throws {CLIError} code `CONFIG_NOT_FOUND` — explicit `configPath` doesn't exist
142
- * @throws {CLIError} code `CONFIG_PARSE_ERROR` — file exists but fails to parse
143
- * @throws {CLIError} code `CONFIG_UNKNOWN_FORMAT` — no loader for the file extension
144
- *
145
- * @example
146
- * ```ts
147
- * const result = await discoverConfig('mycli', adapter, {
148
- * loaders: [
149
- * configFormat(['yaml', 'yml'], Bun.YAML.parse),
150
- * configFormat(['toml'], Bun.TOML.parse),
151
- * ],
152
- * });
153
- * ```
154
- */
155
- declare function discoverConfig(appName: string, adapter: ConfigAdapter, options?: ConfigDiscoveryOptions): Promise<ConfigDiscoveryResult>;
156
- /**
157
- * Create a {@link FormatLoader} from extensions and a parse function.
158
- *
159
- * Convenience factory for config loading. It avoids manually constructing the
160
- * `{ extensions, parse }` object and makes intent clearer at call sites.
161
- *
162
- * Later loaders registered for the same extension override earlier ones. Any
163
- * error thrown by `parse` is wrapped by {@link discoverConfig} as
164
- * `CONFIG_PARSE_ERROR`.
165
- *
166
- * @param extensions - File extensions this loader handles (without dot, e.g. `'yaml'`).
167
- * @param parse - Parse function: takes file content string and returns a parsed config value.
168
- * @returns A {@link FormatLoader} ready to pass to {@link ConfigDiscoveryOptions.loaders}.
169
- *
170
- * @example
171
- * ```ts
172
- * import { cli, configFormat } from '@kjanat/dreamcli';
173
- * import { parse as parseYaml } from 'yaml';
174
- * import { parse as parseTOML } from '@iarna/toml';
175
- *
176
- * const yamlPackageLoader = configFormat(['yaml', 'yml'], parseYaml);
177
- * const tomlPackageLoader = configFormat(['toml'], parseTOML);
178
- * // Or with Bun's built-in parsers:
179
- * // const yamlLoader = configFormat(['yaml', 'yml'], Bun.YAML.parse);
180
- * // const tomlLoader = configFormat(['toml'], Bun.TOML.parse);
181
- *
182
- * cli('myapp')
183
- * .config('myapp')
184
- * .configLoader(yamlLoader)
185
- * .configLoader(tomlLoader)
186
- * .run();
187
- * ```
188
- */
189
- declare function configFormat(extensions: readonly string[], parse: (content: string) => unknown): FormatLoader;
190
- //#endregion
191
- export { type ConfigAdapter, type ConfigDiscoveryOptions, type ConfigDiscoveryResult, type ConfigFound, type ConfigNotFound, type ConfigSearchPathOptions, type FormatLoader, type ManifestDiscoveryOptions, type PackageJsonAdapter, type PackageJsonData, type PackageRepository, type PackageRepositoryUrlOptions, buildConfigSearchPaths, configFormat, discoverConfig, discoverManifest, inferCliName, packageRepositoryUrl };