@inventarch/cli 1.1.1 → 1.2.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 (85) hide show
  1. package/LANGUAGE.md +2 -2
  2. package/README.md +10 -4
  3. package/SPEC.md +16 -4
  4. package/assets/base/0305ca741b1dfec97ff35fbeb36d4a66a0c9c0614b730fe14fcdac0f1565e28a.ia.tgz +0 -0
  5. package/assets/base.json +3 -3
  6. package/assets/host/c5fb2bfbba619cbd558ecc1e94dd2c16e37aa8599b4e423f1f59ed01f2074e03.tgz +0 -0
  7. package/assets/host.json +4 -4
  8. package/assets/vocabulary.json +436 -4
  9. package/dist/capture.d.ts +81 -0
  10. package/dist/capture.d.ts.map +1 -0
  11. package/dist/capture.js +271 -0
  12. package/dist/capture.js.map +1 -0
  13. package/dist/claude-cli.js +1 -1
  14. package/dist/claude-cli.js.map +1 -1
  15. package/dist/commands.d.ts +1 -1
  16. package/dist/commands.d.ts.map +1 -1
  17. package/dist/commands.js +32 -3
  18. package/dist/commands.js.map +1 -1
  19. package/dist/compile.d.ts +6 -0
  20. package/dist/compile.d.ts.map +1 -1
  21. package/dist/compile.js +57 -27
  22. package/dist/compile.js.map +1 -1
  23. package/dist/consumer.d.ts +48 -7
  24. package/dist/consumer.d.ts.map +1 -1
  25. package/dist/consumer.js +134 -28
  26. package/dist/consumer.js.map +1 -1
  27. package/dist/decline.d.ts.map +1 -1
  28. package/dist/decline.js +15 -7
  29. package/dist/decline.js.map +1 -1
  30. package/dist/distribute.d.ts +43 -11
  31. package/dist/distribute.d.ts.map +1 -1
  32. package/dist/distribute.js +173 -63
  33. package/dist/distribute.js.map +1 -1
  34. package/dist/format.d.ts +2 -2
  35. package/dist/format.d.ts.map +1 -1
  36. package/dist/format.js +17 -10
  37. package/dist/format.js.map +1 -1
  38. package/dist/home-remedy.d.ts +8 -4
  39. package/dist/home-remedy.d.ts.map +1 -1
  40. package/dist/home-remedy.js +8 -4
  41. package/dist/home-remedy.js.map +1 -1
  42. package/dist/host-projection.js +1 -1
  43. package/dist/host-projection.js.map +1 -1
  44. package/dist/host.d.ts +10 -4
  45. package/dist/host.d.ts.map +1 -1
  46. package/dist/host.js +43 -27
  47. package/dist/host.js.map +1 -1
  48. package/dist/init.d.ts +5 -2
  49. package/dist/init.d.ts.map +1 -1
  50. package/dist/init.js +41 -20
  51. package/dist/init.js.map +1 -1
  52. package/dist/inspect.d.ts +26 -2
  53. package/dist/inspect.d.ts.map +1 -1
  54. package/dist/inspect.js +117 -52
  55. package/dist/inspect.js.map +1 -1
  56. package/dist/pack.d.ts +3 -1
  57. package/dist/pack.d.ts.map +1 -1
  58. package/dist/pack.js +32 -9
  59. package/dist/pack.js.map +1 -1
  60. package/dist/read.d.ts +21 -0
  61. package/dist/read.d.ts.map +1 -0
  62. package/dist/read.js +141 -0
  63. package/dist/read.js.map +1 -0
  64. package/dist/render.d.ts +11 -0
  65. package/dist/render.d.ts.map +1 -1
  66. package/dist/render.js +28 -1
  67. package/dist/render.js.map +1 -1
  68. package/dist/session.d.ts +6 -1
  69. package/dist/session.d.ts.map +1 -1
  70. package/dist/session.js +52 -6
  71. package/dist/session.js.map +1 -1
  72. package/dist/user-host.d.ts.map +1 -1
  73. package/dist/user-host.js +7 -5
  74. package/dist/user-host.js.map +1 -1
  75. package/dist/validate.d.ts +1 -2
  76. package/dist/validate.d.ts.map +1 -1
  77. package/dist/validate.js +6 -27
  78. package/dist/validate.js.map +1 -1
  79. package/dist/vocabulary.d.ts +4 -0
  80. package/dist/vocabulary.d.ts.map +1 -1
  81. package/dist/vocabulary.js +12 -7
  82. package/dist/vocabulary.js.map +1 -1
  83. package/package.json +6 -6
  84. package/assets/base/78bff5eb3188b628c06d2f1cf1477fb1bfcea874ec3863ae112b4972b8e81517.ia.tgz +0 -0
  85. package/assets/host/b97e367bbf15db09f552d6bd6dd3701210efe77931d34b57ccb85240957aba61.tgz +0 -0
package/dist/compile.js CHANGED
@@ -1,5 +1,10 @@
1
1
  /**
2
- * `ia compile`: docs/specs/consumer-cli-contract/README.md §2.4.
2
+ * `ia compile`: docs/specs/consumer-cli-contract/README.md §2.4, deprecated in favour of `ia capture`.
3
+ *
4
+ * Decision release-bump (operator, 2026-10-07): in 1.x the verb keeps its behaviour exactly — the `ia.compiled.v1`
5
+ * artifact at .ia/work/compiled.json or `--out <file>` under .ia/work/, `--stdout`, the IA-DIST-LOCAL-MODIFICATION
6
+ * refusal without `--force` and its exit classes — and adds one deprecation line on stderr naming `ia capture`. The
7
+ * alias of decision compile-verb-fate, which routes the verb to the capture, waits for 2.0.
3
8
  *
4
9
  * One deterministic document, `ia.compiled.v1`. Determinism is a requirement on this writer, not a hope: records
5
10
  * are sorted by canonical identity, diagnostics by (path, line, code, message), object keys are emitted sorted and
@@ -12,19 +17,21 @@
12
17
  * pass, never suppressed and never omitted from --json.
13
18
  */
14
19
  import { resolve } from 'node:path';
20
+ import { CAPTURE_CURRENT } from '@inventarch/db';
15
21
  import { createFile, json, LANGUAGE_IDENTITY, replace, sha256, workOutputPath, } from '@inventarch/distribution/services';
16
- import { Refusal, requireRoot } from './consumer.js';
22
+ import { findingCounts, orderFindings } from './capture.js';
23
+ import { Refusal, requireRoot, respell } from './consumer.js';
17
24
  import { codeOf, openSession } from './session.js';
18
- import { NOT_EVALUATED } from './validate.js';
19
- import { atom, document, entry, headerLine, sectionLabel, truncateDigest, words } from './render.js';
25
+ import { atom, document, entry, headerLine, quote, sectionLabel, truncateDigest, words } from './render.js';
20
26
  export const DEFAULT_OUT = '.ia/work/compiled.json';
21
27
  export const ARTIFACT = 'ia.compiled.v1';
22
28
  const compare = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
23
- /** The ordering the compliance layer already applies, reused rather than reinvented. */
24
- const orderFindings = (findings) => [...findings].sort((a, b) => compare(a.path, b.path) || a.line - b.line || compare(a.code, b.code) || compare(a.message, b.message));
25
29
  export function buildArtifact(root, session) {
26
30
  const admission = session.admission();
27
- const records = [...session.reader.records()].sort((a, b) => compare(a.identity, b.identity));
31
+ // ia.compiled.v1 records predate graph G13, so the artifact and its digest omit the per-record digest.
32
+ const records = [...session.reader.records()]
33
+ .sort((a, b) => compare(a.identity, b.identity))
34
+ .map(({ digest: _digest, ...record }) => record);
28
35
  const diagnostics = orderFindings(admission.findings);
29
36
  const artifact = {
30
37
  formatVersion: 1,
@@ -35,12 +42,7 @@ export function buildArtifact(root, session) {
35
42
  revision: admission.revision,
36
43
  records,
37
44
  diagnostics,
38
- counts: {
39
- records: records.length,
40
- errors: diagnostics.filter((finding) => finding.severity === 'error').length,
41
- warnings: diagnostics.filter((finding) => finding.severity === 'warning').length,
42
- notEvaluated: diagnostics.filter((finding) => NOT_EVALUATED.has(finding.code)).length,
43
- },
45
+ counts: findingCounts(records.length, diagnostics),
44
46
  };
45
47
  const text = json(artifact);
46
48
  return { artifact, text, digest: sha256(text) };
@@ -93,12 +95,18 @@ export function renderCompile(view, path, caps) {
93
95
  ], { depth: 0, symbol: 'step' }, caps),
94
96
  ], { leadingBlank: true });
95
97
  }
98
+ /**
99
+ * Decision release-bump (operator, 2026-10-07): `ia compile` keeps its 1.x behaviour and prints this one line on
100
+ * stderr whenever it runs to a result, in every output mode, `--json` and `--stdout` included, so stdout stays exactly
101
+ * what 1.x wrote there; a refusal prints only the refusal. The alias of decision compile-verb-fate lands in 2.0.
102
+ */
103
+ export const DEPRECATION = `Deprecated: ia compile becomes an alias of "ia capture" in 2.0 and is removed in 3.0; run "ia capture" to write the admitted snapshot to ${CAPTURE_CURRENT}.\n`;
96
104
  /**
97
105
  * §2.4: running `ia compile` twice is the ordinary case, so refusing by default is stated rather than discovered.
98
106
  * `createFile` raises IA-DIST-LOCAL-MODIFICATION on an existing entry; the code is carried through unchanged and
99
107
  * only the next action is added, because a refusal whose remedy is one flag must name that flag.
100
108
  */
101
- function publish(root, path, content, force) {
109
+ function publish(root, path, content, force, overwrite) {
102
110
  if (force) {
103
111
  replace(root, path, content);
104
112
  return;
@@ -109,28 +117,50 @@ function publish(root, path, content, force) {
109
117
  catch (error) {
110
118
  if (codeOf(error, '') !== 'IA-DIST-LOCAL-MODIFICATION')
111
119
  throw error;
112
- throw new Refusal('IA-DIST-LOCAL-MODIFICATION', `${path} already exists`, 3, { path }, 'Pass --force to overwrite it, or choose another --out under .ia/work/.');
120
+ throw new Refusal('IA-DIST-LOCAL-MODIFICATION', `${path} already exists`, 3, { path }, `Run "${overwrite}" to overwrite it.`);
113
121
  }
114
122
  }
115
- export function runCompile(context) {
116
- const { args, caps, json: machine } = context;
117
- const root = requireRoot(context);
118
- // Placement is decided before the workspace is read, so an unsafe --out never costs a compilation.
119
- const path = args.flag('stdout')
120
- ? null
121
- : workOutputPath({
123
+ /** The refused invocation again with `--force`, so the one flag the remedy needs is named in a runnable command. */
124
+ function forced(context) {
125
+ const out = context.args.value('out'), root = context.args.value('root');
126
+ return [
127
+ 'ia compile',
128
+ ...(out === undefined ? [] : ['--out', quote(out)]),
129
+ '--force',
130
+ ...(root === undefined ? [] : ['--root', quote(root)]),
131
+ ].join(' ');
132
+ }
133
+ /**
134
+ * The artifact's place, decided before the workspace is read so an unsafe `--out` never costs a compilation. The
135
+ * distribution's IA-DIST-PATH-UNSAFE is carried through unchanged (§4.1); only its next action is added, the rerun
136
+ * with the one value the user has to correct.
137
+ */
138
+ function placement(context, root) {
139
+ try {
140
+ return workOutputPath({
122
141
  root,
123
- path: args.value('out') ?? DEFAULT_OUT,
142
+ path: context.args.value('out') ?? DEFAULT_OUT,
124
143
  refusal: 'A compiled artifact is written under .ia/work/',
125
144
  });
145
+ }
146
+ catch (error) {
147
+ if (error instanceof Refusal || codeOf(error, '') !== 'IA-DIST-PATH-UNSAFE')
148
+ throw error;
149
+ throw new Refusal('IA-DIST-PATH-UNSAFE', error instanceof Error ? error.message : String(error), 3, null, `Run "${respell(context, { options: { out: ['<file>'] } })}" naming a file under .ia/work/.`);
150
+ }
151
+ }
152
+ export function runCompile(context) {
153
+ const { args, caps, json: machine } = context;
154
+ const root = requireRoot(context);
155
+ const path = args.flag('stdout') ? null : placement(context, root);
126
156
  const view = collectCompile(root);
127
157
  const exitCode = compileExit(view);
128
158
  // §2.4: with --stdout the artifact is the single value on stdout, so nothing else may be written there.
129
159
  if (path === null)
130
- return { exitCode, stdout: view.text, stderr: '' };
131
- publish(root, path, Buffer.from(view.text, 'utf8'), args.flag('force'));
160
+ return { exitCode, stdout: view.text, stderr: DEPRECATION };
161
+ publish(root, path, Buffer.from(view.text, 'utf8'), args.flag('force'), forced(context));
132
162
  return machine
133
- ? { exitCode, stdout: JSON.stringify(compileEnvelope(view, resolve(root, path))) + '\n', stderr: '' }
134
- : { exitCode, stdout: renderCompile(view, path, caps), stderr: '' };
163
+ ? { exitCode, stdout: JSON.stringify(compileEnvelope(view, resolve(root, path))) + '\n', stderr: DEPRECATION }
164
+ : { exitCode, stdout: renderCompile(view, path, caps), stderr: DEPRECATION };
135
165
  }
136
166
  //# sourceMappingURL=compile.js.map
@@ -1 +1 @@
1
- {"version":3,"file":"compile.js","sourceRoot":"","sources":["../src/compile.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"compile.js","sourceRoot":"","sources":["../src/compile.ts"],"names":[],"mappings":"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"}
@@ -51,7 +51,17 @@ export interface Context {
51
51
  readonly caps: Capabilities;
52
52
  readonly json: boolean;
53
53
  }
54
- /** §4: a refusal carries the service's own code unchanged, its exit class, and where it happened. */
54
+ /**
55
+ * §4: a refusal carries the service's own code unchanged, its exit class, and where it happened. Design row 27
56
+ * (position-and-projection §12): it also names its next action, which quotes exactly one command carrying every value
57
+ * this invocation supplied that the command needs. A manual step the CLI cannot take for the user (delete or move a
58
+ * named file, set a variable) may come first; an explanation may follow. It spells no other command or option.
59
+ *
60
+ * The published constructor keeps its 1.x form (decision release-bump): `where` and `next` default to null, and a
61
+ * refusal without a next action of its own is given `serviceNext`'s when it is rendered, so `--json` `next` is always
62
+ * a string. Every construction site in this CLI still names its next action explicitly; tests/refusal-next.test.ts
63
+ * fails a site that omits it or passes null.
64
+ */
55
65
  export declare class Refusal extends Error {
56
66
  readonly code: string;
57
67
  readonly exit: number;
@@ -73,20 +83,39 @@ export declare class Refusal extends Error {
73
83
  }
74
84
  /**
75
85
  * §5's first signal, raised by a verb that had already written when it observed the signal. The JSON result stays
76
- * §5's fixed object; the one stderr line gains the rerun that finishes the work, which M5.2 §5 requires `ia init`
77
- * to name once it has written anything.
86
+ * §5's fixed object plus `next`; the one stderr line gains the rerun that finishes the work, which M5.2 §5 requires
87
+ * `ia init` to name once it has written anything.
78
88
  */
79
89
  export declare class Interrupted extends Error {
80
90
  readonly next: string;
81
91
  constructor(next: string);
82
92
  }
93
+ /** The refused invocation a fallback next command is spelled for: its verb, or none for the binary, and `--root` as given. */
94
+ export interface Refused {
95
+ readonly command: string | null;
96
+ readonly root?: string | undefined;
97
+ }
98
+ /**
99
+ * Design row 27 for a service refusal that reaches the shell with no next action of its own: usage names the verb's
100
+ * own help; a record finding (`IA-COMP-*`, `IA-GRAPH-*`, `IA-LANG-*`) names `ia validate`; every other code, an
101
+ * unrecognized failure included, names `ia doctor`, which observes the runtime, workspace, installation and host
102
+ * state such a refusal comes from. Both carry `--root` when the refused invocation gave it. A verb that knows a more
103
+ * exact repair names it at the refusal instead.
104
+ */
105
+ export declare function serviceNext(code: string, refused: Refused): string;
83
106
  /**
84
107
  * §4.1: the consumer never rewrites a service's code. Class 4 is unreachable from the three verbs this release
85
- * implements, because none of them acquires anything over a network, so every unmapped failure is class 3.
108
+ * implements, because none of them acquires anything over a network, so every unmapped failure is class 3. With the
109
+ * refused invocation named, the next action is `serviceNext`'s spelled for it; without, it is null as in 1.x, and
110
+ * `renderRefusal` supplies the fallback.
86
111
  */
87
- export declare function refusalOf(error: unknown): Refusal;
88
- /** §4.3 and §6.5. Human mode renders the block on stderr; `--json` emits the one object on stdout. */
89
- export declare function renderRefusal(refusal: Refusal, caps: Capabilities, json: boolean): Result;
112
+ export declare function refusalOf(error: unknown, refused?: Refused): Refusal;
113
+ /**
114
+ * §4.3 and §6.5. Human mode renders the block on stderr; `--json` emits the one object on stdout. Design row 27 holds
115
+ * at this boundary: a refusal built without a next action (the 1.x constructor form) is given `serviceNext`'s, spelled
116
+ * for `refused` when the caller names the refused invocation.
117
+ */
118
+ export declare function renderRefusal(refusal: Refusal, caps: Capabilities, json: boolean, refused?: Refused): Result;
90
119
  /** §6.5's strip rule applied to the serializer as well as the renderer, so both carry the same message. */
91
120
  export declare const stripFor: (message: string, code: string, location: string | null, identity: string | null) => string;
92
121
  export declare const optionLabel: (name: string, short: string | undefined, placeholder: string | undefined) => string;
@@ -109,6 +138,18 @@ export declare function renderCommandHelp(command: CommandSpec, caps: Capabiliti
109
138
  export declare function discoverRoot(start: string, iaHome?: string): string | undefined;
110
139
  /** The IA home for discovery, or undefined when its variable is malformed; the verb that needs the home refuses then. */
111
140
  export declare function iaHomeOf(env: Readonly<Record<string, string | undefined>>, home?: string): string | undefined;
141
+ /**
142
+ * Design row 27: the refused invocation spelled again from what the parser understood, so a next action that reruns it
143
+ * carries every argument this invocation supplied that the rerun needs: its positionals, then the verb's own options in
144
+ * grammar order, `--root` last, each value quoted. As the install, host and init reruns are, it is the verb's plan: an
145
+ * optional `--apply` is left out, and `ia restore`'s required one is kept with `--yes`, confirmed as every printed apply
146
+ * is. The other common flags only shape the output, so none is spelled. `changes` replaces the positionals or one option's
147
+ * values with the argument the remedy asks the user to correct.
148
+ */
149
+ export declare function respell(context: Pick<Context, 'command' | 'args'>, changes?: {
150
+ readonly positionals?: readonly string[];
151
+ readonly options?: Readonly<Record<string, readonly string[]>>;
152
+ }): string;
112
153
  /**
113
154
  * §2.0: the real path of the resolved absolute root, because `workspace()` refuses a relative root and any link on the
114
155
  * way to one (`apps/distribution/src/files.ts:51`). A failed discovery is exit 3 with IA-DB-ROOT-INVALID.
@@ -1 +1 @@
1
- {"version":3,"file":"consumer.d.ts","sourceRoot":"","sources":["../src/consumer.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"consumer.d.ts","sourceRoot":"","sources":["../src/consumer.ts"],"names":[],"mappings":"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"}
package/dist/consumer.js CHANGED
@@ -14,6 +14,7 @@ import { sameFile } from '@inventarch/db';
14
14
  import { resolveIaHome } from '@inventarch/distribution/ia-home';
15
15
  import { parseArguments, UsageError } from './args.js';
16
16
  import { COMMANDS, COMMON_OPTIONS, CORE_TOKENS, findCommand, LEGACY_OPERATIONS, nearestTokens, RESERVED_TOKEN, } from './commands.js';
17
+ import { runCapture } from './capture.js';
17
18
  import { runCompile } from './compile.js';
18
19
  import { runDistribute } from './distribute.js';
19
20
  import { runDoctor } from './doctor.js';
@@ -22,9 +23,10 @@ import { runHost } from './host.js';
22
23
  import { runInit } from './init.js';
23
24
  import { runInspect } from './inspect.js';
24
25
  import { runPack } from './pack.js';
26
+ import { runRead } from './read.js';
25
27
  import { runValidate } from './validate.js';
26
28
  import { runVocabulary } from './vocabulary.js';
27
- import { atom, document, entry, errorBlock, fieldRows, resolveCapabilities, sectionLabel, words } from './render.js';
29
+ import { atom, document, entry, errorBlock, fieldRows, quote, remedyWords, resolveCapabilities, sectionLabel, words, } from './render.js';
28
30
  /** §2.8 rule 3: `y` or `yes`, in any case and ignoring surrounding space. Everything else, EOF included, declines. */
29
31
  export const consents = (answer) => answer !== null && ['y', 'yes'].includes(answer.trim().toLowerCase());
30
32
  /**
@@ -36,7 +38,17 @@ export async function confirm(interaction, summary, question) {
36
38
  interaction.write(question);
37
39
  return consents(await interaction.read());
38
40
  }
39
- /** §4: a refusal carries the service's own code unchanged, its exit class, and where it happened. */
41
+ /**
42
+ * §4: a refusal carries the service's own code unchanged, its exit class, and where it happened. Design row 27
43
+ * (position-and-projection §12): it also names its next action, which quotes exactly one command carrying every value
44
+ * this invocation supplied that the command needs. A manual step the CLI cannot take for the user (delete or move a
45
+ * named file, set a variable) may come first; an explanation may follow. It spells no other command or option.
46
+ *
47
+ * The published constructor keeps its 1.x form (decision release-bump): `where` and `next` default to null, and a
48
+ * refusal without a next action of its own is given `serviceNext`'s when it is rendered, so `--json` `next` is always
49
+ * a string. Every construction site in this CLI still names its next action explicitly; tests/refusal-next.test.ts
50
+ * fails a site that omits it or passes null.
51
+ */
40
52
  export class Refusal extends Error {
41
53
  code;
42
54
  exit;
@@ -57,8 +69,8 @@ export class Refusal extends Error {
57
69
  }
58
70
  /**
59
71
  * §5's first signal, raised by a verb that had already written when it observed the signal. The JSON result stays
60
- * §5's fixed object; the one stderr line gains the rerun that finishes the work, which M5.2 §5 requires `ia init`
61
- * to name once it has written anything.
72
+ * §5's fixed object plus `next`; the one stderr line gains the rerun that finishes the work, which M5.2 §5 requires
73
+ * `ia init` to name once it has written anything.
62
74
  */
63
75
  export class Interrupted extends Error {
64
76
  next;
@@ -75,21 +87,45 @@ const codeOf = (error) => {
75
87
  const code = error.code;
76
88
  return typeof code === 'string' && IA_CODE.test(code) ? code : undefined;
77
89
  };
90
+ /** Code areas whose refusals concern authored records, so their findings are what `ia validate` reports. */
91
+ const RECORD_AREAS = new Set(['COMP', 'GRAPH', 'LANG']);
92
+ /**
93
+ * Design row 27 for a service refusal that reaches the shell with no next action of its own: usage names the verb's
94
+ * own help; a record finding (`IA-COMP-*`, `IA-GRAPH-*`, `IA-LANG-*`) names `ia validate`; every other code, an
95
+ * unrecognized failure included, names `ia doctor`, which observes the runtime, workspace, installation and host
96
+ * state such a refusal comes from. Both carry `--root` when the refused invocation gave it. A verb that knows a more
97
+ * exact repair names it at the refusal instead.
98
+ */
99
+ export function serviceNext(code, refused) {
100
+ if (code === 'IA-CLI-USAGE')
101
+ return `Run "${refused.command === null ? 'ia' : `ia ${refused.command}`} --help" for the accepted syntax.`;
102
+ const rooted = refused.root === undefined ? '' : ` --root ${quote(refused.root)}`;
103
+ return RECORD_AREAS.has(code.split('-')[1] ?? '')
104
+ ? `Run "ia validate${rooted}" for the workspace's located findings.`
105
+ : `Run "ia doctor${rooted}" for the observed runtime, workspace, installation and host state.`;
106
+ }
78
107
  /**
79
108
  * §4.1: the consumer never rewrites a service's code. Class 4 is unreachable from the three verbs this release
80
- * implements, because none of them acquires anything over a network, so every unmapped failure is class 3.
109
+ * implements, because none of them acquires anything over a network, so every unmapped failure is class 3. With the
110
+ * refused invocation named, the next action is `serviceNext`'s spelled for it; without, it is null as in 1.x, and
111
+ * `renderRefusal` supplies the fallback.
81
112
  */
82
- export function refusalOf(error) {
113
+ export function refusalOf(error, refused) {
83
114
  if (error instanceof Refusal)
84
115
  return error;
85
116
  const message = error instanceof Error ? error.message : String(error);
86
117
  if (error instanceof UsageError)
87
- return new Refusal('IA-CLI-USAGE', message, 2);
88
- const code = codeOf(error);
89
- return code === undefined ? new Refusal('IA-CLI-FAILED', message, 3) : new Refusal(code, message, 3);
118
+ return new Refusal('IA-CLI-USAGE', message, 2, null, refused === undefined ? null : serviceNext(error.code, refused));
119
+ const code = codeOf(error) ?? 'IA-CLI-FAILED';
120
+ return new Refusal(code, message, 3, null, refused === undefined ? null : serviceNext(code, refused));
90
121
  }
91
- /** §4.3 and §6.5. Human mode renders the block on stderr; `--json` emits the one object on stdout. */
92
- export function renderRefusal(refusal, caps, json) {
122
+ /**
123
+ * §4.3 and §6.5. Human mode renders the block on stderr; `--json` emits the one object on stdout. Design row 27 holds
124
+ * at this boundary: a refusal built without a next action (the 1.x constructor form) is given `serviceNext`'s, spelled
125
+ * for `refused` when the caller names the refused invocation.
126
+ */
127
+ export function renderRefusal(refusal, caps, json, refused = { command: null }) {
128
+ const next = refusal.next ?? serviceNext(refusal.code, refused);
93
129
  const located = refusal.where?.path === undefined || refusal.where.path === ''
94
130
  ? null
95
131
  : refusal.where.line === undefined
@@ -110,7 +146,7 @@ export function renderRefusal(refusal, caps, json) {
110
146
  line: refusal.where.line ?? null,
111
147
  identity: refusal.where.identity ?? null,
112
148
  },
113
- next: refusal.next,
149
+ next,
114
150
  };
115
151
  return { exitCode: refusal.exit, stdout: JSON.stringify(body) + '\n', stderr: '' };
116
152
  }
@@ -119,7 +155,8 @@ export function renderRefusal(refusal, caps, json) {
119
155
  ...(refusal.where?.identity === undefined ? {} : { identity: refusal.where.identity }),
120
156
  code: refusal.code,
121
157
  message: refusal.message,
122
- ...(refusal.next === null ? {} : { next: words(refusal.next) }),
158
+ // Design row 27: the command it names stays on one line, so it is copied and run as printed.
159
+ next: remedyWords(next),
123
160
  }, { depth: 0 }, caps);
124
161
  return { exitCode: refusal.exit, stdout: '', stderr: document([block]) };
125
162
  }
@@ -157,7 +194,7 @@ const groupBlock = (group, label, caps) => [
157
194
  export function renderHelp(host, caps, namespaces) {
158
195
  const common = OPTION_ORDER.map((name) => COMMON_OPTIONS.find((row) => row.name === name));
159
196
  return document([
160
- entry([[atom('ia', 'bold', 0), atom(`${host.version} — author, compile and distribute .ia records`)]], { depth: 0 }, caps),
197
+ entry([[atom('ia', 'bold', 0), atom(`${host.version} — author, capture and distribute .ia records`)]], { depth: 0 }, caps),
161
198
  [sectionLabel('Usage', caps), ...entry([words('ia <command> [options]')], { depth: 1 }, caps)],
162
199
  groupBlock('workspace', 'Workspace', caps),
163
200
  groupBlock('distribution', 'Distribution', caps),
@@ -221,6 +258,37 @@ export function iaHomeOf(env, home = homedir()) {
221
258
  return undefined;
222
259
  }
223
260
  }
261
+ /**
262
+ * Design row 27: the refused invocation spelled again from what the parser understood, so a next action that reruns it
263
+ * carries every argument this invocation supplied that the rerun needs: its positionals, then the verb's own options in
264
+ * grammar order, `--root` last, each value quoted. As the install, host and init reruns are, it is the verb's plan: an
265
+ * optional `--apply` is left out, and `ia restore`'s required one is kept with `--yes`, confirmed as every printed apply
266
+ * is. The other common flags only shape the output, so none is spelled. `changes` replaces the positionals or one option's
267
+ * values with the argument the remedy asks the user to correct.
268
+ */
269
+ export function respell(context, changes = {}) {
270
+ const { command, args } = context;
271
+ const common = new Set(COMMON_OPTIONS.map((option) => option.name));
272
+ const applies = command.grammar.options.some((option) => option.name === 'apply' && option.required === true);
273
+ const spelled = (option) => option.kind === 'boolean'
274
+ ? args.flag(option.name) && (option.name !== 'apply' || applies)
275
+ ? [`--${option.name}`]
276
+ : []
277
+ : (changes.options?.[option.name] ?? args.list(option.name)).flatMap((value) => [
278
+ `--${option.name}`,
279
+ quote(value),
280
+ ]);
281
+ const options = [
282
+ ...command.grammar.options.filter((option) => !common.has(option.name)).flatMap(spelled),
283
+ ...(applies ? ['--yes'] : []),
284
+ ...command.grammar.options.filter((option) => option.name === 'root').flatMap(spelled),
285
+ ];
286
+ const positionals = (changes.positionals ?? args.positionals).map(quote);
287
+ // A positional that reads as an option was given after `--`, so it is spelled after one again.
288
+ return positionals.some((value) => value.startsWith('-') && value !== '-')
289
+ ? ['ia', command.name, ...options, '--', ...positionals].join(' ')
290
+ : ['ia', command.name, ...positionals, ...options].join(' ');
291
+ }
224
292
  /**
225
293
  * §2.0: the real path of the resolved absolute root, because `workspace()` refuses a relative root and any link on the
226
294
  * way to one (`apps/distribution/src/files.ts:51`). A failed discovery is exit 3 with IA-DB-ROOT-INVALID.
@@ -233,7 +301,7 @@ export function requireRoot(context) {
233
301
  // missing directory as IA-DIST-INPUT-INVALID first, and §4.1 forbids rewriting a service's code, so the CLI
234
302
  // makes the check itself and the service is never reached with a root it would name differently.
235
303
  if (!statSync(path, { throwIfNoEntry: false })?.isDirectory())
236
- throw new Refusal('IA-DB-ROOT-INVALID', `Cannot open workspace ${path}: no such directory`, 3, { path }, 'Pass --root <path> with an existing directory.');
304
+ throw new Refusal('IA-DB-ROOT-INVALID', `Cannot open workspace ${path}: no such directory`, 3, { path }, `Run "${respell(context, { options: { root: ['<directory>'] } })}" naming an existing directory.`);
237
305
  // The root the user chose opens at its real path, as `ia host` resolves it, so a root reached through links (macOS
238
306
  // /tmp, a linked checkout) works; every path below it is still checked link by link. The JS `realpathSync`, not
239
307
  // `.native`: it keeps each name's case as typed, which the steward guard now folds (`unaliased`, #315). An 8.3
@@ -242,7 +310,7 @@ export function requireRoot(context) {
242
310
  }
243
311
  const found = discoverRoot(context.host.cwd, iaHomeOf(context.host.env));
244
312
  if (found === undefined)
245
- throw new Refusal('IA-DB-ROOT-INVALID', `No .ia/src directory at ${context.host.cwd} or in any parent`, 3, { path: context.host.cwd }, 'Run "ia init" to see what a new workspace would contain, or pass --root <path>.');
313
+ throw new Refusal('IA-DB-ROOT-INVALID', `No .ia/src directory at ${context.host.cwd} or in any parent`, 3, { path: context.host.cwd }, 'Run "ia init" to see what a new workspace here would contain.');
246
314
  // A discovered root opens at its real path too: Windows keeps a junction's spelling in the cwd, where POSIX getcwd resolves it.
247
315
  return realpathSync(found);
248
316
  }
@@ -252,14 +320,16 @@ const wantsHelp = (argv) => {
252
320
  const end = argv.indexOf('--');
253
321
  return argv.slice(0, end === -1 ? argv.length : end).some((token) => HELP_TOKENS.has(token));
254
322
  };
255
- /** The thirteen verbs of §1.2 step 5. A verb with no row here is a defect in this table, not a missing feature. */
323
+ /** The fifteen verbs of §1.2 step 5. A verb with no row here is a defect in this table, not a missing feature. */
256
324
  const HANDLERS = {
257
325
  init: runInit,
258
326
  vocabulary: runVocabulary,
259
327
  format: runFormat,
328
+ capture: runCapture,
260
329
  compile: runCompile,
261
330
  validate: runValidate,
262
331
  inspect: runInspect,
332
+ read: runRead,
263
333
  pack: runPack,
264
334
  install: runDistribute('install'),
265
335
  update: runDistribute('update'),
@@ -273,9 +343,12 @@ export async function runCommand(command, argv, host) {
273
343
  const preliminary = resolveCapabilities(host.stdout, {});
274
344
  if (wantsHelp(argv))
275
345
  return { exitCode: 0, stdout: renderCommandHelp(command, preliminary), stderr: '' };
276
- let caps = preliminary;
346
+ let caps = preliminary,
347
+ // Kept for the refusal below, whose fallback next action names the root the parser understood. A failed parse
348
+ // leaves none, and its usage refusal names the verb's help, which takes no root.
349
+ args;
277
350
  try {
278
- const args = parseArguments(argv, command.grammar);
351
+ args = parseArguments(argv, command.grammar);
279
352
  const json = args.flag('json');
280
353
  caps = resolveCapabilities(host.stdout, {
281
354
  ...(args.flag('color') ? { color: true } : args.flag('no-color') ? { color: false } : {}),
@@ -295,27 +368,40 @@ export async function runCommand(command, argv, host) {
295
368
  const context = { host, command, args, caps, json };
296
369
  const handler = HANDLERS[command.name];
297
370
  if (handler === undefined)
298
- throw new Refusal('IA-CLI-FAILED', `No handler is installed for ia ${command.name}`, 3);
371
+ throw new Refusal('IA-CLI-FAILED', `No handler is installed for ia ${command.name}`, 3, null, serviceNext('IA-CLI-FAILED', { command: command.name, root: args.value('root') }));
299
372
  host.signal?.throwIfAborted();
300
373
  const result = await handler(context);
301
374
  host.signal?.throwIfAborted();
302
375
  return result;
303
376
  }
304
377
  catch (error) {
305
- if (host.signal?.aborted)
378
+ if (host.signal?.aborted) {
379
+ // Design row 27: an interruption names one next command too — the rerun a verb that had written supplies, or
380
+ // else this invocation again, exactly as it was typed.
381
+ const next = error instanceof Interrupted
382
+ ? error.next
383
+ : `Run "${['ia', command.name, ...argv].map(quote).join(' ')}" again.`;
306
384
  return {
307
385
  exitCode: 130,
308
386
  stdout: wantsJson(argv)
309
- ? JSON.stringify({ version: 1, ok: false, code: 'IA-CLI-INTERRUPTED', message: 'Interrupted.', exit: 130 }) +
310
- '\n'
387
+ ? JSON.stringify({
388
+ version: 1,
389
+ ok: false,
390
+ code: 'IA-CLI-INTERRUPTED',
391
+ message: 'Interrupted.',
392
+ exit: 130,
393
+ next,
394
+ }) + '\n'
311
395
  : '',
312
- stderr: error instanceof Interrupted ? `Interrupted. ${error.next}\n` : 'Interrupted.\n',
396
+ stderr: `Interrupted. ${next}\n`,
313
397
  };
314
- const raw = refusalOf(error);
398
+ }
399
+ const refused = { command: command.name, root: args?.value('root') };
400
+ const raw = refusalOf(error, refused);
315
401
  const refusal = raw.where === null && raw.at === null
316
402
  ? new Refusal(raw.code, raw.message, raw.exit, null, raw.next, `ia ${command.name}`)
317
403
  : raw;
318
- return renderRefusal(refusal, refusal.exit === 2 ? preliminary : caps, wantsJson(argv));
404
+ return renderRefusal(refusal, refusal.exit === 2 ? preliminary : caps, wantsJson(argv), refused);
319
405
  }
320
406
  }
321
407
  /** A refusal raised before or during parsing still has to honor §5, so `--json` is read from argv directly. */
@@ -323,6 +409,18 @@ const wantsJson = (argv) => {
323
409
  const end = argv.indexOf('--');
324
410
  return argv.slice(0, end === -1 ? argv.length : end).includes('--json');
325
411
  };
412
+ /** The `--root` and `--params` pairs a machine route admits (`runCli` in main.ts), the first of each, as typed. */
413
+ function machineOptions(rest) {
414
+ const kept = new Map();
415
+ for (let index = 0; index < rest.length; index += 1) {
416
+ const key = rest[index], value = rest[index + 1];
417
+ if ((key === '--root' || key === '--params') && value !== undefined && !kept.has(key)) {
418
+ kept.set(key, value);
419
+ index += 1;
420
+ }
421
+ }
422
+ return [...kept].flat();
423
+ }
326
424
  /**
327
425
  * §1.2's ordered table. The first match wins and the order is normative: step 4 precedes step 5 unconditionally,
328
426
  * so a legacy operation can never be shadowed by a consumer verb.
@@ -360,7 +458,15 @@ export async function dispatch(argv, host, legacy, extensions) {
360
458
  ...LEGACY_OPERATIONS,
361
459
  ...extensions.map((entry) => entry.token).filter((candidate) => !CORE_TOKENS.has(candidate)),
362
460
  ];
363
- const near = nearestTokens(token, admitted);
364
- return renderRefusal(new Refusal('IA-CLI-USAGE', `Unknown command ${token}`, 2, null, near.length === 0 ? 'Run "ia --help" for the commands this binary admits.' : `Did you mean ${near.join(', ')}?`, `ia ${token}`), caps, wantsJson(argv));
461
+ // Design row 27: one command, the nearest token with the rest of the invocation as typed; any other near token is
462
+ // named, not offered as a second command. A machine route admits only its two options, so only those are kept.
463
+ const [nearest, ...also] = nearestTokens(token, admitted);
464
+ const others = also.length === 0 ? '' : ` Also near: ${also.join(', ')}.`;
465
+ const rest = nearest !== undefined && LEGACY_OPERATIONS.includes(nearest)
466
+ ? machineOptions(argv.slice(1))
467
+ : argv.slice(1);
468
+ return renderRefusal(new Refusal('IA-CLI-USAGE', `Unknown command ${token}`, 2, null, nearest === undefined
469
+ ? 'Run "ia --help" for the commands this binary admits.'
470
+ : `Did you mean "${['ia', nearest, ...rest].map(quote).join(' ')}"?${others}`, `ia ${token}`), caps, wantsJson(argv));
365
471
  }
366
472
  //# sourceMappingURL=consumer.js.map