@kjanat/dreamcli 3.0.0 → 4.0.0-rc.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 (147) hide show
  1. package/CHANGELOG.md +967 -1
  2. package/README.md +9 -3
  3. package/dist/core/cli/builtins.d.mts +47 -0
  4. package/dist/core/cli/builtins.mjs +135 -0
  5. package/dist/core/cli/compiled.d.mts +29 -0
  6. package/dist/core/cli/compiled.mjs +76 -0
  7. package/dist/core/cli/dispatch.d.mts +9 -85
  8. package/dist/core/cli/help-links.d.mts +2 -14
  9. package/dist/core/cli/index.d.mts +282 -101
  10. package/dist/core/cli/index.mjs +497 -264
  11. package/dist/core/cli/planner.d.mts +13 -86
  12. package/dist/core/cli/planner.mjs +47 -30
  13. package/dist/core/cli/plugin.d.mts +1 -1
  14. package/dist/core/cli/propagate.mjs +1 -1
  15. package/dist/core/cli/reserved-flags.d.mts +1 -0
  16. package/dist/core/cli/reserved-flags.mjs +158 -0
  17. package/dist/core/cli/root-help.d.mts +1 -47
  18. package/dist/core/cli/root-help.mjs +37 -47
  19. package/dist/core/cli/root-output-flags.d.mts +1 -0
  20. package/dist/core/cli/root-output-flags.mjs +169 -0
  21. package/dist/core/cli/root-surface.d.mts +1 -68
  22. package/dist/core/cli/root-surface.mjs +2 -2
  23. package/dist/core/cli/runtime-preflight.d.mts +1 -199
  24. package/dist/core/cli/runtime-preflight.mjs +67 -17
  25. package/dist/core/completion/index.d.mts +2 -2
  26. package/dist/core/completion/shells/bash.d.mts +0 -1
  27. package/dist/core/completion/shells/bash.mjs +2 -1
  28. package/dist/core/completion/shells/fish.d.mts +0 -1
  29. package/dist/core/completion/shells/fish.mjs +2 -1
  30. package/dist/core/completion/shells/powershell.d.mts +0 -1
  31. package/dist/core/completion/shells/powershell.mjs +2 -1
  32. package/dist/core/completion/shells/shared.d.mts +3 -114
  33. package/dist/core/completion/shells/shared.mjs +9 -39
  34. package/dist/core/completion/shells/zsh.d.mts +0 -1
  35. package/dist/core/completion/shells/zsh.mjs +2 -1
  36. package/dist/core/config/index.d.mts +3 -3
  37. package/dist/core/config/index.mjs +2 -2
  38. package/dist/core/config/package-json.d.mts +2 -33
  39. package/dist/core/config/package-json.mjs +1 -34
  40. package/dist/core/errors/index.d.mts +7 -7
  41. package/dist/core/execution/index.d.mts +1 -48
  42. package/dist/core/execution/index.mjs +42 -27
  43. package/dist/core/help/ansi.d.mts +0 -11
  44. package/dist/core/help/index.d.mts +3 -35
  45. package/dist/core/help/index.mjs +29 -6
  46. package/dist/core/help/theme.d.mts +1 -21
  47. package/dist/core/json-schema/index.d.mts +279 -10
  48. package/dist/core/json-schema/index.mjs +482 -237
  49. package/dist/core/json-schema/meta-descriptions.generated.d.mts +79 -7
  50. package/dist/core/json-schema/meta-descriptions.generated.mjs +40 -6
  51. package/dist/core/output/activity.d.mts +1 -193
  52. package/dist/core/output/activity.mjs +1 -1
  53. package/dist/core/output/bind.d.mts +1 -37
  54. package/dist/core/output/contracts.d.mts +7 -13
  55. package/dist/core/output/contracts.mjs +1 -1
  56. package/dist/core/output/display-value.d.mts +1 -19
  57. package/dist/core/output/index.d.mts +5 -187
  58. package/dist/core/output/index.mjs +44 -9
  59. package/dist/core/output/renderers.d.mts +1 -45
  60. package/dist/core/output/writer.d.mts +0 -1
  61. package/dist/core/parse/index.d.mts +27 -5
  62. package/dist/core/parse/index.mjs +350 -227
  63. package/dist/core/parse/occurrences.d.mts +89 -0
  64. package/dist/core/parse/occurrences.mjs +114 -0
  65. package/dist/core/prompt/index.d.mts +3 -3
  66. package/dist/core/read-flags/index.d.mts +150 -0
  67. package/dist/core/read-flags/index.mjs +217 -0
  68. package/dist/core/resolve/args.d.mts +35 -4
  69. package/dist/core/resolve/args.mjs +132 -55
  70. package/dist/core/resolve/coerce.d.mts +66 -9
  71. package/dist/core/resolve/coerce.mjs +834 -270
  72. package/dist/core/resolve/config.d.mts +1 -10
  73. package/dist/core/resolve/contracts.d.mts +67 -44
  74. package/dist/core/resolve/errors.mjs +29 -21
  75. package/dist/core/resolve/flags.d.mts +36 -9
  76. package/dist/core/resolve/flags.mjs +129 -151
  77. package/dist/core/resolve/index.d.mts +8 -6
  78. package/dist/core/resolve/index.mjs +51 -18
  79. package/dist/core/resolve/path-checks.d.mts +47 -0
  80. package/dist/core/resolve/path-checks.mjs +102 -0
  81. package/dist/core/resolve/redaction.d.mts +12 -0
  82. package/dist/core/resolve/redaction.mjs +14 -0
  83. package/dist/core/resolve/stages.d.mts +85 -0
  84. package/dist/core/resolve/stages.mjs +170 -0
  85. package/dist/core/resolve/standard.d.mts +1 -24
  86. package/dist/core/resolve/standard.mjs +141 -43
  87. package/dist/core/schema/activity.d.mts +16 -16
  88. package/dist/core/schema/arg.d.mts +849 -71
  89. package/dist/core/schema/arg.mjs +727 -54
  90. package/dist/core/schema/brand.d.mts +17 -0
  91. package/dist/core/schema/cardinality.d.mts +301 -0
  92. package/dist/core/schema/cardinality.mjs +514 -0
  93. package/dist/core/schema/command.d.mts +181 -112
  94. package/dist/core/schema/command.mjs +305 -42
  95. package/dist/core/schema/flag.d.mts +515 -173
  96. package/dist/core/schema/flag.mjs +576 -78
  97. package/dist/core/schema/index.d.mts +11 -8
  98. package/dist/core/schema/index.mjs +10 -0
  99. package/dist/core/schema/middleware.d.mts +15 -12
  100. package/dist/core/schema/number-constraints.d.mts +5 -5
  101. package/dist/core/schema/prompt.d.mts +4 -4
  102. package/dist/core/schema/provenance.d.mts +99 -0
  103. package/dist/core/schema/provenance.mjs +28 -0
  104. package/dist/core/schema/run.d.mts +21 -60
  105. package/dist/core/schema/source.d.mts +179 -0
  106. package/dist/core/schema/source.mjs +206 -0
  107. package/dist/core/schema/standard.d.mts +12 -19
  108. package/dist/core/schema/stdin.d.mts +87 -0
  109. package/dist/core/schema/stdin.mjs +91 -0
  110. package/dist/core/schema/string-constraints.d.mts +16 -5
  111. package/dist/core/schema/string-constraints.mjs +18 -1
  112. package/dist/core/schema/value-parsers.d.mts +81 -9
  113. package/dist/core/schema/value-parsers.mjs +19 -1
  114. package/dist/core/schema/value.d.mts +242 -0
  115. package/dist/core/schema/value.mjs +573 -0
  116. package/dist/core/testkit/index.d.mts +28 -3
  117. package/dist/core/testkit/index.mjs +40 -26
  118. package/dist/index.d.mts +21 -16
  119. package/dist/index.mjs +10 -6
  120. package/dist/runtime/adapter.d.mts +3 -3
  121. package/dist/runtime/deno.d.mts +3 -3
  122. package/dist/runtime/detect.d.mts +2 -2
  123. package/dist/runtime/node.d.mts +3 -3
  124. package/dist/runtime/paths.d.mts +1 -31
  125. package/dist/runtime.d.mts +4 -4
  126. package/dist/strings.d.mts +1 -16
  127. package/dist/testkit.d.mts +2 -2
  128. package/dist/testkit.mjs +1 -1
  129. package/dist/version.d.mts +0 -13
  130. package/dist/version.mjs +2 -2
  131. package/dreamcli.schema.json +368 -78
  132. package/examples/interactive.ts +6 -5
  133. package/package.json +10 -9
  134. package/skills/cli-creation/SKILL.md +196 -0
  135. package/skills/cli-creation/agents/openai.yaml +4 -0
  136. package/skills/cli-creation/assets/templates/multi-command.bun-test.ts.tpl +20 -0
  137. package/skills/cli-creation/assets/templates/multi-command.test.ts.tpl +20 -0
  138. package/skills/cli-creation/assets/templates/multi-command.ts.tpl +89 -0
  139. package/skills/cli-creation/assets/templates/single-command.bun-test.ts.tpl +29 -0
  140. package/skills/cli-creation/assets/templates/single-command.test.ts.tpl +29 -0
  141. package/skills/cli-creation/assets/templates/single-command.ts.tpl +47 -0
  142. package/skills/cli-creation/references/consumer-workflow.md +65 -0
  143. package/skills/cli-creation/references/pattern-cookbook.md +451 -0
  144. package/skills/cli-creation/references/runtime-notes.md +29 -0
  145. package/skills/cli-creation/scripts/scaffold_cli.py +360 -0
  146. package/dist/core/resolve/property.d.mts +0 -51
  147. package/dist/core/resolve/property.mjs +0 -53
@@ -1,7 +1,8 @@
1
- import { DeprecationWarning, ResolveOptions, ResolveResult } from "./contracts.mjs";
1
+ import { ResolutionProvenance } from "../schema/provenance.mjs";
2
2
  import { CommandSchema } from "../schema/command.mjs";
3
3
  import "../schema/index.mjs";
4
4
  import { ParseResult } from "../parse/index.mjs";
5
+ import { DeprecationWarning, ResolutionProvenanceRecord, ResolveOptions, ResolveResult } from "./contracts.mjs";
5
6
  //#region src/core/resolve/index.d.ts
6
7
  /**
7
8
  * Resolve parsed values against a command schema.
@@ -13,10 +14,11 @@ import { ParseResult } from "../parse/index.mjs";
13
14
  *
14
15
  * Resolution order:
15
16
  * 1. CLI parsed value (from {@linkcode ParseResult})
16
- * 2. Env variable (from {@linkcode ResolveOptions.env}, if flag declares `envVar`)
17
- * 3. Config value (from {@linkcode ResolveOptions.config}, if flag declares `configPath`)
18
- * 4. Prompt (from {@linkcode ResolveOptions.prompter}, if flag declares `prompt`)
19
- * 5. Default value (from schema)
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)
20
22
  *
21
23
  * After resolution, validates that all required flags and args have
22
24
  * a value. Collects **all** validation errors before throwing, so the
@@ -39,4 +41,4 @@ import { ParseResult } from "../parse/index.mjs";
39
41
  */
40
42
  declare function resolve(schema: CommandSchema, parsed: ParseResult, options?: ResolveOptions): Promise<ResolveResult>;
41
43
  //#endregion
42
- export { type DeprecationWarning, type ResolveOptions, type ResolveResult, resolve };
44
+ export { type DeprecationWarning, type ResolutionProvenance, type ResolutionProvenanceRecord, type ResolveOptions, type ResolveResult, resolve };
@@ -1,16 +1,15 @@
1
1
  import { isValidationError } from "../errors/index.mjs";
2
2
  import { collectValidationErrors, isNonEmpty, throwAggregatedErrors } from "./errors.mjs";
3
- import { resolveArgs } from "./args.mjs";
4
3
  import { resolveFlags } from "./flags.mjs";
4
+ import { resolveArgs } from "./args.mjs";
5
5
  import { applyStandardValidators } from "./standard.mjs";
6
6
  //#region src/core/resolve/index.ts
7
7
  /**
8
- * Resolution chain: CLI -> env -> config -> prompt -> default.
8
+ * Resolution chain: CLI -> stdin -> env -> config -> prompt -> default.
9
9
  *
10
- * v0.1 implemented: **CLI parsed value -> default value**.
11
- * v0.2 adds: **env variable resolution** and **config object resolution**
12
- * between CLI and default.
13
- * v0.3 adds: **prompt resolution** between config and default.
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.
14
13
  *
15
14
  * The resolver takes raw {@linkcode ParseResult} (from the parser) and a
16
15
  * {@linkcode CommandSchema}, applies the resolution chain, and validates
@@ -30,10 +29,11 @@ import { applyStandardValidators } from "./standard.mjs";
30
29
  *
31
30
  * Resolution order:
32
31
  * 1. CLI parsed value (from {@linkcode ParseResult})
33
- * 2. Env variable (from {@linkcode ResolveOptions.env}, if flag declares `envVar`)
34
- * 3. Config value (from {@linkcode ResolveOptions.config}, if flag declares `configPath`)
35
- * 4. Prompt (from {@linkcode ResolveOptions.prompter}, if flag declares `prompt`)
36
- * 5. Default value (from schema)
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
37
  *
38
38
  * After resolution, validates that all required flags and args have
39
39
  * a value. Collects **all** validation errors before throwing, so the
@@ -55,27 +55,44 @@ import { applyStandardValidators } from "./standard.mjs";
55
55
  * ```
56
56
  */
57
57
  async function resolve(schema, parsed, options) {
58
- const stdinData = options?.stdinData;
59
- const env = options?.env ?? {};
60
- const config = options?.config ?? {};
61
- const prompter = options?.prompter;
62
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
+ };
63
70
  let flags = {};
64
71
  let args = {};
65
72
  const errors = [];
66
73
  try {
67
- flags = await resolveFlags(schema.flags, parsed.flags, env, config, prompter, schema.interactive, deprecations, options?.stat, options?.mkdir);
74
+ flags = await resolveFlags(schema.flags, parsed.flags, {
75
+ ...shared,
76
+ interactive: schema.interactive,
77
+ provenance: flagProvenance
78
+ });
68
79
  } catch (error) {
69
80
  if (!isValidationError(error)) throw error;
70
81
  errors.push(...collectValidationErrors(error));
71
82
  }
72
83
  try {
73
- args = resolveArgs(schema.args, parsed.args, stdinData, env, deprecations);
84
+ args = await resolveArgs(schema.args, parsed.args, {
85
+ ...shared,
86
+ provenance: argProvenance
87
+ });
74
88
  } catch (error) {
75
89
  if (!isValidationError(error)) throw error;
76
90
  errors.push(...collectValidationErrors(error));
77
91
  }
78
- const validated = await applyStandardValidators(schema, flags, args);
92
+ const validated = await applyStandardValidators(schema, flags, args, {
93
+ flags: flagProvenance,
94
+ args: argProvenance
95
+ });
79
96
  flags = validated.flags;
80
97
  args = validated.args;
81
98
  errors.push(...validated.errors);
@@ -83,8 +100,24 @@ async function resolve(schema, parsed, options) {
83
100
  return {
84
101
  flags,
85
102
  args,
86
- deprecations
103
+ deprecations,
104
+ provenance: {
105
+ flags: flagProvenance,
106
+ args: argProvenance
107
+ }
87
108
  };
88
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
+ }
89
122
  //#endregion
90
123
  export { resolve };
@@ -0,0 +1,47 @@
1
+ import { PathChecks } from "../schema/value-parsers.mjs";
2
+ import "../schema/index.mjs";
3
+ //#region src/core/resolve/path-checks.d.ts
4
+ /**
5
+ * Filesystem probe injected by the caller for path checks.
6
+ *
7
+ * Returns what exists at the path, or `null` when nothing does.
8
+ */
9
+ type StatFn = (path: string) => Promise<"file" | "directory" | null>;
10
+ /** Recursive directory creation injected by the caller for `create` checks. */
11
+ type MkdirFn = (path: string) => Promise<void>;
12
+ /** Which surface declared the path, and under what name. */
13
+ type PathCheckSubject = {
14
+ readonly kind: "flag";
15
+ readonly name: string;
16
+ } | {
17
+ readonly kind: "arg";
18
+ readonly name: string;
19
+ };
20
+ /**
21
+ * Check a resolved path value against its declared filesystem expectations.
22
+ *
23
+ * @param subject - The flag or arg the value belongs to.
24
+ * @param value - The resolved path.
25
+ * @param checks - Expectations declared by `flag.path()` / `arg.path()`.
26
+ * @param stat - Filesystem probe.
27
+ * @param mkdir - Recursive directory creation, when the caller supplies one.
28
+ * @param echo - Whether the source permits quoting the path, per
29
+ * `redaction.ts`. A path from stdin, env, config, prompt, or a default is
30
+ * quoted as `<redacted>` and omitted from `details`.
31
+ * @returns `undefined` when the path satisfies the checks, or a
32
+ * {@link ValidationError} with code `'CONSTRAINT_VIOLATED'` otherwise.
33
+ */
34
+ declare function validatePathChecks(subject: PathCheckSubject, value: string, checks: PathChecks, stat: StatFn, mkdir: MkdirFn | undefined, echo: boolean): Promise<ValidationError | undefined>;
35
+ /**
36
+ * List the path strings a resolved value carries.
37
+ *
38
+ * Path checks belong to the element, so a collection is checked entry by entry:
39
+ * an array yields its string elements and a record its string values. A value
40
+ * of another type belongs to another codec and is skipped.
41
+ *
42
+ * @param value - The resolved flag or arg value.
43
+ * @returns Every path string to check, possibly none.
44
+ */
45
+ declare function pathValuesOf(value: unknown): readonly string[];
46
+ //#endregion
47
+ export { type MkdirFn, type PathCheckSubject, type StatFn, pathValuesOf, validatePathChecks };
@@ -0,0 +1,102 @@
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 };
@@ -0,0 +1,12 @@
1
+ //#region src/core/resolve/redaction.d.ts
2
+ /** What a diagnostic prints in place of a value it may not echo. */
3
+ declare 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
+ declare function echoesValue(source: ResolutionProvenance | undefined): boolean;
11
+ //#endregion
12
+ export { REDACTED, echoesValue };
@@ -0,0 +1,14 @@
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 };
@@ -0,0 +1,85 @@
1
+ import { ResolutionProvenance } from "../schema/provenance.mjs";
2
+ import { DecodedSourceBinding, PromptSourceBinding, SourceBinding, StdinSourceBinding } from "../schema/source.mjs";
3
+ import "./contracts.mjs";
4
+ import { CliFinish, CoerceResult } from "./coerce.mjs";
5
+ //#region src/core/resolve/stages.d.ts
6
+ /** What the parser produced for one input in this invocation. */
7
+ type CliValue = {
8
+ readonly kind: "value";
9
+ readonly value: unknown;
10
+ } | {
11
+ readonly kind: "dash";
12
+ } | {
13
+ readonly kind: "absent";
14
+ };
15
+ /** The outcome of one stage, or of a whole walk. */
16
+ type StageOutcome = {
17
+ readonly kind: "value";
18
+ readonly value: unknown;
19
+ readonly provenance: ResolutionProvenance;
20
+ } | {
21
+ readonly kind: "error";
22
+ readonly error: ValidationError;
23
+ } | {
24
+ readonly kind: "absent";
25
+ };
26
+ /** A prompt run that either answered, failed, or declined to produce a value. */
27
+ type PromptOutcome = {
28
+ readonly ok: true;
29
+ readonly value: unknown;
30
+ } | {
31
+ readonly ok: false;
32
+ readonly error: ValidationError | undefined;
33
+ };
34
+ /** Everything one input contributes to its own resolution. */
35
+ interface StageInput {
36
+ /** What the parser produced for this input. */
37
+ readonly cli: CliValue;
38
+ /** Decode a raw value from a non-CLI source into the input's declared type. */
39
+ readonly coerce: (binding: DecodedSourceBinding, raw: unknown) => CoerceResult;
40
+ /**
41
+ * Aggregate what the parser produced, splicing the stdin buffer into the
42
+ * position each `-` occurrence holds.
43
+ */
44
+ readonly finishCli: (value: unknown, stdinData: string | null | undefined, stdin: StdinSourceBinding | undefined) => CliFinish;
45
+ /** Run the prompt engine for this input. */
46
+ readonly runPrompt: (binding: PromptSourceBinding) => Promise<PromptOutcome>;
47
+ }
48
+ /** External state every stage reads from. */
49
+ interface StageState {
50
+ /** Environment variable snapshot. */
51
+ readonly env: Readonly<Record<string, string | undefined>>;
52
+ /** Parsed config file contents. */
53
+ readonly config: Readonly<Record<string, unknown>>;
54
+ /** Pre-read stdin content, or `null`/`undefined` when nothing was piped. */
55
+ readonly stdinData: string | null | undefined;
56
+ /** Whether an interactive prompt engine is available. */
57
+ readonly canPrompt: boolean;
58
+ }
59
+ /**
60
+ * Walk the given bindings in order and return the first one that produces a
61
+ * value or an error.
62
+ *
63
+ * A coercion failure at any sourced stage stops the walk, so a bad env value
64
+ * never silently falls through to config.
65
+ *
66
+ * @param bindings - The sources to attempt, in precedence order.
67
+ * @param input - The input being resolved.
68
+ * @param state - External state the stages read.
69
+ * @returns The winning stage's outcome, or `absent` when no stage produced one.
70
+ */
71
+ declare function runStages(bindings: readonly SourceBinding[], input: StageInput, state: StageState): Promise<StageOutcome>;
72
+ /**
73
+ * How the parser's record reads for one input.
74
+ *
75
+ * A `-` counts as the stdin selector only when the input declares a stdin
76
+ * binding that reacts to it; otherwise it is the literal string the user typed.
77
+ *
78
+ * @param present - Whether the parser produced an own key for this input.
79
+ * @param value - The parsed value.
80
+ * @param bindings - The input's source list.
81
+ * @returns What the CLI stage should do with it.
82
+ */
83
+ declare function readCliValue(present: boolean, value: unknown, bindings: readonly SourceBinding[]): CliValue;
84
+ //#endregion
85
+ export { type CliValue, type PromptOutcome, type StageInput, type StageOutcome, type StageState, readCliValue, runStages };
@@ -0,0 +1,170 @@
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,24 +1 @@
1
- import { ValidationError } from "../errors/index.mjs";
2
- import { CommandSchema } from "../schema/command.mjs";
3
- import "../schema/index.mjs";
4
- //#region src/core/resolve/standard.d.ts
5
- /** Resolved values after the Standard Schema pass, plus any issues found. */
6
- interface StandardValidationResult {
7
- readonly flags: Readonly<Record<string, unknown>>;
8
- readonly args: Readonly<Record<string, unknown>>;
9
- readonly errors: readonly ValidationError[];
10
- }
11
- /**
12
- * Validate resolved flag and arg values against any attached Standard Schema
13
- * validators. Values without a validator, or resolved to `undefined`, pass
14
- * through untouched.
15
- *
16
- * @param schema - The command schema carrying per-flag/arg validators.
17
- * @param flags - Resolved flag values, keyed by flag name.
18
- * @param args - Resolved arg values, keyed by arg name.
19
- * @returns The (possibly transformed) values and any constraint violations.
20
- * @internal
21
- */
22
- declare function applyStandardValidators(schema: CommandSchema, flags: Readonly<Record<string, unknown>>, args: Readonly<Record<string, unknown>>): Promise<StandardValidationResult>;
23
- //#endregion
24
- export { applyStandardValidators };
1
+ export {}