@kjanat/dreamcli 4.0.0-rc.3 → 4.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (212) hide show
  1. package/README.md +5 -7
  2. package/dist/{runtime/adapter.d.mts → adapter-D0hbBNVB.d.mts} +2 -4
  3. package/dist/completion-D4mz6axB.mjs +6 -0
  4. package/dist/completion.d.mts +90 -0
  5. package/dist/completion.mjs +1 -0
  6. package/dist/config-B9ddC-Kb.mjs +1 -0
  7. package/dist/config.d.mts +2 -0
  8. package/dist/config.mjs +1 -0
  9. package/dist/core-Cp2w8vRq.mjs +17 -0
  10. package/dist/index-BziI2aKc.d.mts +5440 -0
  11. package/dist/index-DOfClfYR.d.mts +370 -0
  12. package/dist/index-DWsnGZlx.d.mts +831 -0
  13. package/dist/{core/cli/index.d.mts → index-DXROeDPC.d.mts} +116 -57
  14. package/dist/index-DndPmT8J.d.mts +275 -0
  15. package/dist/{core/json-schema/index.d.mts → index-DyoaS234.d.mts} +43 -34
  16. package/dist/index.d.mts +190 -41
  17. package/dist/index.mjs +1 -26
  18. package/dist/json-schema-C9SzZ7jY.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,44 +0,0 @@
1
- import { ResolutionProvenance } from "../schema/provenance.mjs";
2
- import { CommandSchema } from "../schema/command.mjs";
3
- import "../schema/index.mjs";
4
- import { ParseResult } from "../parse/index.mjs";
5
- import { DeprecationWarning, ResolutionProvenanceRecord, ResolveOptions, ResolveResult } from "./contracts.mjs";
6
- //#region src/core/resolve/index.d.ts
7
- /**
8
- * Resolve parsed values against a command schema.
9
- *
10
- * Low-level API: most applications should rely on `cli().run()`, `.execute()`,
11
- * or `runCommand()`, which already call {@linkcode resolve} at the right time.
12
- * Reach for this function when testing precedence rules directly or building
13
- * custom execution flows around {@linkcode CommandSchema}.
14
- *
15
- * Resolution order:
16
- * 1. CLI parsed value (from {@linkcode ParseResult})
17
- * 2. Stdin (from {@linkcode ResolveOptions.stdinData}, if the input declares `stdin`)
18
- * 3. Env variable (from {@linkcode ResolveOptions.env}, if the input declares `envVar`)
19
- * 4. Config value (from {@linkcode ResolveOptions.config}, if the input declares `configPath`)
20
- * 5. Prompt (from {@linkcode ResolveOptions.prompter}, if the input declares `prompt`)
21
- * 6. Default value (from schema)
22
- *
23
- * After resolution, validates that all required flags and args have
24
- * a value. Collects **all** validation errors before throwing, so the
25
- * user sees every missing field at once.
26
- *
27
- * @param schema - The command schema defining flags and args
28
- * @param parsed - Raw parsed values from the parser
29
- * @param options - External state for the resolution chain
30
- * @returns Fully resolved flag and arg values
31
- * @throws {@linkcode ValidationError} if any required flag or arg is missing,
32
- * or if an env/config value fails coercion
33
- *
34
- * @example
35
- * ```ts
36
- * const parsed = parse(deploy.schema, ['production']);
37
- * const resolved = await resolve(deploy.schema, parsed, {
38
- * env: { DEPLOY_REGION: 'eu' },
39
- * });
40
- * ```
41
- */
42
- declare function resolve(schema: CommandSchema, parsed: ParseResult, options?: ResolveOptions): Promise<ResolveResult>;
43
- //#endregion
44
- export { type DeprecationWarning, type ResolutionProvenance, type ResolutionProvenanceRecord, type ResolveOptions, type ResolveResult, resolve };
@@ -1,123 +0,0 @@
1
- import { isValidationError } from "../errors/index.mjs";
2
- import { collectValidationErrors, isNonEmpty, throwAggregatedErrors } from "./errors.mjs";
3
- import { resolveFlags } from "./flags.mjs";
4
- import { resolveArgs } from "./args.mjs";
5
- import { applyStandardValidators } from "./standard.mjs";
6
- //#region src/core/resolve/index.ts
7
- /**
8
- * Resolution chain: CLI -> stdin -> env -> config -> prompt -> default.
9
- *
10
- * Flags and args walk the same ordered stages. An explicit `-` is CLI-sourced
11
- * with bytes from stdin and keeps CLI precedence; the `stdin` stage is the
12
- * implicit fallback an absent input takes before the environment.
13
- *
14
- * The resolver takes raw {@linkcode ParseResult} (from the parser) and a
15
- * {@linkcode CommandSchema}, applies the resolution chain, and validates
16
- * that all required flags/args are present. On success it returns a
17
- * {@linkcode ResolveResult} with fully resolved values; on failure it throws
18
- * {@linkcode ValidationError}.
19
- *
20
- * @module dreamcli/core/resolve
21
- */
22
- /**
23
- * Resolve parsed values against a command schema.
24
- *
25
- * Low-level API: most applications should rely on `cli().run()`, `.execute()`,
26
- * or `runCommand()`, which already call {@linkcode resolve} at the right time.
27
- * Reach for this function when testing precedence rules directly or building
28
- * custom execution flows around {@linkcode CommandSchema}.
29
- *
30
- * Resolution order:
31
- * 1. CLI parsed value (from {@linkcode ParseResult})
32
- * 2. Stdin (from {@linkcode ResolveOptions.stdinData}, if the input declares `stdin`)
33
- * 3. Env variable (from {@linkcode ResolveOptions.env}, if the input declares `envVar`)
34
- * 4. Config value (from {@linkcode ResolveOptions.config}, if the input declares `configPath`)
35
- * 5. Prompt (from {@linkcode ResolveOptions.prompter}, if the input declares `prompt`)
36
- * 6. Default value (from schema)
37
- *
38
- * After resolution, validates that all required flags and args have
39
- * a value. Collects **all** validation errors before throwing, so the
40
- * user sees every missing field at once.
41
- *
42
- * @param schema - The command schema defining flags and args
43
- * @param parsed - Raw parsed values from the parser
44
- * @param options - External state for the resolution chain
45
- * @returns Fully resolved flag and arg values
46
- * @throws {@linkcode ValidationError} if any required flag or arg is missing,
47
- * or if an env/config value fails coercion
48
- *
49
- * @example
50
- * ```ts
51
- * const parsed = parse(deploy.schema, ['production']);
52
- * const resolved = await resolve(deploy.schema, parsed, {
53
- * env: { DEPLOY_REGION: 'eu' },
54
- * });
55
- * ```
56
- */
57
- async function resolve(schema, parsed, options) {
58
- const deprecations = [];
59
- const flagProvenance = provenanceRecord();
60
- const argProvenance = provenanceRecord();
61
- const shared = {
62
- env: options?.env ?? {},
63
- config: options?.config ?? {},
64
- stdinData: options?.stdinData,
65
- prompter: options?.prompter,
66
- deprecations,
67
- stat: options?.stat,
68
- mkdir: options?.mkdir
69
- };
70
- let flags = {};
71
- let args = {};
72
- const errors = [];
73
- try {
74
- flags = await resolveFlags(schema.flags, parsed.flags, {
75
- ...shared,
76
- interactive: schema.interactive,
77
- provenance: flagProvenance
78
- });
79
- } catch (error) {
80
- if (!isValidationError(error)) throw error;
81
- errors.push(...collectValidationErrors(error));
82
- }
83
- try {
84
- args = await resolveArgs(schema.args, parsed.args, {
85
- ...shared,
86
- provenance: argProvenance
87
- });
88
- } catch (error) {
89
- if (!isValidationError(error)) throw error;
90
- errors.push(...collectValidationErrors(error));
91
- }
92
- const validated = await applyStandardValidators(schema, flags, args, {
93
- flags: flagProvenance,
94
- args: argProvenance
95
- });
96
- flags = validated.flags;
97
- args = validated.args;
98
- errors.push(...validated.errors);
99
- if (isNonEmpty(errors)) throwAggregatedErrors(errors);
100
- return {
101
- flags,
102
- args,
103
- deprecations,
104
- provenance: {
105
- flags: flagProvenance,
106
- args: argProvenance
107
- }
108
- };
109
- }
110
- /**
111
- * An empty per-surface provenance record.
112
- *
113
- * A handler reads this record by input name, and an input that resolved nothing
114
- * must read back as `undefined`. A prototype would answer a name such as
115
- * `toString` with an inherited method instead.
116
- *
117
- * @returns A record with no prototype.
118
- */
119
- function provenanceRecord() {
120
- return Object.create(null);
121
- }
122
- //#endregion
123
- export { resolve };
@@ -1,48 +0,0 @@
1
- import { ValidationError } from "../errors/index.mjs";
2
- import { PathChecks } from "../schema/value-parsers.mjs";
3
- import "../schema/index.mjs";
4
- //#region src/core/resolve/path-checks.d.ts
5
- /**
6
- * Filesystem probe injected by the caller for path checks.
7
- *
8
- * Returns what exists at the path, or `null` when nothing does.
9
- */
10
- type StatFn = (path: string) => Promise<'file' | 'directory' | null>;
11
- /** Recursive directory creation injected by the caller for `create` checks. */
12
- type MkdirFn = (path: string) => Promise<void>;
13
- /** Which surface declared the path, and under what name. */
14
- type PathCheckSubject = {
15
- readonly kind: 'flag';
16
- readonly name: string;
17
- } | {
18
- readonly kind: 'arg';
19
- readonly name: string;
20
- };
21
- /**
22
- * Check a resolved path value against its declared filesystem expectations.
23
- *
24
- * @param subject - The flag or arg the value belongs to.
25
- * @param value - The resolved path.
26
- * @param checks - Expectations declared by `flag.path()` / `arg.path()`.
27
- * @param stat - Filesystem probe.
28
- * @param mkdir - Recursive directory creation, when the caller supplies one.
29
- * @param echo - Whether the source permits quoting the path, per
30
- * `redaction.ts`. A path from stdin, env, config, prompt, or a default is
31
- * quoted as `<redacted>` and omitted from `details`.
32
- * @returns `undefined` when the path satisfies the checks, or a
33
- * {@link ValidationError} with code `'CONSTRAINT_VIOLATED'` otherwise.
34
- */
35
- declare function validatePathChecks(subject: PathCheckSubject, value: string, checks: PathChecks, stat: StatFn, mkdir: MkdirFn | undefined, echo: boolean): Promise<ValidationError | undefined>;
36
- /**
37
- * List the path strings a resolved value carries.
38
- *
39
- * Path checks belong to the element, so a collection is checked entry by entry:
40
- * an array yields its string elements and a record its string values. A value
41
- * of another type belongs to another codec and is skipped.
42
- *
43
- * @param value - The resolved flag or arg value.
44
- * @returns Every path string to check, possibly none.
45
- */
46
- declare function pathValuesOf(value: unknown): readonly string[];
47
- //#endregion
48
- export { type MkdirFn, type PathCheckSubject, type StatFn, pathValuesOf, validatePathChecks };
@@ -1,102 +0,0 @@
1
- import { ValidationError } from "../errors/index.mjs";
2
- import { REDACTED } from "./redaction.mjs";
3
- //#region src/core/resolve/path-checks.ts
4
- /**
5
- * Internal post-resolution filesystem checks for `flag.path()` and `arg.path()`.
6
- *
7
- * The checks run after a value has been resolved, whatever source produced it
8
- * (CLI, env, config, prompt, stdin, or default), through the caller-injected
9
- * probe so `src/core` stays free of platform I/O. Flags and args share the
10
- * checks and differ only in how the subject is named.
11
- *
12
- * @module dreamcli/core/resolve/path-checks
13
- * @internal
14
- */
15
- /** How a subject reads inside a sentence: `flag --out` or `argument <out>`. */
16
- function subjectLabel(subject) {
17
- return subject.kind === "flag" ? `flag --${subject.name}` : `argument <${subject.name}>`;
18
- }
19
- /** How a subject is spelled on the command line: `--out` or `<out>`. */
20
- function subjectReference(subject) {
21
- return subject.kind === "flag" ? `--${subject.name}` : `<${subject.name}>`;
22
- }
23
- /** The key naming the subject in error details: `flag` or `arg`. */
24
- function subjectDetails(subject) {
25
- return subject.kind === "flag" ? { flag: subject.name } : { arg: subject.name };
26
- }
27
- /**
28
- * Check a resolved path value against its declared filesystem expectations.
29
- *
30
- * @param subject - The flag or arg the value belongs to.
31
- * @param value - The resolved path.
32
- * @param checks - Expectations declared by `flag.path()` / `arg.path()`.
33
- * @param stat - Filesystem probe.
34
- * @param mkdir - Recursive directory creation, when the caller supplies one.
35
- * @param echo - Whether the source permits quoting the path, per
36
- * `redaction.ts`. A path from stdin, env, config, prompt, or a default is
37
- * quoted as `<redacted>` and omitted from `details`.
38
- * @returns `undefined` when the path satisfies the checks, or a
39
- * {@link ValidationError} with code `'CONSTRAINT_VIOLATED'` otherwise.
40
- */
41
- async function validatePathChecks(subject, value, checks, stat, mkdir, echo) {
42
- const label = subjectLabel(subject);
43
- const reference = subjectReference(subject);
44
- const details = subjectDetails(subject);
45
- const quoted = echo ? value : REDACTED;
46
- const reported = echo ? { value } : {};
47
- const found = await stat(value);
48
- if (found === null) {
49
- if (checks.create && mkdir !== void 0) try {
50
- await mkdir(value);
51
- return;
52
- } catch (error) {
53
- return new ValidationError(`Failed to create directory '${quoted}' for ${label}: ${error instanceof Error ? error.message : String(error)}`, {
54
- code: "CONSTRAINT_VIOLATED",
55
- details: {
56
- ...details,
57
- ...reported,
58
- constraint: "create"
59
- },
60
- suggest: `Provide a creatable or existing directory path for ${reference}`
61
- });
62
- }
63
- if (!checks.mustExist) return void 0;
64
- return new ValidationError(`Path '${quoted}' for ${label} does not exist`, {
65
- code: "CONSTRAINT_VIOLATED",
66
- details: {
67
- ...details,
68
- ...reported,
69
- constraint: "mustExist"
70
- },
71
- suggest: `Provide an existing path for ${reference}`
72
- });
73
- }
74
- if (checks.type !== void 0 && found !== checks.type) return new ValidationError(`Path '${quoted}' for ${label} is a ${found}, expected a ${checks.type}`, {
75
- code: "CONSTRAINT_VIOLATED",
76
- details: {
77
- ...details,
78
- ...reported,
79
- constraint: "pathType",
80
- expected: checks.type
81
- },
82
- suggest: `Provide a ${checks.type} path for ${reference}`
83
- });
84
- }
85
- /**
86
- * List the path strings a resolved value carries.
87
- *
88
- * Path checks belong to the element, so a collection is checked entry by entry:
89
- * an array yields its string elements and a record its string values. A value
90
- * of another type belongs to another codec and is skipped.
91
- *
92
- * @param value - The resolved flag or arg value.
93
- * @returns Every path string to check, possibly none.
94
- */
95
- function pathValuesOf(value) {
96
- if (typeof value === "string") return [value];
97
- if (Array.isArray(value)) return value.filter((entry) => typeof entry === "string");
98
- if (typeof value === "object" && value !== null) return Object.values(value).filter((entry) => typeof entry === "string");
99
- return [];
100
- }
101
- //#endregion
102
- export { pathValuesOf, validatePathChecks };
@@ -1,13 +0,0 @@
1
- import { ResolutionProvenance } from "../schema/provenance.mjs";
2
- //#region src/core/resolve/redaction.d.ts
3
- /** What a diagnostic prints in place of a value it may not echo. */
4
- declare const REDACTED = "<redacted>";
5
- /**
6
- * Whether a diagnostic may quote the value a stage produced.
7
- *
8
- * @param source - Where the value came from, or `undefined` when unrecorded.
9
- * @returns `true` when the value is safe to echo.
10
- */
11
- declare function echoesValue(source: ResolutionProvenance | undefined): boolean;
12
- //#endregion
13
- export { REDACTED, echoesValue };
@@ -1,14 +0,0 @@
1
- //#region src/core/resolve/redaction.ts
2
- /** What a diagnostic prints in place of a value it may not echo. */
3
- const REDACTED = "<redacted>";
4
- /**
5
- * Whether a diagnostic may quote the value a stage produced.
6
- *
7
- * @param source - Where the value came from, or `undefined` when unrecorded.
8
- * @returns `true` when the value is safe to echo.
9
- */
10
- function echoesValue(source) {
11
- return source !== void 0 && source.stage === "cli" && !("via" in source);
12
- }
13
- //#endregion
14
- export { REDACTED, echoesValue };
@@ -1,86 +0,0 @@
1
- import { ValidationError } from "../errors/index.mjs";
2
- import { ResolutionProvenance } from "../schema/provenance.mjs";
3
- import { DecodedSourceBinding, PromptSourceBinding, SourceBinding, StdinSourceBinding } from "../schema/source.mjs";
4
- import "./contracts.mjs";
5
- import { CliFinish, CoerceResult } from "./coerce.mjs";
6
- //#region src/core/resolve/stages.d.ts
7
- /** What the parser produced for one input in this invocation. */
8
- type CliValue = {
9
- readonly kind: 'value';
10
- readonly value: unknown;
11
- } | {
12
- readonly kind: 'dash';
13
- } | {
14
- readonly kind: 'absent';
15
- };
16
- /** The outcome of one stage, or of a whole walk. */
17
- type StageOutcome = {
18
- readonly kind: 'value';
19
- readonly value: unknown;
20
- readonly provenance: ResolutionProvenance;
21
- } | {
22
- readonly kind: 'error';
23
- readonly error: ValidationError;
24
- } | {
25
- readonly kind: 'absent';
26
- };
27
- /** A prompt run that either answered, failed, or declined to produce a value. */
28
- type PromptOutcome = {
29
- readonly ok: true;
30
- readonly value: unknown;
31
- } | {
32
- readonly ok: false;
33
- readonly error: ValidationError | undefined;
34
- };
35
- /** Everything one input contributes to its own resolution. */
36
- interface StageInput {
37
- /** What the parser produced for this input. */
38
- readonly cli: CliValue;
39
- /** Decode a raw value from a non-CLI source into the input's declared type. */
40
- readonly coerce: (binding: DecodedSourceBinding, raw: unknown) => CoerceResult;
41
- /**
42
- * Aggregate what the parser produced, splicing the stdin buffer into the
43
- * position each `-` occurrence holds.
44
- */
45
- readonly finishCli: (value: unknown, stdinData: string | null | undefined, stdin: StdinSourceBinding | undefined) => CliFinish;
46
- /** Run the prompt engine for this input. */
47
- readonly runPrompt: (binding: PromptSourceBinding) => Promise<PromptOutcome>;
48
- }
49
- /** External state every stage reads from. */
50
- interface StageState {
51
- /** Environment variable snapshot. */
52
- readonly env: Readonly<Record<string, string | undefined>>;
53
- /** Parsed config file contents. */
54
- readonly config: Readonly<Record<string, unknown>>;
55
- /** Pre-read stdin content, or `null`/`undefined` when nothing was piped. */
56
- readonly stdinData: string | null | undefined;
57
- /** Whether an interactive prompt engine is available. */
58
- readonly canPrompt: boolean;
59
- }
60
- /**
61
- * Walk the given bindings in order and return the first one that produces a
62
- * value or an error.
63
- *
64
- * A coercion failure at any sourced stage stops the walk, so a bad env value
65
- * never silently falls through to config.
66
- *
67
- * @param bindings - The sources to attempt, in precedence order.
68
- * @param input - The input being resolved.
69
- * @param state - External state the stages read.
70
- * @returns The winning stage's outcome, or `absent` when no stage produced one.
71
- */
72
- declare function runStages(bindings: readonly SourceBinding[], input: StageInput, state: StageState): Promise<StageOutcome>;
73
- /**
74
- * How the parser's record reads for one input.
75
- *
76
- * A `-` counts as the stdin selector only when the input declares a stdin
77
- * binding that reacts to it; otherwise it is the literal string the user typed.
78
- *
79
- * @param present - Whether the parser produced an own key for this input.
80
- * @param value - The parsed value.
81
- * @param bindings - The input's source list.
82
- * @returns What the CLI stage should do with it.
83
- */
84
- declare function readCliValue(present: boolean, value: unknown, bindings: readonly SourceBinding[]): CliValue;
85
- //#endregion
86
- export { type CliValue, type PromptOutcome, type StageInput, type StageOutcome, type StageState, readCliValue, runStages };
@@ -1,170 +0,0 @@
1
- import { stdinReadsOnDash, stdinReadsWhenMissing } from "../schema/stdin.mjs";
2
- import { stdinBindingOf } from "../schema/source.mjs";
3
- import { resolveConfigPath } from "./config.mjs";
4
- //#region src/core/resolve/stages.ts
5
- const ABSENT = { kind: "absent" };
6
- /**
7
- * Walk the given bindings in order and return the first one that produces a
8
- * value or an error.
9
- *
10
- * A coercion failure at any sourced stage stops the walk, so a bad env value
11
- * never silently falls through to config.
12
- *
13
- * @param bindings - The sources to attempt, in precedence order.
14
- * @param input - The input being resolved.
15
- * @param state - External state the stages read.
16
- * @returns The winning stage's outcome, or `absent` when no stage produced one.
17
- */
18
- async function runStages(bindings, input, state) {
19
- const stdin = stdinBindingOf(bindings);
20
- for (const binding of bindings) {
21
- const outcome = await runStage(binding, stdin, input, state);
22
- if (outcome.kind !== "absent") return outcome;
23
- }
24
- return ABSENT;
25
- }
26
- /** Attempt one binding. */
27
- async function runStage(binding, stdin, input, state) {
28
- switch (binding.stage) {
29
- case "cli": return cliStage(stdin, input, state);
30
- case "stdin": return stdinStage(binding, input, state);
31
- case "env": return envStage(binding, input, state);
32
- case "config": return configStage(binding, input, state);
33
- case "prompt": return promptStage(binding, input, state);
34
- case "default": return {
35
- kind: "value",
36
- value: binding.defaultValue,
37
- provenance: { stage: "default" }
38
- };
39
- }
40
- }
41
- /**
42
- * The CLI stage, including an explicit `-`.
43
- *
44
- * A `-` selects stdin while staying CLI-sourced, so it outranks every later
45
- * stage. When nothing was piped it produces no value and the walk continues,
46
- * leaving env, config, prompt, and the default reachable.
47
- */
48
- function cliStage(stdin, input, state) {
49
- if (input.cli.kind === "dash") {
50
- const buffer = state.stdinData;
51
- if (stdin === void 0 || typeof buffer !== "string") return ABSENT;
52
- return coerced(input, stdin, buffer, {
53
- stage: "cli",
54
- via: "stdin",
55
- trigger: "dash"
56
- });
57
- }
58
- if (input.cli.kind === "value") {
59
- const finished = input.finishCli(input.cli.value, state.stdinData, stdin);
60
- if (finished.kind === "absent") return ABSENT;
61
- if (finished.kind === "error") return {
62
- kind: "error",
63
- error: finished.error
64
- };
65
- return {
66
- kind: "value",
67
- value: finished.value,
68
- provenance: cliProvenance(finished.viaStdin)
69
- };
70
- }
71
- return ABSENT;
72
- }
73
- /**
74
- * Name where a finished CLI value came from.
75
- *
76
- * A collection that spliced the buffer at a `-` occurrence is CLI-sourced with
77
- * some of its bytes from stdin, which is the record an explicit `-` produces
78
- * for a scalar. A literal `-` an input without a stdin binding collected is a
79
- * value like any other.
80
- *
81
- * @param viaStdin - Whether finishing the CLI value read the stdin buffer.
82
- * @returns The provenance record for the CLI stage.
83
- */
84
- function cliProvenance(viaStdin) {
85
- return viaStdin ? {
86
- stage: "cli",
87
- via: "stdin",
88
- trigger: "dash"
89
- } : { stage: "cli" };
90
- }
91
- /** The implicit stdin fallback, taken only by an input argv left absent. */
92
- function stdinStage(binding, input, state) {
93
- if (!stdinReadsWhenMissing(binding)) return ABSENT;
94
- if (input.cli.kind !== "absent") return ABSENT;
95
- const buffer = state.stdinData;
96
- if (typeof buffer !== "string") return ABSENT;
97
- return coerced(input, binding, buffer, {
98
- stage: "stdin",
99
- via: "stdin",
100
- trigger: "fallback"
101
- });
102
- }
103
- /** The environment stage. */
104
- function envStage(binding, input, state) {
105
- const envVar = binding.envVar;
106
- const raw = Object.hasOwn(state.env, envVar) ? state.env[envVar] : void 0;
107
- if (raw === void 0) return ABSENT;
108
- return coerced(input, binding, raw, {
109
- stage: "env",
110
- envVar
111
- });
112
- }
113
- /** The config-file stage. */
114
- function configStage(binding, input, state) {
115
- const configPath = binding.configPath;
116
- const raw = resolveConfigPath(state.config, configPath);
117
- if (raw === void 0) return ABSENT;
118
- return coerced(input, binding, raw, {
119
- stage: "config",
120
- configPath
121
- });
122
- }
123
- /** The interactive stage. */
124
- async function promptStage(binding, input, state) {
125
- if (!state.canPrompt) return ABSENT;
126
- const result = await input.runPrompt(binding);
127
- if (result.ok) return {
128
- kind: "value",
129
- value: result.value,
130
- provenance: { stage: "prompt" }
131
- };
132
- return result.error === void 0 ? ABSENT : {
133
- kind: "error",
134
- error: result.error
135
- };
136
- }
137
- /** Decode a raw value and attach the stage's provenance on success. */
138
- function coerced(input, binding, raw, provenance) {
139
- const result = input.coerce(binding, raw);
140
- return result.ok ? {
141
- kind: "value",
142
- value: result.value,
143
- provenance
144
- } : {
145
- kind: "error",
146
- error: result.error
147
- };
148
- }
149
- /**
150
- * How the parser's record reads for one input.
151
- *
152
- * A `-` counts as the stdin selector only when the input declares a stdin
153
- * binding that reacts to it; otherwise it is the literal string the user typed.
154
- *
155
- * @param present - Whether the parser produced an own key for this input.
156
- * @param value - The parsed value.
157
- * @param bindings - The input's source list.
158
- * @returns What the CLI stage should do with it.
159
- */
160
- function readCliValue(present, value, bindings) {
161
- if (!present || value === void 0) return { kind: "absent" };
162
- const stdin = stdinBindingOf(bindings);
163
- if (value === "-" && stdin !== void 0 && stdinReadsOnDash(stdin)) return { kind: "dash" };
164
- return {
165
- kind: "value",
166
- value
167
- };
168
- }
169
- //#endregion
170
- export { readCliValue, runStages };
@@ -1,26 +0,0 @@
1
- import { ValidationError } from "../errors/index.mjs";
2
- import { CommandSchema } from "../schema/command.mjs";
3
- import "../schema/index.mjs";
4
- import { ResolutionProvenanceRecord } from "./contracts.mjs";
5
- //#region src/core/resolve/standard.d.ts
6
- /** Resolved values after the Standard Schema pass, plus any issues found. */
7
- interface StandardValidationResult {
8
- readonly flags: Readonly<Record<string, unknown>>;
9
- readonly args: Readonly<Record<string, unknown>>;
10
- readonly errors: readonly ValidationError[];
11
- }
12
- /**
13
- * Validate resolved flag and arg values against any attached Standard Schema
14
- * validators. Values without a validator, or resolved to `undefined`, pass
15
- * through untouched.
16
- *
17
- * @param schema - The command schema carrying per-flag/arg validators.
18
- * @param flags - Resolved flag values, keyed by flag name.
19
- * @param args - Resolved arg values, keyed by arg name.
20
- * @param provenance - Which stage produced each value, read for redaction.
21
- * @returns The (possibly transformed) values and any constraint violations.
22
- * @internal
23
- */
24
- declare function applyStandardValidators(schema: CommandSchema, flags: Readonly<Record<string, unknown>>, args: Readonly<Record<string, unknown>>, provenance: ResolutionProvenanceRecord): Promise<StandardValidationResult>;
25
- //#endregion
26
- export { applyStandardValidators };