@inventarch/cli 1.1.1 → 2.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 (116) hide show
  1. package/LANGUAGE.md +2 -2
  2. package/README.md +17 -4
  3. package/SPEC.md +51 -7
  4. package/assets/base/0305ca741b1dfec97ff35fbeb36d4a66a0c9c0614b730fe14fcdac0f1565e28a.ia.tgz +0 -0
  5. package/assets/base.json +3 -3
  6. package/assets/host/3d2c8530db8d14755410b17be8228a230d88de96f9dc78f953979d3ca7c6ea62.tgz +0 -0
  7. package/assets/host.json +4 -4
  8. package/assets/vocabulary.json +436 -4
  9. package/dist/bundled-base.d.ts +18 -0
  10. package/dist/bundled-base.d.ts.map +1 -0
  11. package/dist/bundled-base.js +44 -0
  12. package/dist/bundled-base.js.map +1 -0
  13. package/dist/capture.d.ts +108 -0
  14. package/dist/capture.d.ts.map +1 -0
  15. package/dist/capture.js +346 -0
  16. package/dist/capture.js.map +1 -0
  17. package/dist/claude-cli.js +1 -1
  18. package/dist/claude-cli.js.map +1 -1
  19. package/dist/commands.d.ts +23 -1
  20. package/dist/commands.d.ts.map +1 -1
  21. package/dist/commands.js +201 -10
  22. package/dist/commands.js.map +1 -1
  23. package/dist/compile.d.ts +5 -0
  24. package/dist/compile.d.ts.map +1 -1
  25. package/dist/compile.js +40 -51
  26. package/dist/compile.js.map +1 -1
  27. package/dist/consumer.d.ts +48 -7
  28. package/dist/consumer.d.ts.map +1 -1
  29. package/dist/consumer.js +142 -29
  30. package/dist/consumer.js.map +1 -1
  31. package/dist/decline.d.ts.map +1 -1
  32. package/dist/decline.js +15 -7
  33. package/dist/decline.js.map +1 -1
  34. package/dist/distribute.d.ts +68 -16
  35. package/dist/distribute.d.ts.map +1 -1
  36. package/dist/distribute.js +243 -110
  37. package/dist/distribute.js.map +1 -1
  38. package/dist/doctor.d.ts.map +1 -1
  39. package/dist/doctor.js +113 -60
  40. package/dist/doctor.js.map +1 -1
  41. package/dist/format.d.ts +2 -2
  42. package/dist/format.d.ts.map +1 -1
  43. package/dist/format.js +19 -11
  44. package/dist/format.js.map +1 -1
  45. package/dist/home-remedy.d.ts +8 -4
  46. package/dist/home-remedy.d.ts.map +1 -1
  47. package/dist/home-remedy.js +8 -4
  48. package/dist/home-remedy.js.map +1 -1
  49. package/dist/host-projection.d.ts +73 -6
  50. package/dist/host-projection.d.ts.map +1 -1
  51. package/dist/host-projection.js +296 -38
  52. package/dist/host-projection.js.map +1 -1
  53. package/dist/host.d.ts +106 -30
  54. package/dist/host.d.ts.map +1 -1
  55. package/dist/host.js +270 -139
  56. package/dist/host.js.map +1 -1
  57. package/dist/init.d.ts +285 -37
  58. package/dist/init.d.ts.map +1 -1
  59. package/dist/init.js +1270 -205
  60. package/dist/init.js.map +1 -1
  61. package/dist/inspect.d.ts +26 -2
  62. package/dist/inspect.d.ts.map +1 -1
  63. package/dist/inspect.js +117 -52
  64. package/dist/inspect.js.map +1 -1
  65. package/dist/main.d.ts.map +1 -1
  66. package/dist/main.js +3 -1
  67. package/dist/main.js.map +1 -1
  68. package/dist/migration-journal.d.ts +35 -0
  69. package/dist/migration-journal.d.ts.map +1 -0
  70. package/dist/migration-journal.js +205 -0
  71. package/dist/migration-journal.js.map +1 -0
  72. package/dist/next.d.ts +21 -0
  73. package/dist/next.d.ts.map +1 -0
  74. package/dist/next.js +210 -0
  75. package/dist/next.js.map +1 -0
  76. package/dist/operation-help.d.ts.map +1 -1
  77. package/dist/operation-help.js +14 -3
  78. package/dist/operation-help.js.map +1 -1
  79. package/dist/pack.d.ts +3 -1
  80. package/dist/pack.d.ts.map +1 -1
  81. package/dist/pack.js +56 -11
  82. package/dist/pack.js.map +1 -1
  83. package/dist/position.d.ts +22 -0
  84. package/dist/position.d.ts.map +1 -0
  85. package/dist/position.js +242 -0
  86. package/dist/position.js.map +1 -0
  87. package/dist/project.d.ts +42 -0
  88. package/dist/project.d.ts.map +1 -0
  89. package/dist/project.js +232 -0
  90. package/dist/project.js.map +1 -0
  91. package/dist/read.d.ts +31 -0
  92. package/dist/read.d.ts.map +1 -0
  93. package/dist/read.js +152 -0
  94. package/dist/read.js.map +1 -0
  95. package/dist/render.d.ts +19 -0
  96. package/dist/render.d.ts.map +1 -1
  97. package/dist/render.js +44 -1
  98. package/dist/render.js.map +1 -1
  99. package/dist/session.d.ts +12 -1
  100. package/dist/session.d.ts.map +1 -1
  101. package/dist/session.js +68 -6
  102. package/dist/session.js.map +1 -1
  103. package/dist/user-host.d.ts.map +1 -1
  104. package/dist/user-host.js +7 -5
  105. package/dist/user-host.js.map +1 -1
  106. package/dist/validate.d.ts +1 -2
  107. package/dist/validate.d.ts.map +1 -1
  108. package/dist/validate.js +6 -27
  109. package/dist/validate.js.map +1 -1
  110. package/dist/vocabulary.d.ts +4 -0
  111. package/dist/vocabulary.d.ts.map +1 -1
  112. package/dist/vocabulary.js +12 -7
  113. package/dist/vocabulary.js.map +1 -1
  114. package/package.json +6 -6
  115. package/assets/base/78bff5eb3188b628c06d2f1cf1477fb1bfcea874ec3863ae112b4972b8e81517.ia.tgz +0 -0
  116. package/assets/host/b97e367bbf15db09f552d6bd6dd3701210efe77931d34b57ccb85240957aba61.tgz +0 -0
@@ -26,30 +26,31 @@
26
26
  * the lock and never chooses a registry.
27
27
  *
28
28
  * Registered host projections (docs/specs/host-registration/README.md §4, "install, update, remove"):
29
- * a workspace that owns a projection for a host — its `<host>-projection.json` state exists — lists installed
30
- * distributions in it, so a change to the installed set changes the projection. `--apply` refuses before anything is
31
- * acquired or written when an owned projection file was edited by hand, because the refresh would refuse it, and
32
- * re-renders each registered projection after the install commits. MCP and hook entries do not depend on the
33
- * installed set and are not touched. `restore` reinstalls the locked generation, whose admitted systems are
29
+ * a workspace that owns a projection for a host — its `<host>-projection.json` state exists — renders the position
30
+ * packet of its admitted records, so a change to the installed set changes the projection. `--apply` refuses before
31
+ * anything is acquired or written when an owned projection file was edited by hand, or when the steward guard the
32
+ * refresh would retire (B11) cannot be removed, because the refresh would refuse either, and re-renders each
33
+ * registered projection after the install commits through `applyHostProjection`, the one writer of projection files,
34
+ * which retires such a guard before any projection file changes and writes the receipt; the plan, and so the question
35
+ * an apply asks, names each refresh that retires one (`retire`). MCP entries do not depend on the installed set and are
36
+ * not touched. `restore` reinstalls the locked generation, whose admitted systems are
34
37
  * unchanged, so it neither checks nor refreshes. A refresh that fails after the install committed cannot undo the
35
38
  * install, and it is not hidden either: like `ia init --host` after initialization, the command refuses at class 3
36
39
  * with the service's code, message and file, and its next action opens "The installation is applied." before the
37
40
  * repair, so a script sees the failure and a reader sees what did happen. `ia doctor` reports the drift until then.
38
41
  */
39
- import { existsSync } from 'node:fs';
40
- import { resolve } from 'node:path';
41
- import { WORKSPACE_PROJECTION_MARKER } from '@inventarch/compliance';
42
+ import { readBase } from './bundled-base.js';
42
43
  import { canonicalDistributionJson, decodeDistributionRequests, DISTRIBUTION_ENGINE_VERSION, INSTALL_PATHS, } from '@inventarch/db/distribution';
43
- import { ARCHIVE_CACHE, applyInstallation, planInstallation } from '@inventarch/distribution/install';
44
- import { applyProjection, observeProjection, planProjection } from '@inventarch/distribution/projection';
44
+ import { ARCHIVE_CACHE, applyInstallation, cacheArchive, planInstallation } from '@inventarch/distribution/install';
45
+ import { legacyProjectionActions, observeProjection } from '@inventarch/distribution/projection';
46
+ import { PACKET_MARKER } from '@inventarch/runtime';
45
47
  import { registryChooser, registryLocation, registryWithdrawals, resolveFromRegistries, unpublishedPins, } from '@inventarch/distribution/registry';
46
48
  import { resolveReleases } from '@inventarch/distribution/resolve';
47
- import { WORKSPACE_HOSTS } from '@inventarch/distribution/hosts';
48
49
  import { acquireArtifact, cachedCandidates, planRestore, pruneLockRequest, readInstalledState, readWorkspaceJson, readWorkspaceLock, resolveCatalog, writeWorkOutput, } from '@inventarch/distribution/services';
49
50
  import { UsageError } from './args.js';
50
- import { confirm, Refusal, refusalOf, requireRoot } from './consumer.js';
51
- import { renderProjectionFor } from './host-projection.js';
52
- import { hostNext, lockRefusal, projectionRepair, refusedPath, STATE } from './host.js';
51
+ import { confirm, Refusal, refusalOf, requireRoot, serviceNext } from './consumer.js';
52
+ import { applyHostProjection, ownsGuard, planRetirement, preflightReceipt, renderProjectionFor, } from './host-projection.js';
53
+ import { GUARD_SCOPE, hostNext, projectedHosts, projectionFailure, projectionRepair, projectionRerun, refusedPath, SETTINGS, } from './host.js';
53
54
  import { codeOf } from './session.js';
54
55
  import { atom, commandFacts, document, entry, fieldRows, headerLine, quote, sectionLabel, truncateDigest, words, } from './render.js';
55
56
  /** §2.8: the id grammar is `provider/name`, and a positional may pin it with `@<range>`. */
@@ -83,30 +84,48 @@ export function changeRows(plan, previous) {
83
84
  }
84
85
  return rows;
85
86
  }
86
- const RETRY = 'Retry when the host is reachable, or add the archive to a local catalog entry {"path":"...","withdrawn":false} and re-run with --catalog <file> --offline.';
87
- const REGISTRY_RETRY = 'Check network access to the registry named above, or pass --registry <url|dir>, map the provider in .ia/registries.json, or use --catalog <file>.';
88
- const DEFAULT_RETRY = 'Pass --registry <url|dir>, map the provider to a registry in .ia/registries.json, or install from a local catalog with --catalog <file>.';
89
- const OVERSIZE = 'The registry named above serves a document over the 4 MiB limit, and retrying will not change that. Choose another registry with --registry <url|dir> or .ia/registries.json, or use --catalog <file>.';
90
- const INCOMPLETE = 'That registry directory is incomplete: it lists a release whose artifact file is missing. Re-add the release with "ia-distribution registry add --registry <dir> --archive <file>", or choose another registry with --registry <url|dir> or .ia/registries.json.';
91
- /** Registry spec §4's remedy for an unmapped provider; `ia doctor` names the same one. */
87
+ const RETRY = (reruns) => `Retry "${reruns.again}" when the host is reachable.`;
88
+ const REGISTRY_RETRY = (reruns) => `Check network access to the registry named above, then retry "${reruns.again}".`;
89
+ const DEFAULT_RETRY = (reruns) => `Map the provider to a registry in .ia/registries.json, then run "${reruns.again}".`;
90
+ /** A limit a retry cannot fix: another registry is chosen at the level that chose this one, which outranks those below. */
91
+ function oversized(reruns) {
92
+ const why = 'The registry named above serves a document over the 4 MiB limit, and retrying will not change that.';
93
+ if (reruns.chosen === 'flag')
94
+ return `${why} Run "${reruns.another}" naming another registry.`;
95
+ if (reruns.chosen === 'variable')
96
+ return `${why} Set IA_REGISTRY to another registry, then run "${reruns.again}".`;
97
+ return `${why} Map the provider to another registry in .ia/registries.json, then run "${reruns.again}".`;
98
+ }
99
+ /** The message names the directory registry, and the release is re-added to that one. */
100
+ const INCOMPLETE_REGISTRY = /^Registry (.+) has no artifacts\//;
101
+ const INCOMPLETE = (dir) => `That registry directory is incomplete: it lists a release whose artifact file is missing. Re-add the release with "ia-distribution registry add --registry ${quote(dir)} --archive <file>".`;
102
+ /**
103
+ * Registry spec §4's remedy for an unmapped provider, as `ia doctor` prints it. The exported 1.x text is unchanged
104
+ * (decision release-bump); a refusal names `UNMAPPED_NEXT` instead, whose one command is the rerun (design row 27).
105
+ */
92
106
  export const UNMAPPED = "Every requested and locked package's provider needs a registry. Map the provider to an HTTPS URL or a workspace directory in .ia/registries.json, or pass --registry <url|dir>.";
93
- const LICENSED = 'This CLI has no licensed acquisition path. Obtain the archive through its licensed channel, then install it from a local catalog with --catalog <file>.';
107
+ const UNMAPPED_NEXT = "Every requested and locked package's provider needs a registry: map the provider to an HTTPS URL or a workspace directory in .ia/registries.json.";
108
+ const LICENSED = (reruns) => `This CLI has no licensed acquisition path. Obtain the archive through its licensed channel, then install it from a local catalog with "${reruns.local}".`;
94
109
  const REMOTE_LIMIT = /^(?:Remote archive|Registry document) /;
95
110
  const SERVICE_CODE = /^IA-[A-Z]+-[A-Z-]+$/;
96
- /** The repair for a cached archive that does not verify: the cache holds copies, and the consumer has no verb that cleans it. */
97
- const deleteCached = (path) => `Delete ${path}, then re-run the command; a published archive is fetched again from its registry or catalog.`;
98
- function unavailable(message, route) {
111
+ /**
112
+ * The repair for a cached archive that does not verify: the cache holds copies, and the consumer has no verb that
113
+ * cleans it. An `--offline` rerun reads only the cache, so the rerun is the online one, which fetches the copy again.
114
+ */
115
+ const deleteCached = (path, reruns) => `Delete ${path}, then rerun "${reruns.online}"; a published archive is fetched again from its registry or catalog.`;
116
+ function unavailable(message, route, reruns) {
99
117
  if (message.startsWith('The default registry '))
100
- return DEFAULT_RETRY;
118
+ return DEFAULT_RETRY(reruns);
101
119
  if (message.startsWith('Registry document '))
102
- return OVERSIZE;
120
+ return oversized(reruns);
103
121
  if (message.startsWith('Registry request '))
104
- return REGISTRY_RETRY;
105
- if (/^Registry .+ has no artifacts\//.test(message))
106
- return INCOMPLETE;
107
- return route === 'registry' ? REGISTRY_RETRY : RETRY;
122
+ return REGISTRY_RETRY(reruns);
123
+ const incomplete = INCOMPLETE_REGISTRY.exec(message);
124
+ if (incomplete !== null)
125
+ return INCOMPLETE(incomplete[1]);
126
+ return route === 'registry' ? REGISTRY_RETRY(reruns) : RETRY(reruns);
108
127
  }
109
- async function acquiring(run, where, route) {
128
+ async function acquiring(run, where, route, reruns) {
110
129
  try {
111
130
  return await run();
112
131
  }
@@ -120,16 +139,17 @@ async function acquiring(run, where, route) {
120
139
  // A refusal located at a cached archive (a corrupt cached lock pin, registry spec §5.1) is repaired by deleting it.
121
140
  const cachedFile = own !== null && own.startsWith(`${ARCHIVE_CACHE}/`) ? own : null;
122
141
  if (code === 'IA-DIST-ARTIFACT-UNAVAILABLE' || (code === 'IA-DIST-LIMIT-EXCEEDED' && REMOTE_LIMIT.test(message)))
123
- throw new Refusal(code, message, 4, at, cachedFile !== null ? deleteCached(cachedFile) : unavailable(message, route));
142
+ throw new Refusal(code, message, 4, at, cachedFile !== null ? deleteCached(cachedFile, reruns) : unavailable(message, route, reruns));
124
143
  if (code === '')
125
- throw new Refusal('IA-CLI-FAILED', `Artifact transport failed: ${message}`, 4, at, route === 'registry' ? REGISTRY_RETRY : RETRY);
144
+ throw new Refusal('IA-CLI-FAILED', `Artifact transport failed: ${message}`, 4, at, route === 'registry' ? REGISTRY_RETRY(reruns) : RETRY(reruns));
126
145
  if (code === 'IA-DIST-REGISTRY-UNMAPPED')
127
- throw new Refusal(code, message, 3, at, UNMAPPED);
146
+ throw new Refusal(code, message, 3, at, `${UNMAPPED_NEXT} Then run "${reruns.again}".`);
128
147
  if (code === 'IA-DIST-LICENSE-REQUIRED')
129
- throw new Refusal(code, message, 3, at, LICENSED);
130
- // A service refusal the service located keeps its code and class 3, and gains its location (§4.3).
148
+ throw new Refusal(code, message, 3, at, LICENSED(reruns));
149
+ // A service refusal the service located keeps its code and class 3, and gains its location (§4.3) and the
150
+ // rerun after the file it names is repaired.
131
151
  if (!(error instanceof Refusal) && own !== null)
132
- throw new Refusal(code, message, 3, at, cachedFile !== null ? deleteCached(cachedFile) : null);
152
+ throw new Refusal(code, message, 3, at, cachedFile !== null ? deleteCached(cachedFile, reruns) : `Fix ${own}, then rerun "${reruns.again}".`);
133
153
  throw error;
134
154
  }
135
155
  }
@@ -137,19 +157,19 @@ async function acquiring(run, where, route) {
137
157
  * Registry spec §5.4: `--offline` without `--catalog` resolves from the workspace cache, reaching only the ids this
138
158
  * command can need — its requests, the lock's packages and their dependencies — so an unrelated stale duplicate in
139
159
  * the cache never reaches resolution. A cached file that cannot be read is located, and its repair is to delete it:
140
- * the cache holds copies, and the consumer has no verb that cleans it. A cache over its bound names the directory
141
- * and the two online sources.
160
+ * the cache holds copies, and the consumer has no verb that cleans it. A cache over its bound names the directory to
161
+ * prune before the rerun.
142
162
  */
143
- function cached(root, reach) {
163
+ function cached(root, reach, reruns) {
144
164
  try {
145
165
  return cachedCandidates({ root, reach });
146
166
  }
147
167
  catch (error) {
148
168
  const refusal = refusalOf(error), path = refusedPath(error);
149
169
  if (path !== null && path.startsWith(`${ARCHIVE_CACHE}/`))
150
- throw new Refusal(refusal.code, refusal.message, 3, { path }, deleteCached(path));
170
+ throw new Refusal(refusal.code, refusal.message, 3, { path }, deleteCached(path, reruns));
151
171
  if (refusal.code === 'IA-DIST-LIMIT-EXCEEDED')
152
- throw new Refusal(refusal.code, refusal.message, 3, null, `Remove archives this workspace no longer needs from ${ARCHIVE_CACHE}/, or resolve online with --registry <url|dir> or --catalog <file> instead of --offline.`);
172
+ throw new Refusal(refusal.code, refusal.message, 3, null, `Remove archives this workspace no longer needs from ${ARCHIVE_CACHE}/, then rerun "${reruns.again}".`);
153
173
  throw error;
154
174
  }
155
175
  }
@@ -172,7 +192,7 @@ function registrySources(choices) {
172
192
  * reaching for rather than the file that listed it. The acquisition is the installer's own and the resolution that
173
193
  * follows reads the same bytes back from the cache it filled; nothing here decides what a catalog entry means.
174
194
  */
175
- async function warm(root, entries, offline, signal) {
195
+ async function warm(root, entries, offline, reruns, signal) {
176
196
  signal?.throwIfAborted();
177
197
  if (offline || !Array.isArray(entries))
178
198
  return;
@@ -180,13 +200,16 @@ async function warm(root, entries, offline, signal) {
180
200
  if (row === null || typeof row !== 'object' || typeof row.url !== 'string' || typeof row.digest !== 'string')
181
201
  continue;
182
202
  const url = row.url, digest = row.digest;
183
- await acquiring(() => acquireArtifact({ root, url, digest, signal }), url, 'catalog');
203
+ await acquiring(() => acquireArtifact({ root, url, digest, signal }), url, 'catalog', reruns);
184
204
  }
185
205
  }
186
206
  /** A plan that resolves from registries without a chooser is a caller defect, not a user's refusal. */
187
207
  function chooserOf(request) {
188
208
  if (request.choose === undefined)
189
- throw new Refusal('IA-CLI-FAILED', `ia ${request.operation} resolves from registries but was given no registry chooser`, 3);
209
+ throw new Refusal('IA-CLI-FAILED', `ia ${request.operation} resolves from registries but was given no registry chooser`, 3, null, serviceNext('IA-CLI-FAILED', {
210
+ command: request.operation,
211
+ root: request.rooted === true ? request.root : undefined,
212
+ }));
190
213
  return request.choose;
191
214
  }
192
215
  /** §2.8: a positional adds or repins one direct request; `--requests` supplies the whole set the native path reads. */
@@ -204,38 +227,43 @@ export function mergeRequests(previous, ids) {
204
227
  * `update <id>` names one direct request. `--to` repins its range; without `--to` the request keeps its range and
205
228
  * only the preference changes (registry spec §6.2). Either way an id that is not a direct request is refused.
206
229
  */
207
- function repin(previous, id, to) {
230
+ function repin(previous, id, to, reruns) {
208
231
  if (previous === undefined)
209
- throw new Refusal('IA-DIST-INPUT-INVALID', 'Update requires an existing installation', 3, null, 'Run "ia install <id>[@<range>]" first, or "ia doctor" for the installed state.');
232
+ throw new Refusal('IA-DIST-INPUT-INVALID', 'Update requires an existing installation', 3, null, `Run "${reruns.install}" first.`);
210
233
  if (!previous.requests.some((request) => request.id === id))
211
- throw new Refusal('IA-DIST-INPUT-INVALID', `${id} is not a direct request of this installation`, 3, null, 'Run "ia inspect" for the installed generation and name one of its direct requests.');
234
+ throw new Refusal('IA-DIST-INPUT-INVALID', `${id} is not a direct request of this installation`, 3, null, `Run "${reruns.inspect}" for the installed generation and name one of its direct requests.`);
212
235
  return to === undefined
213
236
  ? previous.requests
214
237
  : previous.requests.map((request) => (request.id === id ? { id, range: to } : request));
215
238
  }
216
239
  /**
217
- * Host registration spec §4: the hosts whose projection this workspace owns. Ownership is the state file's presence,
218
- * as `ia host` and `ia doctor` decide it. `restore` changes no admitted system, so it has none to refresh.
240
+ * Host registration spec §4: the hosts whose projection this workspace owns (`projectedHosts`), a projection `ia
241
+ * project` wrote without a registration included. `restore` changes no admitted system, so it has none to refresh.
219
242
  */
220
- export const registeredProjections = (root, operation) => operation === 'restore' ? [] : WORKSPACE_HOSTS.filter((host) => existsSync(resolve(root, STATE.projection(host))));
243
+ export const registeredProjections = (root, operation) => operation === 'restore' ? [] : projectedHosts(root);
221
244
  /**
222
245
  * Host registration spec §4: `--apply` refuses before any install write when a registered projection would refuse.
223
246
  * A hand edit to an owned file is the refusal the refresh would raise (§6.3), so it is found here, before
224
- * acquisition, the saved plan or the lock is touched; the remedy is the one `ia host` and `ia doctor` name for it.
247
+ * acquisition, the saved plan or the lock is touched; the remedy is the one `ia doctor` names for it, its rerun
248
+ * `projectionRerun`'s: `ia host <host> --apply` for a registered host, `ia project <host> --apply` for a projection
249
+ * `ia project` wrote without a registration (task ia-project-verb).
225
250
  * Missing, outdated and unowned files do not block: the refresh rewrites the first two and never touches the third.
226
251
  * A file the mechanism cannot read — an unreadable ownership state, an aliased or oversized managed file — would
227
- * refuse the refresh too, so it is refused here, located at that file, with the repair `ia host` names for it.
252
+ * refuse the refresh too, so it is refused here, located at that file, with the repair `ia host` names for it. So is
253
+ * a steward-guard registration the refresh's retirement (B11) would refuse: an unreadable guard state, or a guard
254
+ * group changed by hand; a pending host journal that refuses the retirement's plan names its own recovery.
228
255
  */
229
256
  export function requireProjectionsClean(root, hosts, rooted) {
230
257
  for (const host of hosts) {
231
- const rerun = `ia host ${host} --apply`;
258
+ const rerun = projectionRerun(root, host);
232
259
  let drifts;
233
260
  try {
234
- drifts = observeProjection({ root, host, artifacts: null, marker: WORKSPACE_PROJECTION_MARKER });
261
+ planRetirement(root, host);
262
+ preflightReceipt(root, host);
263
+ drifts = observeProjection({ root, host, artifacts: null, marker: PACKET_MARKER });
235
264
  }
236
265
  catch (error) {
237
- const refusal = refusalOf(error), path = refusedPath(error) ?? STATE.projection(host);
238
- throw new Refusal(refusal.code, refusal.message, 3, { path }, hostNext(projectionRepair(host, path, rerun), host, root, rooted));
266
+ throw projectionFailure(error, root, host, rerun);
239
267
  }
240
268
  const changed = drifts.find((drift) => drift.drift === 'changed');
241
269
  if (changed !== undefined)
@@ -243,26 +271,20 @@ export function requireProjectionsClean(root, hosts, rooted) {
243
271
  }
244
272
  }
245
273
  /**
246
- * Host registration spec §4: after the install committed, a registered projection is re-rendered from the records and
247
- * the new lock and applied through the projection mechanism, which re-checks every file itself. A refusal comes back
248
- * rather than being thrown, so every registered host is attempted before the command refuses. A file the mechanism
274
+ * Host registration spec §4: after the install committed, a registered projection is re-rendered from the records of
275
+ * the new generation and applied through `applyHostProjection`, which retires an owned steward guard first (B11),
276
+ * re-checks every file itself and writes the receipt (B12); the retirement comes back as `retired`. A refusal comes
277
+ * back rather than being thrown, so every registered host is attempted before the command refuses. A file the mechanism
249
278
  * located gets `ia host`'s repair for it; a held host lock names the recovery that clears a dead holder's; a CLI
250
- * refusal (the workspace no longer admits, the renderer refused) keeps its own next action; anything else names the
251
- * rerun.
279
+ * refusal (the workspace no longer admits) keeps its own next action; anything else names the rerun, which is
280
+ * `projectionRerun`'s, as `ia doctor` names it.
252
281
  */
253
282
  function refreshed(view, host) {
254
283
  try {
255
- const artifacts = renderProjectionFor(view.root, host);
256
- applyProjection(planProjection({ root: view.root, host, artifacts, marker: WORKSPACE_PROJECTION_MARKER }));
257
- return null;
284
+ return applyHostProjection(view.root, host, renderProjectionFor(view.root, host)).guard;
258
285
  }
259
286
  catch (error) {
260
- const busy = lockRefusal(error, view.root);
261
- if (busy !== null)
262
- return busy;
263
- const refusal = refusalOf(error), path = refusedPath(error), rerun = `ia host ${host} --apply`;
264
- const next = path !== null ? projectionRepair(host, path, rerun) : (refusal.next ?? `Run "${rerun}" to finish.`);
265
- return new Refusal(refusal.code, refusal.message, 3, path === null ? refusal.where : { path }, hostNext(next, host, view.root, view.rooted));
287
+ return projectionFailure(error, view.root, host, projectionRerun(view.root, host));
266
288
  }
267
289
  }
268
290
  /**
@@ -283,9 +305,64 @@ function installedLock(root, operation) {
283
305
  throw error;
284
306
  }
285
307
  }
308
+ /**
309
+ * The `Reruns` of a request that supplies none (a 1.x caller of this published function), spelled from its own fields
310
+ * as `rerunsOf` spells them from the parsed arguments: `--root` when the request says it was named, the registry
311
+ * chosen by the per-provider map, since the request carries no `--registry` value.
312
+ */
313
+ function requestReruns(request) {
314
+ const { operation, to, root } = request;
315
+ const apply = operation === 'restore' ? ' --apply --yes' : '';
316
+ const spell = (named, variant = {}) => {
317
+ const parts = [`ia ${named}`, ...(variant.ids ?? request.ids).map(quote)];
318
+ if (named === 'update' && to !== undefined)
319
+ parts.push('--to', quote(to));
320
+ if (request.requestsFile !== undefined)
321
+ parts.push('--requests', quote(request.requestsFile));
322
+ if (variant.source !== undefined)
323
+ parts.push(...variant.source);
324
+ else if (request.catalog !== undefined)
325
+ parts.push('--catalog', quote(request.catalog));
326
+ if (request.planOut !== undefined)
327
+ parts.push('--plan-out', quote(request.planOut));
328
+ if (variant.source === undefined && variant.online !== true && request.offline)
329
+ parts.push('--offline');
330
+ if (request.allowWithdrawn)
331
+ parts.push('--allow-withdrawn');
332
+ if (request.rooted === true)
333
+ parts.push('--root', quote(root));
334
+ return parts.join(' ');
335
+ };
336
+ return {
337
+ again: `${spell(operation)}${apply}`,
338
+ online: `${spell(operation, { online: true })}${apply}`,
339
+ local: `${spell(operation, { source: ['--catalog', '<file>'] })}${apply}`,
340
+ chosen: 'map',
341
+ another: `${spell(operation, { source: ['--registry', '<url|dir>'] })}${apply}`,
342
+ install: spell('install', { ids: request.ids.map((id) => (to === undefined ? id : `${id}@${to}`)) }),
343
+ inspect: `ia inspect${request.rooted === true ? ` --root ${quote(root)}` : ''}`,
344
+ };
345
+ }
286
346
  export async function collectPlan(request) {
287
347
  request.signal?.throwIfAborted();
288
348
  const { root, operation } = request;
349
+ const reruns = request.reruns ?? requestReruns(request);
350
+ /**
351
+ * A file the invocation named (`--catalog`, `--requests`), read as the service reads it; one that is not there names
352
+ * the rerun with that one value to correct, the service's code and message carried through unchanged (§4.1).
353
+ */
354
+ const supplied = (path, option) => {
355
+ try {
356
+ return readWorkspaceJson({ root, path });
357
+ }
358
+ catch (error) {
359
+ const message = error instanceof Error ? error.message : String(error);
360
+ if (codeOf(error, '') !== 'IA-DIST-INPUT-INVALID' || !message.endsWith(`Missing input ${path}`))
361
+ throw error;
362
+ const rerun = option === 'catalog' ? reruns.local : reruns.again.replace(`--requests ${quote(path)}`, '--requests <file>');
363
+ throw new Refusal('IA-DIST-INPUT-INVALID', message, 3, null, `Run "${rerun}" naming an existing ${option === 'catalog' ? 'catalog' : 'requests'} file.`);
364
+ }
365
+ };
289
366
  const previous = installedLock(root, operation);
290
367
  let plan;
291
368
  let withdrawn = [];
@@ -294,6 +371,15 @@ export async function collectPlan(request) {
294
371
  if (operation === 'restore') {
295
372
  // One lock is read, and the withdrawal check and the plan both use that same object (registry spec §6.3).
296
373
  const lock = readWorkspaceLock({ root });
374
+ if (request.packageRoot !== undefined) {
375
+ const base = readBase(request.packageRoot);
376
+ const locked = lock.packages.find((row) => row.id === base.pin.id);
377
+ if (locked?.archive === base.pin.archive) {
378
+ if (locked.manifest !== base.pin.manifest || locked.version !== base.pin.version)
379
+ throw new Refusal('IA-DIST-INPUT-INVALID', 'The locked bundled base manifest or version differs from its verified archive', 3, { path: INSTALL_PATHS.lock }, `Restore the exact portable lock from source control, then run "${reruns.again}".`);
380
+ cacheArchive(root, base.bytes, base.pin.archive);
381
+ }
382
+ }
297
383
  if (request.catalog === undefined && !request.offline) {
298
384
  const choose = chooserOf(request);
299
385
  const restored = await acquiring(async () => {
@@ -307,7 +393,7 @@ export async function collectPlan(request) {
307
393
  withdrawnRefusalPrefix,
308
394
  withdrawn: pins,
309
395
  });
310
- }, null, 'registry');
396
+ }, null, 'registry', reruns);
311
397
  plan = restored.plan;
312
398
  withdrawn = restored.withdrawn;
313
399
  // The registries asked: every locked package's except an unpublished cached pin, which no registry lists (§6.3).
@@ -315,8 +401,8 @@ export async function collectPlan(request) {
315
401
  registries = registrySources(lock.packages.filter((pkg) => !unpublished.has(pkg.id)).map((pkg) => choose(pkg.id)));
316
402
  }
317
403
  else {
318
- const entries = request.offline ? undefined : readWorkspaceJson({ root, path: request.catalog });
319
- await warm(root, entries, request.offline, request.signal);
404
+ const entries = request.offline ? undefined : supplied(request.catalog, 'catalog');
405
+ await warm(root, entries, request.offline, reruns, request.signal);
320
406
  const restored = await acquiring(() => planRestore({
321
407
  root,
322
408
  signal: request.signal,
@@ -325,7 +411,7 @@ export async function collectPlan(request) {
325
411
  allowWithdrawn: request.allowWithdrawn,
326
412
  withdrawnRefusalPrefix,
327
413
  ...(request.offline ? {} : { catalog: entries }),
328
- }), request.catalog ?? null, 'catalog');
414
+ }), request.catalog ?? null, 'catalog', reruns);
329
415
  plan = restored.plan;
330
416
  withdrawn = restored.withdrawn;
331
417
  }
@@ -336,21 +422,18 @@ export async function collectPlan(request) {
336
422
  else {
337
423
  const updated = operation === 'update' ? request.ids[0] : undefined;
338
424
  const requests = updated !== undefined
339
- ? repin(previous, updated, request.to)
425
+ ? repin(previous, updated, request.to, reruns)
340
426
  : request.requestsFile === undefined
341
427
  ? mergeRequests(previous, request.ids)
342
- : decodeDistributionRequests(readWorkspaceJson({ root, path: request.requestsFile }));
428
+ : decodeDistributionRequests(supplied(request.requestsFile, 'requests'));
343
429
  let choices;
344
430
  if (request.catalog !== undefined) {
345
- const entries = readWorkspaceJson({ root, path: request.catalog });
346
- await warm(root, entries, request.offline, request.signal);
347
- choices = await acquiring(() => resolveCatalog({ root, entries, offline: request.offline, signal: request.signal }), request.catalog, 'catalog');
431
+ const entries = supplied(request.catalog, 'catalog');
432
+ await warm(root, entries, request.offline, reruns, request.signal);
433
+ choices = await acquiring(() => resolveCatalog({ root, entries, offline: request.offline, signal: request.signal }), request.catalog, 'catalog', reruns);
348
434
  }
349
435
  else if (request.offline) {
350
- choices = cached(root, [
351
- ...requests.map((dependency) => dependency.id),
352
- ...(previous?.packages ?? []).map((pkg) => pkg.id),
353
- ]);
436
+ choices = cached(root, [...requests.map((dependency) => dependency.id), ...(previous?.packages ?? []).map((pkg) => pkg.id)], reruns);
354
437
  }
355
438
  else {
356
439
  // Registry spec §5: metadata selection, then only the selected archives are fetched and verified. Only the ids the
@@ -374,7 +457,7 @@ export async function collectPlan(request) {
374
457
  named,
375
458
  choose,
376
459
  signal: request.signal,
377
- }), null, 'registry');
460
+ }), null, 'registry', reruns);
378
461
  choices = resolution.candidates;
379
462
  registries = registrySources(resolution.sources.values());
380
463
  }
@@ -395,6 +478,7 @@ export async function collectPlan(request) {
395
478
  content: () => Buffer.from(canonicalDistributionJson(plan)),
396
479
  refusal: 'A saved plan is written to a new file under .ia/work/',
397
480
  });
481
+ const refresh = request.refresh ?? registeredProjections(root, operation);
398
482
  return {
399
483
  operation,
400
484
  root,
@@ -405,7 +489,10 @@ export async function collectPlan(request) {
405
489
  registries,
406
490
  invocation: request.invocation,
407
491
  planOut,
408
- refresh: request.refresh ?? registeredProjections(root, operation),
492
+ refresh,
493
+ projectionFiles: refresh.map((host) => ({ host, files: legacyProjectionActions(root, host, PACKET_MARKER) })),
494
+ retire: refresh.filter((host) => ownsGuard(root, host)),
495
+ retired: [],
409
496
  rooted: request.rooted ?? false,
410
497
  };
411
498
  }
@@ -417,19 +504,18 @@ export async function collectPlan(request) {
417
504
  * refused refresh is class 3 naming the first refusal, and the count when more than one host refused (file comment).
418
505
  */
419
506
  export function applyPlan(view) {
420
- const applied = { ...view, applied: applyInstallation(view.plan) };
421
- const refused = view.refresh
422
- .map((host) => refreshed(applied, host))
423
- .filter((refusal) => refusal !== null);
507
+ const installed = { ...view, applied: applyInstallation(view.plan) };
508
+ const results = view.refresh.map((host) => [host, refreshed(installed, host)]), refused = results.flatMap(([, result]) => (result instanceof Refusal ? [result] : []));
424
509
  const [first] = refused;
425
510
  if (first !== undefined) {
426
511
  const count = refused.length > 1 ? ` ${refused.length} registered host projections were not refreshed; this is the first.` : '';
427
512
  throw new Refusal(first.code, first.message, 3, first.where, `The installation is applied.${count} ${first.next}`);
428
513
  }
429
- return applied;
514
+ return { ...installed, retired: results.flatMap(([host, result]) => (result === 'retired' ? [host] : [])) };
430
515
  }
431
516
  /**
432
- * The `--json` envelope (§2.8): `{version: 1, command, plan, applied?, refresh?, registries?, withdrawn?, planOut?}`.
517
+ * The `--json` envelope (§2.8): `{version: 1, command, plan, applied?, refresh?, retire?, retired?, registries?,
518
+ * withdrawn?, planOut?}`.
433
519
  *
434
520
  * - `plan` is the planner's own value, unchanged.
435
521
  * - `registries` (registry spec §6.1) is present only when registries were the source: one `{provider, base, level}`
@@ -446,8 +532,11 @@ export function planEnvelope(view) {
446
532
  plan: view.plan,
447
533
  // `applied` is applyInstallation's return, its `host: 'pending'` literal included (§2.8).
448
534
  ...(view.applied === null ? {} : { applied: view.applied }),
449
- // Host registration spec §4: the registered projections an apply refreshes.
450
- ...(view.refresh.length === 0 ? {} : { refresh: view.refresh }),
535
+ // Host registration spec §4: the registered projections an apply refreshes, those whose refresh retires the
536
+ // steward guard first (B11), and after an apply those whose refresh retired it.
537
+ ...(view.refresh.length === 0 ? {} : { refresh: view.refresh, projectionFiles: view.projectionFiles }),
538
+ ...(view.retire.length === 0 ? {} : { retire: view.retire }),
539
+ ...(view.retired.length === 0 ? {} : { retired: view.retired }),
451
540
  ...(view.registries.length === 0 ? {} : { registries: view.registries }),
452
541
  ...(view.withdrawn.length === 0 ? {} : { withdrawn: view.withdrawn }),
453
542
  ...(view.planOut === null ? {} : { planOut: view.planOut }),
@@ -519,11 +608,20 @@ const wouldWriteBlocks = (view, caps) => {
519
608
  ...projectionsBlocks(view, caps),
520
609
  ];
521
610
  };
522
- /** Host registration spec §4: the plan says which registered projections the apply re-renders. */
611
+ /**
612
+ * Host registration spec §4: the plan says which registered projections the apply re-renders, and which of those
613
+ * refreshes first retire the steward guard an earlier release registered (B11), with what that leaves unguarded.
614
+ */
523
615
  const projectionsBlocks = (view, caps) => view.refresh.length === 0
524
616
  ? []
525
617
  : [
526
- entry([words(`Registered host projections (${view.refresh.join(', ')}) are refreshed after apply.`)], { depth: 1, symbol: 'info' }, caps),
618
+ entry([
619
+ words(`Registered host projections (${view.refresh.join(', ')}) are refreshed after apply${view.retire.length === 0
620
+ ? ''
621
+ : `; the refresh first retires the steward guard registered in ${SETTINGS} (${view.retire.join(', ')})`}.`),
622
+ ], { depth: 1, symbol: 'info' }, caps),
623
+ ...view.projectionFiles.flatMap(({ host, files }) => files.map(({ path, action }) => entry([words(`${host}: ${path} ${action}${action === 'foreign' ? ' (left in place)' : ''}`)], { depth: 1, symbol: action === 'remove' ? 'removed' : 'info' }, caps))),
624
+ ...(view.retire.length === 0 ? [] : [entry([words(GUARD_SCOPE)], { depth: 1, symbol: 'info' }, caps)]),
527
625
  ];
528
626
  /**
529
627
  * What an applied plan says about hosts. `applied.host` is applyInstallation's literal and is never presented as
@@ -532,7 +630,9 @@ const projectionsBlocks = (view, caps) => view.refresh.length === 0
532
630
  */
533
631
  const hostLine = (view) => view.refresh.length === 0
534
632
  ? 'Host state is not reported by the installer; run "ia doctor" for it.'
535
- : `Registered host projections (${view.refresh.join(', ')}) were refreshed; run "ia doctor" for host state.`;
633
+ : `Registered host projections (${view.refresh.join(', ')}) were refreshed${view.retired.length === 0
634
+ ? ''
635
+ : `, and the steward guard an earlier release registered was retired first (${view.retired.join(', ')})`}; run "ia doctor" for host state.`;
536
636
  export function renderPlan(view, caps) {
537
637
  const blocks = [
538
638
  headerBlock(view, caps),
@@ -583,23 +683,54 @@ export const renderDeclined = (view, caps) => document([
583
683
  entry([words('Nothing was applied.')], { depth: 0, symbol: 'info' }, caps),
584
684
  entry(commandFacts('Apply with "', `${view.invocation} --apply --yes`, '".', 3, caps), { depth: 0, symbol: 'step' }, caps),
585
685
  ], { leadingBlank: true });
586
- /** The invocation is rebuilt from the parsed arguments, so the printed command is the one that was understood. */
587
- function invocationOf(context, operation) {
686
+ /**
687
+ * The invocation is rebuilt from the parsed arguments, so the printed command is the one that was understood. A
688
+ * remedy's variant names another operation over its own ids, replaces the source (`--registry`, `--catalog`,
689
+ * `--offline`) with the one the remedy asks for, or keeps the source online without `--offline`.
690
+ */
691
+ function invocationOf(context, operation, variant = {}) {
588
692
  const { args } = context;
589
- const parts = [`ia ${operation}`, ...args.positionals.map(quote)];
590
- for (const name of ['to', 'requests', 'registry', 'catalog', 'plan-out']) {
591
- const value = args.value(name);
592
- if (value !== undefined)
593
- parts.push(`--${name}`, quote(value));
693
+ const parts = [`ia ${operation}`, ...(variant.ids ?? args.positionals).map(quote)];
694
+ const value = (name) => {
695
+ const given = args.value(name);
696
+ if (given !== undefined)
697
+ parts.push(`--${name}`, quote(given));
698
+ };
699
+ if (operation === 'update')
700
+ value('to');
701
+ value('requests');
702
+ if (variant.source === undefined) {
703
+ value('registry');
704
+ value('catalog');
594
705
  }
595
- for (const name of ['offline', 'allow-withdrawn'])
596
- if (args.flag(name))
597
- parts.push(`--${name}`);
598
- const root = args.value('root');
599
- if (root !== undefined)
600
- parts.push('--root', quote(root));
706
+ else
707
+ parts.push(...variant.source);
708
+ value('plan-out');
709
+ if (variant.source === undefined && variant.online !== true && args.flag('offline'))
710
+ parts.push('--offline');
711
+ if (args.flag('allow-withdrawn'))
712
+ parts.push('--allow-withdrawn');
713
+ value('root');
601
714
  return parts.join(' ');
602
715
  }
716
+ /** Design row 27: the commands this invocation's remedies name, spelled once from what the parser understood. */
717
+ function rerunsOf(context, operation) {
718
+ const { args, host } = context;
719
+ // `restore` has no preview: its rerun is the apply, confirmed, as every printed apply is.
720
+ const apply = operation === 'restore' ? ' --apply --yes' : '';
721
+ const to = args.value('to'), root = args.value('root');
722
+ return {
723
+ again: `${invocationOf(context, operation)}${apply}`,
724
+ online: `${invocationOf(context, operation, { online: true })}${apply}`,
725
+ local: `${invocationOf(context, operation, { source: ['--catalog', '<file>'] })}${apply}`,
726
+ chosen: args.value('registry') !== undefined ? 'flag' : host.env['IA_REGISTRY'] ? 'variable' : 'map',
727
+ another: `${invocationOf(context, operation, { source: ['--registry', '<url|dir>'] })}${apply}`,
728
+ install: invocationOf(context, 'install', {
729
+ ids: args.positionals.map((id) => (to === undefined ? id : `${id}@${to}`)),
730
+ }),
731
+ inspect: `ia inspect${root === undefined ? '' : ` --root ${quote(root)}`}`,
732
+ };
733
+ }
603
734
  /**
604
735
  * Registry spec §4: the one chooser a command builds, from the host rather than the process, so every verb that
605
736
  * reports or uses registry routing (`install`, `update`, `restore`, `doctor`) picks the same base for an id. A
@@ -631,6 +762,7 @@ export function runDistribute(operation) {
631
762
  if (args.flag('apply'))
632
763
  requireProjectionsClean(root, refresh, rooted);
633
764
  const planned = await collectPlan({
765
+ packageRoot: host.packageRoot,
634
766
  signal: host.signal,
635
767
  root,
636
768
  operation,
@@ -642,6 +774,7 @@ export function runDistribute(operation) {
642
774
  allowWithdrawn: args.flag('allow-withdrawn'),
643
775
  planOut: args.value('plan-out'),
644
776
  invocation: invocationOf(context, operation),
777
+ reruns: rerunsOf(context, operation),
645
778
  rooted,
646
779
  refresh,
647
780
  choose,