@inventarch/cli 1.2.0 → 3.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.
- package/README.md +20 -5
- package/SPEC.md +86 -11
- package/assets/base/08eaab3e1a6215d78283b82a94a0228367ac7bd78d0a746c56db79c8d7546c3a.ia.tgz +0 -0
- package/assets/base.json +3 -3
- package/assets/host/d7722e32fd0511df2a6dfdf2353e621fdff1cf559d5c8b7ac256c7eceac0452f.tgz +0 -0
- package/assets/host.json +4 -4
- package/assets/vocabulary.json +11 -3
- package/dist/adopt.d.ts +8 -0
- package/dist/adopt.d.ts.map +1 -0
- package/dist/adopt.js +60 -0
- package/dist/adopt.js.map +1 -0
- package/dist/author.d.ts +32 -0
- package/dist/author.d.ts.map +1 -0
- package/dist/author.js +226 -0
- package/dist/author.js.map +1 -0
- package/dist/briefing.d.ts +2 -0
- package/dist/briefing.d.ts.map +1 -1
- package/dist/briefing.js +15 -3
- package/dist/briefing.js.map +1 -1
- package/dist/bundled-base.d.ts +18 -0
- package/dist/bundled-base.d.ts.map +1 -0
- package/dist/bundled-base.js +44 -0
- package/dist/bundled-base.js.map +1 -0
- package/dist/capture.d.ts +41 -6
- package/dist/capture.d.ts.map +1 -1
- package/dist/capture.js +132 -43
- package/dist/capture.js.map +1 -1
- package/dist/commands.d.ts +30 -8
- package/dist/commands.d.ts.map +1 -1
- package/dist/commands.js +287 -35
- package/dist/commands.js.map +1 -1
- package/dist/compile.d.ts +3 -4
- package/dist/compile.d.ts.map +1 -1
- package/dist/compile.js +28 -72
- package/dist/compile.js.map +1 -1
- package/dist/consumer.d.ts +11 -2
- package/dist/consumer.d.ts.map +1 -1
- package/dist/consumer.js +103 -20
- package/dist/consumer.js.map +1 -1
- package/dist/distribute.d.ts +30 -8
- package/dist/distribute.d.ts.map +1 -1
- package/dist/distribute.js +112 -60
- package/dist/distribute.js.map +1 -1
- package/dist/doctor-authority.d.ts +3 -0
- package/dist/doctor-authority.d.ts.map +1 -0
- package/dist/doctor-authority.js +65 -0
- package/dist/doctor-authority.js.map +1 -0
- package/dist/doctor-mounts.d.ts +4 -0
- package/dist/doctor-mounts.d.ts.map +1 -0
- package/dist/doctor-mounts.js +32 -0
- package/dist/doctor-mounts.js.map +1 -0
- package/dist/doctor.d.ts.map +1 -1
- package/dist/doctor.js +327 -79
- package/dist/doctor.js.map +1 -1
- package/dist/format.d.ts.map +1 -1
- package/dist/format.js +2 -1
- package/dist/format.js.map +1 -1
- package/dist/host-projection.d.ts +131 -6
- package/dist/host-projection.d.ts.map +1 -1
- package/dist/host-projection.js +663 -42
- package/dist/host-projection.js.map +1 -1
- package/dist/host.d.ts +154 -32
- package/dist/host.d.ts.map +1 -1
- package/dist/host.js +393 -142
- package/dist/host.js.map +1 -1
- package/dist/init.d.ts +296 -38
- package/dist/init.d.ts.map +1 -1
- package/dist/init.js +1303 -203
- package/dist/init.js.map +1 -1
- package/dist/main.d.ts +1 -6
- package/dist/main.d.ts.map +1 -1
- package/dist/main.js +4 -7
- package/dist/main.js.map +1 -1
- package/dist/migration-journal.d.ts +35 -0
- package/dist/migration-journal.d.ts.map +1 -0
- package/dist/migration-journal.js +205 -0
- package/dist/migration-journal.js.map +1 -0
- package/dist/next.d.ts +21 -0
- package/dist/next.d.ts.map +1 -0
- package/dist/next.js +216 -0
- package/dist/next.js.map +1 -0
- package/dist/operation-help.d.ts.map +1 -1
- package/dist/operation-help.js +15 -4
- package/dist/operation-help.js.map +1 -1
- package/dist/pack.d.ts.map +1 -1
- package/dist/pack.js +24 -2
- package/dist/pack.js.map +1 -1
- package/dist/position.d.ts +22 -0
- package/dist/position.d.ts.map +1 -0
- package/dist/position.js +244 -0
- package/dist/position.js.map +1 -0
- package/dist/preview.d.ts +145 -0
- package/dist/preview.d.ts.map +1 -0
- package/dist/preview.js +962 -0
- package/dist/preview.js.map +1 -0
- package/dist/profile.d.ts +118 -0
- package/dist/profile.d.ts.map +1 -0
- package/dist/profile.js +362 -0
- package/dist/profile.js.map +1 -0
- package/dist/project.d.ts +45 -0
- package/dist/project.d.ts.map +1 -0
- package/dist/project.js +263 -0
- package/dist/project.js.map +1 -0
- package/dist/read.d.ts +12 -2
- package/dist/read.d.ts.map +1 -1
- package/dist/read.js +32 -18
- package/dist/read.js.map +1 -1
- package/dist/render.d.ts +24 -2
- package/dist/render.d.ts.map +1 -1
- package/dist/render.js +171 -4
- package/dist/render.js.map +1 -1
- package/dist/session.d.ts +39 -12
- package/dist/session.d.ts.map +1 -1
- package/dist/session.js +55 -11
- package/dist/session.js.map +1 -1
- package/dist/user-host.d.ts +3 -3
- package/dist/user-host.js +10 -10
- package/dist/user-host.js.map +1 -1
- package/dist/validate.d.ts +28 -16
- package/dist/validate.d.ts.map +1 -1
- package/dist/validate.js +245 -23
- package/dist/validate.js.map +1 -1
- package/package.json +6 -6
- package/assets/base/0305ca741b1dfec97ff35fbeb36d4a66a0c9c0614b730fe14fcdac0f1565e28a.ia.tgz +0 -0
- package/assets/host/c5fb2bfbba619cbd558ecc1e94dd2c16e37aa8599b4e423f1f59ed01f2074e03.tgz +0 -0
package/dist/host.js
CHANGED
|
@@ -1,36 +1,51 @@
|
|
|
1
1
|
/**
|
|
2
2
|
* `ia host`: docs/specs/host-registration/README.md §4.
|
|
3
3
|
*
|
|
4
|
-
* One verb owns the managed host set of §5.1: the MCP entry
|
|
5
|
-
*
|
|
6
|
-
*
|
|
7
|
-
*
|
|
8
|
-
*
|
|
9
|
-
*
|
|
10
|
-
*
|
|
4
|
+
* One verb owns the managed host set of §5.1: the MCP entry and the workspace projection, plus the context element
|
|
5
|
+
* §5.2's gate keeps unselected. It plans by default and never writes while planning — the payload's location is
|
|
6
|
+
* computed, not created. `--apply` materializes the embedded payload once per user (§3.3), re-plans every
|
|
7
|
+
* sub-transaction against the verified payload, then applies them in order — mcp, projection — and removal runs them
|
|
8
|
+
* in reverse (§8). No cross-file atomicity is claimed: a rerun converges, and a pending journal refuses naming its
|
|
9
|
+
* recovery. Nothing here reports that a server answered or a hook ran; `applied.observed` is always false (plan-0002
|
|
10
|
+
* M5 exit).
|
|
11
11
|
*
|
|
12
|
-
*
|
|
13
|
-
*
|
|
14
|
-
*
|
|
12
|
+
* Milestone position-packet task replace-renderers (plan amendments B9, B11 and B12): the projection is the position
|
|
13
|
+
* packet's consumer rendering, and `ia host` registers no steward guard. The projection element lists instead the
|
|
14
|
+
* retirement of a guard an earlier release registered, which `applyHostProjection` (host-projection.ts) performs before
|
|
15
|
+
* any projection file changes, the owned 1.x steward files it deletes and the foreign files it leaves. Task
|
|
16
|
+
* ia-project-verb: `ia project` (project.ts) plans and applies that element alone, through the same planner
|
|
17
|
+
* (`projectionElement`), re-plan (`replanProjection`) and writer, and its file rows (`projectionFileRows`).
|
|
18
|
+
*
|
|
19
|
+
* The plan asks the mechanisms themselves. `planHostFor` plans against the payload apply will materialize, described
|
|
20
|
+
* from the pin without reading it (`expectedHostCache`), so a conflict in the preview is the service's own refusal —
|
|
21
|
+
* its code and message unchanged (contract §4.1) — and is the refusal apply would raise.
|
|
22
|
+
*
|
|
23
|
+
* Milestone generation-binding (plan amendments C16 and C24, design item 9): the apply reads the join receipts before it
|
|
24
|
+
* writes anything, refusing ones it cannot read, and once every element is applied it records the host's join from the
|
|
25
|
+
* committed registration (`joinHost`): the installed-implementation catalog of the payload it names, at the workspace's
|
|
26
|
+
* authored revision. A removal drops it (`leaveHost`). The plan and the envelope do not change; `ia doctor` reports
|
|
27
|
+
* the join.
|
|
15
28
|
*/
|
|
16
29
|
import { createHash } from 'node:crypto';
|
|
17
30
|
import { existsSync, realpathSync, statSync } from 'node:fs';
|
|
18
|
-
import { resolve } from 'node:path';
|
|
31
|
+
import { dirname, isAbsolute, relative, resolve } from 'node:path';
|
|
19
32
|
import { lifecycleProfile } from '@inventarch/workspace-runtime/lifecycle-profile';
|
|
20
|
-
import {
|
|
21
|
-
import {
|
|
22
|
-
import {
|
|
23
|
-
import {
|
|
33
|
+
import { hostRow, WORKSPACE_HOSTS, workspaceRow } from '@inventarch/distribution/hosts';
|
|
34
|
+
import { recoverInstallation } from '@inventarch/distribution/install';
|
|
35
|
+
import { recoverGuardRegistration } from '@inventarch/distribution/guard-registration';
|
|
36
|
+
import { recoverLifecycleRegistration } from '@inventarch/distribution/lifecycle-registration';
|
|
37
|
+
import { applyHost, assertHostRegistrationIdle, expectedHostCache, HOST_REGISTRATION, planHost, planHostFor, recoverHost, } from '@inventarch/distribution/host';
|
|
24
38
|
import { assertHomeOutsideWorkspace, hostPayloadPath, materializeHostPayload, readHostPin, } from '@inventarch/distribution/host-home';
|
|
39
|
+
import { joinHost, JOINS, leaveHost, readJoins } from '@inventarch/distribution/implementations';
|
|
25
40
|
import { assertIaHomeUsable } from '@inventarch/distribution/ia-home';
|
|
26
41
|
import { readMaterializedPlugin } from '@inventarch/distribution/plugin-home';
|
|
27
|
-
import { applyProjection, planProjection } from '@inventarch/distribution/projection';
|
|
28
42
|
import { UsageError } from './args.js';
|
|
29
43
|
import { homeSrcRemedy, hostHome, located } from './home-remedy.js';
|
|
30
44
|
import { confirm, Interrupted, Refusal, refusalOf, requireRoot } from './consumer.js';
|
|
31
|
-
import {
|
|
45
|
+
import { sessionGate } from './profile.js';
|
|
46
|
+
import { applyHostProjection, notTaken, planFiles, planHookStep, planRetirement, renderProjectionFor, } from './host-projection.js';
|
|
32
47
|
import { codeOf } from './session.js';
|
|
33
|
-
import { atom, blockSymbolWidth, commandFacts, document, entry, fieldRows, headerLine, indentOf, quote, sectionLabel, truncateDigest, words, } from './render.js';
|
|
48
|
+
import { atom, blockSymbolWidth, commandFacts, document, entry, fieldRows, headerLine, indentOf, quote, safeRootAdvice, sectionLabel, truncateDigest, words, } from './render.js';
|
|
34
49
|
import { runUserHost } from './user-host.js';
|
|
35
50
|
/** The installation, not the workspace, is at fault; `ia doctor` names the channel a reinstall goes through. */
|
|
36
51
|
const DAMAGED = 'The ia installation is damaged; run "ia doctor" for its install channel and reinstall @inventarch/cli through it, so assets/host travels with it.';
|
|
@@ -39,22 +54,32 @@ export const USER_PLUGIN_COMMAND = 'ia host claude --user --apply';
|
|
|
39
54
|
export const USER_PLUGIN_MISSING = `The user-level plugin is not installed; run "${USER_PLUGIN_COMMAND}" to add it.`;
|
|
40
55
|
/** §5.3's sentence, verbatim, per host. Every element — the projection included — is machine-local. */
|
|
41
56
|
export const MACHINE_LOCAL = {
|
|
42
|
-
claude: 'These files are machine-local: .mcp.json, .claude/settings.local.json, .claude/rules/ia-workspace.md, .claude/skills/ia-authoring/, the
|
|
43
|
-
codex: 'These files are machine-local: .codex/config.toml, AGENTS.md, .agents/skills/ia-authoring/ and .ia/distributions/. Do not commit them.',
|
|
57
|
+
claude: 'These files are machine-local: .mcp.json, .claude/settings.local.json, .claude/rules/ia-workspace.md, .claude/skills/ia-authoring/, the agents and skills generated from authored records under .claude/agents/ and .claude/skills/, and .ia/distributions/. Do not commit them.',
|
|
58
|
+
codex: 'These files are machine-local: .codex/config.toml, AGENTS.md, .agents/skills/ia-authoring/, the skills generated from authored records under .agents/skills/, and .ia/distributions/. Do not commit them.',
|
|
44
59
|
};
|
|
45
60
|
/** §5.4: the MCP element's one fixed addition, from §2.3's host facts. */
|
|
46
61
|
export const MCP_APPROVAL = 'Claude Code asks for approval before starting a project MCP server.';
|
|
47
|
-
/**
|
|
48
|
-
|
|
62
|
+
/**
|
|
63
|
+
* Operator decision 2026-10-08 (plan amendment B11), said where the guard used to be registered, as operator decision
|
|
64
|
+
* 2026-09-23 ("narrow + disclose") said what it refused: the guard is retired, so nothing it refused is refused now.
|
|
65
|
+
*/
|
|
66
|
+
export const GUARD_SCOPE = 'ia host registers one guard group per authored @hook, which refuses an edit its paths and tools select unless the acting agent holds a governing @mandate granting Synthesis there; it registers no per-system steward guard, and applying the projection retires one an earlier release registered.';
|
|
49
67
|
/** §5.1's files, exported once so `ia doctor` names the same ones. */
|
|
50
68
|
export const MCP_PATH = { claude: '.mcp.json', codex: '.codex/config.toml' };
|
|
51
69
|
export const SETTINGS = '.claude/settings.local.json';
|
|
52
70
|
export const HOSTS_AREA = '.ia/distributions/hosts';
|
|
53
|
-
/**
|
|
71
|
+
/**
|
|
72
|
+
* §5.1's state files. Their presence says whether this workspace owns an element; their content is the mechanisms'.
|
|
73
|
+
* `hooks` is a steward-guard registration an earlier release made, which the projection apply retires (B11), and
|
|
74
|
+
* `receipt` the receipt it writes beside the projection state (B12).
|
|
75
|
+
*/
|
|
54
76
|
export const STATE = {
|
|
55
77
|
mcp: (host) => `${HOSTS_AREA}/${host}-${HOST_REGISTRATION}.json`,
|
|
56
78
|
hooks: `${HOSTS_AREA}/claude-guard-${HOST_REGISTRATION}.json`,
|
|
79
|
+
/** The ownership state of the groups registered for authored `@hook` records (distribution `hookStatePath`). */
|
|
80
|
+
hookGroups: `${HOSTS_AREA}/claude-hooks-${HOST_REGISTRATION}.json`,
|
|
57
81
|
projection: (host) => `${HOSTS_AREA}/${host}-projection.json`,
|
|
82
|
+
receipt: (host) => `${HOSTS_AREA}/${host}-receipt.json`,
|
|
58
83
|
};
|
|
59
84
|
/**
|
|
60
85
|
* What one host's MCP element owns, named so a user can find and delete exactly it. Codex's is a marked block
|
|
@@ -67,6 +92,8 @@ const OWNED_MCP = {
|
|
|
67
92
|
`through "# END IA PROJECTION host-${HOST_REGISTRATION}", markers included`,
|
|
68
93
|
};
|
|
69
94
|
const OWNED_GUARD = `the IA guard group in ${SETTINGS}`;
|
|
95
|
+
/** The groups registered for authored `@hook` records, each running the guard for its hook. */
|
|
96
|
+
const OWNED_HOOKS = `every IA hook group in ${SETTINGS} (each runs the guard for one authored @hook)`;
|
|
70
97
|
/**
|
|
71
98
|
* The repair for an ownership state file that cannot be read, or null when `path` is not one. The mechanisms refuse
|
|
72
99
|
* every plan until the file goes, and deleting it alone would leave what it owned looking unmanaged, so the repair
|
|
@@ -77,7 +104,10 @@ export function stateRepair(host, path, rerun) {
|
|
|
77
104
|
return `Delete ${path} and ${OWNED_MCP[host]}, then run "${rerun}".`;
|
|
78
105
|
if (host === 'claude' && path === STATE.hooks)
|
|
79
106
|
return `Delete ${path} and ${OWNED_GUARD}, then run "${rerun}".`;
|
|
80
|
-
|
|
107
|
+
// Review finding H-N3: the hook ownership state names the groups it owns, so both go before the rerun.
|
|
108
|
+
if (host === 'claude' && path === STATE.hookGroups)
|
|
109
|
+
return `Delete ${path} and ${OWNED_HOOKS}, then run "${rerun}".`;
|
|
110
|
+
if (path === STATE.projection(host) || path === STATE.receipt(host))
|
|
81
111
|
return `Delete ${path}, then run "${rerun}".`;
|
|
82
112
|
return null;
|
|
83
113
|
}
|
|
@@ -103,8 +133,35 @@ export const HOST_LOCK = `${HOSTS_AREA}/lock.json`;
|
|
|
103
133
|
* names `ia host` instead of such a remedy.
|
|
104
134
|
*/
|
|
105
135
|
export const THEN_RERUN = ', then rerun.';
|
|
106
|
-
/**
|
|
107
|
-
export const recoverCommand = (command, root) => `ia
|
|
136
|
+
/** An installed CLI recovery, delegating the named distribution mechanism with an explicit root. */
|
|
137
|
+
export const recoverCommand = (command, root) => `ia recover ${command === 'recover' ? 'installation' : command.replace(/^recover-/, '')} --root ${quote(root)}`;
|
|
138
|
+
/** Recovery needs an existing explicit root, including one whose initialization was interrupted. */
|
|
139
|
+
export function runRecovery(context) {
|
|
140
|
+
const mechanisms = {
|
|
141
|
+
installation: recoverInstallation,
|
|
142
|
+
host: recoverHost,
|
|
143
|
+
guard: recoverGuardRegistration,
|
|
144
|
+
lifecycle: recoverLifecycleRegistration,
|
|
145
|
+
};
|
|
146
|
+
const selected = context.args.positionals[0] ?? 'installation';
|
|
147
|
+
if (!Object.hasOwn(mechanisms, selected))
|
|
148
|
+
throw new UsageError('Recovery must be installation, host, guard or lifecycle');
|
|
149
|
+
const root = requireRoot(context);
|
|
150
|
+
try {
|
|
151
|
+
const result = mechanisms[selected](root);
|
|
152
|
+
return {
|
|
153
|
+
exitCode: 0,
|
|
154
|
+
stdout: context.json
|
|
155
|
+
? JSON.stringify({ version: 1, ok: true, recovery: selected, root, result }) + '\n'
|
|
156
|
+
: `${selected} recovery: ${result.status}.\n`,
|
|
157
|
+
stderr: '',
|
|
158
|
+
};
|
|
159
|
+
}
|
|
160
|
+
catch (error) {
|
|
161
|
+
const refusal = refusalOf(error);
|
|
162
|
+
throw new Refusal(refusal.code, refusal.message, 3, refusedPath(error) === null ? refusal.where : { path: refusedPath(error) }, `Preserve the recovery state, resolve the reported conflict or wait for its running owner to finish, then run "ia recover ${selected} --root ${quote(root)}".`);
|
|
163
|
+
}
|
|
164
|
+
}
|
|
108
165
|
/**
|
|
109
166
|
* §8 "or refuses naming a recovery": a held host lock is another run or a killed one, and nothing here can tell
|
|
110
167
|
* which, so the next action names the recovery that decides it — `recoverHost` takes the lock in recovery mode,
|
|
@@ -138,34 +195,110 @@ export function pinnedRelease(packageRoot) {
|
|
|
138
195
|
return { release: null, code: codeOf(error, 'IA-DIST-ARTIFACT-UNAVAILABLE') };
|
|
139
196
|
}
|
|
140
197
|
}
|
|
141
|
-
/**
|
|
142
|
-
|
|
198
|
+
/**
|
|
199
|
+
* §4: the target must be initialized and admit; anything else names ia init or ia validate. `named` is the root as the
|
|
200
|
+
* init it names spells it: `ia host` names the resolved root, and `ia project` the root as its invocation typed it.
|
|
201
|
+
*/
|
|
202
|
+
export function requireInitialized(root, named = root) {
|
|
143
203
|
if (!existsSync(resolve(root, '.ia/release.json')))
|
|
144
|
-
throw new Refusal('IA-CLI-CONFLICT', 'The target is not an initialized workspace: .ia/release.json is absent', 3, { path: root }, `Run "ia init ${quote(
|
|
204
|
+
throw new Refusal('IA-CLI-CONFLICT', 'The target is not an initialized workspace: .ia/release.json is absent', 3, { path: root }, `Run "ia init ${quote(named)}" first.`);
|
|
145
205
|
}
|
|
146
206
|
/** The journal a failed transaction left behind, if any, with the command that recovers it. */
|
|
147
|
-
const pendingJournal = (root) => JOURNALS.find(([path]) => existsSync(resolve(root, path)));
|
|
207
|
+
export const pendingJournal = (root) => JOURNALS.find(([path]) => existsSync(resolve(root, path)));
|
|
148
208
|
/** Design row 27: the recovery is the one command named; the refused command is simply run again after it. */
|
|
149
|
-
const recoverNext = (root, command) => `Run "${recoverCommand(command, root)}"${THEN_RERUN}`;
|
|
209
|
+
export const recoverNext = (root, command) => `Run "${recoverCommand(command, root)}"${THEN_RERUN}`;
|
|
150
210
|
/**
|
|
151
|
-
* A next action of this verb made runnable from any cwd: every quoted `ia host <host>`
|
|
152
|
-
* `ia validate` a workspace that does not admit names (host-projection.ts), gains `--root <root>`.
|
|
153
|
-
* uses it, because its `<directory>` may not be the cwd a rerun discovers from
|
|
154
|
-
* `"ia host <host>` or `"ia validate
|
|
211
|
+
* A next action of this verb made runnable from any cwd: every quoted `ia host <host>` or `ia project <host>` command
|
|
212
|
+
* it names, and the `ia validate` a workspace that does not admit names (host-projection.ts), gains `--root <root>`.
|
|
213
|
+
* `ia init --host` uses it, because its `<directory>` may not be the cwd a rerun discovers from, and so do `ia project`
|
|
214
|
+
* and `ia doctor`. Every such command opens with `"ia host <host>`, `"ia project <host>` or `"ia validate`, and one
|
|
215
|
+
* that names `--root` itself is left as it is, so the rewrite reaches each one and nothing else.
|
|
155
216
|
*/
|
|
156
|
-
export const rootedNext = (next, host, root) => next.replace(new RegExp(`"ia (?:host ${host}|validate)(?!
|
|
217
|
+
export const rootedNext = (next, host, root) => next.replace(new RegExp(`"ia (?:host ${host}|project ${host}|validate)(?![^"]*\\s--root\\b)`, 'g'), (command) => `${command} --root ${quote(root)}`);
|
|
157
218
|
/** A next action as printed: with `--root` given, each `ia host <host>` command in it carries the root. */
|
|
158
219
|
export const hostNext = (text, host, root, rooted) => rooted ? rootedNext(text, host, root) : text;
|
|
159
220
|
/** The file a mechanism located its refusal at (`locate` in @inventarch/distribution's files.ts), or null. */
|
|
160
|
-
export const refusedPath = (error) => error
|
|
221
|
+
export const refusedPath = (error) => /^IA-/.test(codeOf(error, '')) &&
|
|
222
|
+
error !== null &&
|
|
223
|
+
typeof error === 'object' &&
|
|
224
|
+
'path' in error &&
|
|
225
|
+
typeof error.path === 'string'
|
|
226
|
+
? error.path
|
|
227
|
+
: null;
|
|
228
|
+
/**
|
|
229
|
+
* §6.3: the repair for a projection refusal with `code` located at `path`. The ownership state has its own repair; a
|
|
230
|
+
* guard group the retirement (B11) refuses as changed is deleted by hand, after which the retirement removes the
|
|
231
|
+
* ownership state alone, and settings it cannot read are fixed; any other file is never replaced or adopted, so it is
|
|
232
|
+
* moved or deleted first. `ia host`, `ia doctor` and the install refresh all name it this way.
|
|
233
|
+
*/
|
|
234
|
+
export const projectionRepair = (host, path, rerun, code) => code === 'IA-CLI-FAILED'
|
|
235
|
+
? `Make ${path} writable and release any file lock, then run "${rerun}".`
|
|
236
|
+
: (stateRepair(host, path, rerun) ??
|
|
237
|
+
(![SETTINGS, '.claude/settings.json'].includes(path)
|
|
238
|
+
? `Move or delete ${path}, then run "${rerun}".`
|
|
239
|
+
: code === undefined || code === 'IA-DIST-LOCAL-MODIFICATION'
|
|
240
|
+
? `Delete only the IA guard group in ${path}, then run "${rerun}".`
|
|
241
|
+
: `Fix ${path}, then run "${rerun}".`));
|
|
242
|
+
/** The populated skill folder a projection refusal names (distribution's `skillFolder`, review finding A-F2), if any. */
|
|
243
|
+
export const skillFolderOf = (error) => error !== null && typeof error === 'object' && 'skillFolder' in error && typeof error.skillFolder === 'string'
|
|
244
|
+
? error.skillFolder
|
|
245
|
+
: undefined;
|
|
246
|
+
/** The repair for a generated skill refused at a folder that holds the user's files: those files go, or the name changes. */
|
|
247
|
+
export const folderRepair = (folder, rerun) => `Move the files out of ${folder}, or rename the @playbook that renders it, then run "${rerun}".`;
|
|
248
|
+
/** The hook refusal an error carries (`hookRefusal`), if any. */
|
|
249
|
+
export const hookRefusalOf = (error) => error !== null && typeof error === 'object' && 'hookRefusal' in error
|
|
250
|
+
? error.hookRefusal
|
|
251
|
+
: undefined;
|
|
252
|
+
/**
|
|
253
|
+
* The recovery for a hook refusal, as `ia doctor` names it: a group taken away by hand is one apply never puts back on
|
|
254
|
+
* its own, so the removal drops the registration (after a changed or duplicated group, which the removal refuses too,
|
|
255
|
+
* is deleted) and `ia host` registers the workspace's hooks again; a payload a change needs is materialized by `ia host`.
|
|
256
|
+
*/
|
|
257
|
+
export const hookRepair = (refusal) => 'payload' in refusal
|
|
258
|
+
? `Run "ia host claude --apply" to materialize this release's payload and register the workspace's hooks against it.`
|
|
259
|
+
: refusal.drift === 'foreign'
|
|
260
|
+
? `Delete only the unowned IA hook group for ${refusal.hook} in ${refusal.path}, preserving other groups and settings, then run "ia host claude --remove --apply" to finish removal. Protection may remain active until that group is removed.`
|
|
261
|
+
: refusal.drift === 'modified'
|
|
262
|
+
? `Delete every IA hook group for ${refusal.hook} in ${SETTINGS}, then run "ia host claude --remove --apply" and register again with ia host.`
|
|
263
|
+
: `Run "ia host claude --remove --apply", which drops the registration of the hook group deleted by hand, then register again with ia host.`;
|
|
264
|
+
/** A journal owns recovery; raw operating-system errors never authorize deleting settings or ownership. */
|
|
265
|
+
export function projectionFailure(error, root, host, rerun) {
|
|
266
|
+
const refusal = refusalOf(error), journal = pendingJournal(root);
|
|
267
|
+
if (journal !== undefined)
|
|
268
|
+
return new Refusal(refusal.code, refusal.message, 3, { path: journal[0] }, recoverNext(root, journal[1]));
|
|
269
|
+
const busy = lockRefusal(error, root);
|
|
270
|
+
if (busy !== null)
|
|
271
|
+
return busy;
|
|
272
|
+
const located = refusedPath(error);
|
|
273
|
+
if (located !== null) {
|
|
274
|
+
const path = isAbsolute(located) ? relative(root, located).replaceAll('\\', '/') : located;
|
|
275
|
+
return new Refusal(refusal.code, refusal.message, 3, { path }, rootedNext(skillFolderOf(error) !== undefined
|
|
276
|
+
? folderRepair(skillFolderOf(error), rerun)
|
|
277
|
+
: hookRefusalOf(error) === undefined
|
|
278
|
+
? projectionRepair(host, path, rerun, refusal.code)
|
|
279
|
+
: hookRepair(hookRefusalOf(error)), host, root));
|
|
280
|
+
}
|
|
281
|
+
const system = error;
|
|
282
|
+
if (system && ['EACCES', 'EPERM', 'EBUSY', 'EROFS', 'EISDIR', 'ENOTDIR'].includes(system.code ?? '')) {
|
|
283
|
+
const path = typeof system.path === 'string' ? (system.path.endsWith('.tmp') ? dirname(system.path) : system.path) : root;
|
|
284
|
+
return new Refusal(refusal.code, refusal.message, 3, { path }, rootedNext(`Make ${path} writable and release any file lock, then run "${rerun}".`, host, root));
|
|
285
|
+
}
|
|
286
|
+
return new Refusal(refusal.code, refusal.message, 3, refusal.where, rootedNext(error instanceof Refusal && refusal.next !== null ? refusal.next : `Run "${rerun}" to finish.`, host, root));
|
|
287
|
+
}
|
|
288
|
+
/**
|
|
289
|
+
* Host registration spec §4: the hosts whose projection this workspace owns, by their projection state's presence, as
|
|
290
|
+
* `ia host`, `ia doctor` and the install refresh decide it, a projection `ia project` wrote without a registration
|
|
291
|
+
* included.
|
|
292
|
+
*/
|
|
293
|
+
export const projectedHosts = (root) => WORKSPACE_HOSTS.filter((host) => existsSync(resolve(root, STATE.projection(host))));
|
|
161
294
|
/**
|
|
162
|
-
*
|
|
163
|
-
*
|
|
164
|
-
*
|
|
295
|
+
* The apply that repairs `host`'s projection, which `ia doctor` and the install refresh both name (task
|
|
296
|
+
* ia-project-verb): `ia host <host> --apply` for a registered host, and `ia project <host> --apply` for a projection
|
|
297
|
+
* `ia project` wrote without a registration, which `ia host` would also register an MCP server for.
|
|
165
298
|
*/
|
|
166
|
-
export const
|
|
167
|
-
/** §8: a pending journal refuses the whole verb and names the recovery that clears it. */
|
|
168
|
-
function requireIdle(root, supplied) {
|
|
299
|
+
export const projectionRerun = (root, host) => existsSync(resolve(root, STATE.mcp(host))) ? `ia host ${host} --apply` : `ia project ${host} --apply`;
|
|
300
|
+
/** §8: a pending journal refuses the whole verb and names the recovery that clears it. `ia project` shares it. */
|
|
301
|
+
export function requireIdle(root, supplied) {
|
|
169
302
|
try {
|
|
170
303
|
assertHostRegistrationIdle(root);
|
|
171
304
|
}
|
|
@@ -178,7 +311,17 @@ function requireIdle(root, supplied) {
|
|
|
178
311
|
/** A mechanism's refusal as an element conflict: the service's code and message, located at its file. */
|
|
179
312
|
function conflictOf(error, path) {
|
|
180
313
|
const refusal = refusalOf(error);
|
|
181
|
-
|
|
314
|
+
const raw = error;
|
|
315
|
+
const at = refusedPath(error) ??
|
|
316
|
+
(typeof raw?.path === 'string' ? (raw.path.endsWith('.tmp') ? dirname(raw.path) : raw.path) : path);
|
|
317
|
+
const hook = hookRefusalOf(error), folder = skillFolderOf(error);
|
|
318
|
+
return {
|
|
319
|
+
code: refusal.code,
|
|
320
|
+
path: at,
|
|
321
|
+
reason: refusal.message,
|
|
322
|
+
...(hook === undefined ? {} : { hook }),
|
|
323
|
+
...(folder === undefined ? {} : { folder }),
|
|
324
|
+
};
|
|
182
325
|
}
|
|
183
326
|
const pin = (text) => text === null ? null : createHash('sha256').update(text).digest('hex');
|
|
184
327
|
/** A registration plan's action, from the bytes it would write against the bytes it read. */
|
|
@@ -190,20 +333,20 @@ const actionOf = (plan) => plan.after.state === null
|
|
|
190
333
|
? 'unchanged'
|
|
191
334
|
: 'update';
|
|
192
335
|
/** One registration element, planned by its mechanism; `none` when a removal finds nothing owned. */
|
|
193
|
-
function registrationElement(
|
|
336
|
+
function registrationElement(path, owned, remove, plan) {
|
|
194
337
|
if (remove && !owned)
|
|
195
|
-
return { id, action: 'none', paths: [path], capability: 'absent', conflict: null };
|
|
338
|
+
return { id: 'mcp', action: 'none', paths: [path], capability: 'absent', conflict: null };
|
|
196
339
|
try {
|
|
197
|
-
return { id, action: actionOf(plan()), paths: [path], capability: 'registered', conflict: null };
|
|
340
|
+
return { id: 'mcp', action: actionOf(plan()), paths: [path], capability: 'registered', conflict: null };
|
|
198
341
|
}
|
|
199
342
|
catch (error) {
|
|
200
|
-
return { id, action: 'refused', paths: [path], capability: 'refused', conflict: conflictOf(error, path) };
|
|
343
|
+
return { id: 'mcp', action: 'refused', paths: [path], capability: 'refused', conflict: conflictOf(error, path) };
|
|
201
344
|
}
|
|
202
345
|
}
|
|
203
346
|
/**
|
|
204
347
|
* §5.2: the context element. Claude reports it `not selected` until the gate lifts; Codex reports it `unsupported by
|
|
205
|
-
* host`, because it is delivered through lifecycle hooks and Codex hooks are unavailable
|
|
206
|
-
*
|
|
348
|
+
* host`, because it is delivered through lifecycle hooks and Codex hooks are unavailable, so both hosts carry the
|
|
349
|
+
* same three rows.
|
|
207
350
|
*/
|
|
208
351
|
const contextElement = (host) => ({
|
|
209
352
|
id: 'context',
|
|
@@ -212,18 +355,41 @@ const contextElement = (host) => ({
|
|
|
212
355
|
capability: host === 'claude' ? 'not selected' : 'unsupported by host',
|
|
213
356
|
conflict: null,
|
|
214
357
|
});
|
|
215
|
-
/**
|
|
216
|
-
|
|
358
|
+
/**
|
|
359
|
+
* §5.1 `projection`, planned by the real planners: B11's retirement of an owned guard registration, then the file plan
|
|
360
|
+
* (B9). Both read only the workspace, so the plan is exactly apply's. A retirement is a change, and so is a missing
|
|
361
|
+
* receipt, which every apply writes (B12), so a projection whose files are unchanged is then an update; a removal that
|
|
362
|
+
* finds only a guard registration or a receipt removes them. `ia project` plans with it, and both verbs' applies
|
|
363
|
+
* re-plan with it (`replanProjection`), so no two of them can plan the projection differently.
|
|
364
|
+
*/
|
|
365
|
+
export function projectionElement(root, host, rendered, cache = null) {
|
|
366
|
+
const refused = (conflict) => ({
|
|
367
|
+
id: 'projection',
|
|
368
|
+
action: 'refused',
|
|
369
|
+
paths: [],
|
|
370
|
+
capability: 'refused',
|
|
371
|
+
conflict,
|
|
372
|
+
});
|
|
373
|
+
let guard, hooks, unregistered;
|
|
374
|
+
try {
|
|
375
|
+
guard = planRetirement(root, host) === null ? 'none' : 'retire';
|
|
376
|
+
const step = planHookStep(root, host, rendered, cache);
|
|
377
|
+
hooks = step.plan?.hooks ?? [];
|
|
378
|
+
unregistered = step.unregistered;
|
|
379
|
+
}
|
|
380
|
+
catch (error) {
|
|
381
|
+
return refused(conflictOf(error, SETTINGS));
|
|
382
|
+
}
|
|
217
383
|
try {
|
|
218
|
-
const files =
|
|
219
|
-
const touched = files.filter((file) => file.action !== '
|
|
220
|
-
const action =
|
|
221
|
-
? touched.some((file) => file.action === 'remove')
|
|
384
|
+
const files = planFiles(root, host, rendered).actions;
|
|
385
|
+
const touched = files.filter((file) => file.action !== 'foreign'), changes = guard === 'retire' || hooks.some((hook) => hook.action !== 'unchanged'), receipt = existsSync(resolve(root, STATE.receipt(host)));
|
|
386
|
+
const action = rendered === null
|
|
387
|
+
? touched.some((file) => file.action === 'remove') || changes || receipt
|
|
222
388
|
? 'remove'
|
|
223
389
|
: 'none'
|
|
224
|
-
: touched.every((file) => file.action === 'unchanged')
|
|
390
|
+
: touched.every((file) => file.action === 'unchanged') && !changes && receipt
|
|
225
391
|
? 'unchanged'
|
|
226
|
-
: touched.every((file) => file.action === 'create')
|
|
392
|
+
: touched.every((file) => file.action === 'create') && !changes
|
|
227
393
|
? 'create'
|
|
228
394
|
: 'update';
|
|
229
395
|
return {
|
|
@@ -233,16 +399,13 @@ function projectionElement(root, host, artifacts) {
|
|
|
233
399
|
capability: action === 'none' ? 'absent' : 'registered',
|
|
234
400
|
conflict: null,
|
|
235
401
|
files,
|
|
402
|
+
guard,
|
|
403
|
+
...(host === 'claude' ? { hooks } : {}),
|
|
404
|
+
unsupported: notTaken(rendered?.receipt.unsupported ?? [], unregistered),
|
|
236
405
|
};
|
|
237
406
|
}
|
|
238
407
|
catch (error) {
|
|
239
|
-
return
|
|
240
|
-
id: 'projection',
|
|
241
|
-
action: 'refused',
|
|
242
|
-
paths: [],
|
|
243
|
-
capability: 'refused',
|
|
244
|
-
conflict: conflictOf(error, STATE.projection(host)),
|
|
245
|
-
};
|
|
408
|
+
return refused(conflictOf(error, STATE.projection(host)));
|
|
246
409
|
}
|
|
247
410
|
}
|
|
248
411
|
/** The invocation is rebuilt from the parsed arguments, so the printed command is the one that was understood. */
|
|
@@ -289,42 +452,43 @@ export function collectHost(context) {
|
|
|
289
452
|
located(null, homeSrcRemedy(home, plan), () => assertIaHomeUsable(home));
|
|
290
453
|
const { pin: bundled } = bundledPin(host.packageRoot);
|
|
291
454
|
requireIdle(root, supplied);
|
|
292
|
-
// §4: zero error findings. A removal renders nothing
|
|
293
|
-
|
|
294
|
-
|
|
295
|
-
|
|
296
|
-
|
|
297
|
-
|
|
455
|
+
// §4: zero error findings before anything is rendered or registered. A removal renders nothing and reads no record, so
|
|
456
|
+
// it needs neither an admitting workspace nor records that open (review findings H-R2 and H-R8): it is what restores
|
|
457
|
+
// editing when a broken record or an unreadable workspace leaves a hook group refusing the repair.
|
|
458
|
+
// Review C2-R7: a workspace apply writes the projection `ia project --apply` writes, so it is the effect mode (Execution)
|
|
459
|
+
// under the participant's mandate profile, judged on the rendering session before the confirmation; its plan writes
|
|
460
|
+
// nothing, `--remove` restores editing, and `--user` reads no workspace, so none of them is gated.
|
|
461
|
+
const rendered = remove
|
|
462
|
+
? null
|
|
463
|
+
: renderProjectionFor(root, name, args.flag('apply') ? sessionGate(context, 'effect') : undefined);
|
|
298
464
|
// A host home reached through a symbolic link or junction is refused by the mechanism (IA-DIST-PATH-UNSAFE), because
|
|
299
465
|
// the payload it verifies must be the one the registration names; the remedy is a home with no link in its path.
|
|
300
466
|
const expected = located(null, `Set IA_HOME to a directory path with no links, or unset it; then run "${plan}".`, () => expectedHostCache(hostPayloadPath(home, bundled.release), bundled.release));
|
|
301
467
|
const owned = new Set();
|
|
302
468
|
if (existsSync(resolve(root, STATE.mcp(name))))
|
|
303
469
|
owned.add('mcp');
|
|
304
|
-
|
|
305
|
-
owned.add('hooks');
|
|
306
|
-
const mcp = registrationElement('mcp', MCP_PATH[name], owned.has('mcp'), remove, () => remove ? planHostFor(root, name, null, HOST_REGISTRATION) : planHostFor(root, name, expected));
|
|
307
|
-
const hooks = name === 'codex'
|
|
308
|
-
? { id: 'hooks', action: 'none', paths: [], capability: 'unsupported by host', conflict: null }
|
|
309
|
-
: registrationElement('hooks', SETTINGS, owned.has('hooks'), remove, () => remove ? planGuardRegistration(root, { remove: HOST_REGISTRATION }) : planGuardFor(root, expected));
|
|
470
|
+
const mcp = registrationElement(MCP_PATH[name], owned.has('mcp'), remove, () => remove ? planHostFor(root, name, null, HOST_REGISTRATION) : planHostFor(root, name, expected));
|
|
310
471
|
return {
|
|
311
472
|
root: supplied,
|
|
312
473
|
host: name,
|
|
313
474
|
remove,
|
|
314
475
|
release: bundled.release,
|
|
315
476
|
home,
|
|
316
|
-
elements: [mcp,
|
|
477
|
+
elements: [mcp, contextElement(name), projectionElement(root, name, rendered, remove ? null : { expected })],
|
|
317
478
|
undo: `ia host ${name} --remove --apply`,
|
|
318
479
|
invocation: invocationOf(context, name, remove),
|
|
319
480
|
owned,
|
|
320
481
|
rooted: context.args.value('root') !== undefined,
|
|
321
482
|
userPlugin: row.user === 'plugin' ? { installed: readMaterializedPlugin(home) !== null, command: USER_PLUGIN_COMMAND } : null,
|
|
483
|
+
rendered,
|
|
322
484
|
};
|
|
323
485
|
}
|
|
486
|
+
/** What an apply that retired the steward guard (B11) says it did. */
|
|
487
|
+
export const GUARD_RETIRED = 'Retired the steward guard an earlier release registered: its group in .claude/settings.local.json and its ownership state are removed.';
|
|
324
488
|
/** A next action of this verb as printed: with `--root` given, each `ia host` command in it carries the root. */
|
|
325
489
|
const say = (view, text) => hostNext(text, view.host, view.root, view.rooted);
|
|
326
490
|
/** The next action a conflict renders, and the one its refusal carries, rooted when `--root` was given. */
|
|
327
|
-
const nextFor = (view, id, conflict) => say(view, conflictNext(view, id, conflict));
|
|
491
|
+
const nextFor = (view, id, conflict) => safeRootAdvice(say(view, conflictNext(view, id, conflict)), [view.root]);
|
|
328
492
|
/** The unrooted next action for a conflict. §5.3 fixes the unowned MCP entry's wording. */
|
|
329
493
|
function conflictNext(view, id, conflict) {
|
|
330
494
|
const rerun = `ia host ${view.host}${view.remove ? ' --remove' : ''} --apply`;
|
|
@@ -332,8 +496,6 @@ function conflictNext(view, id, conflict) {
|
|
|
332
496
|
const unreadable = stateRepair(view.host, conflict.path, rerun);
|
|
333
497
|
if (unreadable !== null)
|
|
334
498
|
return unreadable;
|
|
335
|
-
if (conflict.code === 'IA-DIST-LOCAL-MODIFICATION' && id === 'hooks' && view.owned.has('hooks'))
|
|
336
|
-
return modifiedRepair(view.host, ['hooks']);
|
|
337
499
|
if (conflict.code === 'IA-DIST-LOCAL-MODIFICATION' && id === 'mcp') {
|
|
338
500
|
// Owned: removal tolerates a deleted entry, so deleting it and re-registering converges. Unowned: §5.3's wording,
|
|
339
501
|
// made exact for Codex, where the collision can be any ia-workspace table or a file that no longer parses.
|
|
@@ -343,10 +505,12 @@ function conflictNext(view, id, conflict) {
|
|
|
343
505
|
? 'Remove any ia-workspace server outside the IA block from .codex/config.toml and make sure the file parses as TOML, then run "ia host codex --apply".'
|
|
344
506
|
: `Remove that entry, then run "ia host ${view.host} --apply".`;
|
|
345
507
|
}
|
|
346
|
-
if (conflict.code === 'IA-DIST-HOST-UNSUPPORTED' && id === 'hooks')
|
|
347
|
-
return `Remove disableAllHooks from the Claude settings, then run "${rerun}".`;
|
|
348
508
|
if (id === 'projection')
|
|
349
|
-
return
|
|
509
|
+
return conflict.folder !== undefined
|
|
510
|
+
? folderRepair(conflict.folder, rerun)
|
|
511
|
+
: conflict.hook === undefined
|
|
512
|
+
? projectionRepair(view.host, conflict.path, rerun, conflict.code)
|
|
513
|
+
: hookRepair(conflict.hook);
|
|
350
514
|
return `Fix ${conflict.path}, then run "${rerun}".`;
|
|
351
515
|
}
|
|
352
516
|
const refusalFor = (view, id, conflict) => new Refusal(conflict.code, conflict.reason, 3, { path: conflict.path }, nextFor(view, id, conflict));
|
|
@@ -359,6 +523,17 @@ function replan(view, id, path, run) {
|
|
|
359
523
|
throw refusalFor(view, id, conflictOf(error, path));
|
|
360
524
|
}
|
|
361
525
|
}
|
|
526
|
+
/**
|
|
527
|
+
* Apply's re-plan of the projection, shared by `ia host --apply` and `ia project --apply`: the projection element
|
|
528
|
+
* planned against the rendering the apply writes, so a conflict either of its planners finds (the guard retirement or
|
|
529
|
+
* the file plan) is raised, worded by the verb's `refuse`, before anything is written. `applyHostProjection` plans
|
|
530
|
+
* both again before its first write.
|
|
531
|
+
*/
|
|
532
|
+
export function replanProjection(root, host, rendered, refuse, cache = null) {
|
|
533
|
+
const { conflict } = projectionElement(root, host, rendered, cache);
|
|
534
|
+
if (conflict !== null)
|
|
535
|
+
throw refuse(conflict);
|
|
536
|
+
}
|
|
362
537
|
/**
|
|
363
538
|
* §3.3 steps 3-4. A payload directory that fails verification is named by the mechanism and the remedy is to delete
|
|
364
539
|
* it; nothing overwrites it. Any other failure is the bundled payload's own, which only a reinstall repairs.
|
|
@@ -379,12 +554,14 @@ function materialize(view, packageRoot) {
|
|
|
379
554
|
}
|
|
380
555
|
}
|
|
381
556
|
/**
|
|
382
|
-
* §8: mcp,
|
|
383
|
-
* re-planned with the verifying planners before any is applied
|
|
384
|
-
* the workspace changes; each apply then re-plans under
|
|
385
|
-
*
|
|
386
|
-
*
|
|
387
|
-
* is
|
|
557
|
+
* §8: mcp, projection in order; removal in reverse. The payload is materialized, then every sub-transaction is
|
|
558
|
+
* re-planned with the verifying planners before any is applied — the projection's guard retirement (B11) and file plan
|
|
559
|
+
* included — so a refusal any planner can find is raised before the workspace changes; each apply then re-plans under
|
|
560
|
+
* the host lock and refuses a plan that went stale. The projection is applied through `applyHostProjection`, the one
|
|
561
|
+
* writer of projection files, which retires an owned steward guard before any projection file changes and reports it
|
|
562
|
+
* as the element's `guard`. Cancellation is observed between sub-transactions. A failure after an element was written
|
|
563
|
+
* names the rerun that finishes the set, or the recovery a pending journal needs. `checkpoint` runs after each element
|
|
564
|
+
* completes, which is where an interruption test cuts.
|
|
388
565
|
*/
|
|
389
566
|
export function applyHostSet(view, packageRoot, signal, checkpoint = () => { }) {
|
|
390
567
|
const refused = view.elements.find((element) => element.conflict !== null);
|
|
@@ -397,60 +574,104 @@ export function applyHostSet(view, packageRoot, signal, checkpoint = () => { })
|
|
|
397
574
|
id,
|
|
398
575
|
status: view.elements.find((element) => element.id === id).capability,
|
|
399
576
|
});
|
|
577
|
+
/** A failure as the refusal it raises: a pending journal's recovery, the held lock's, or once anything was written, the rerun. */
|
|
578
|
+
const failure = (error) => {
|
|
579
|
+
const refusal = refusalOf(error), journal = pendingJournal(root);
|
|
580
|
+
if (journal !== undefined)
|
|
581
|
+
return new Refusal(refusal.code, refusal.message, 3, { path: journal[0] }, say(view, recoverNext(view.root, journal[1])));
|
|
582
|
+
const busy = lockRefusal(error, view.root);
|
|
583
|
+
if (busy !== null)
|
|
584
|
+
return busy;
|
|
585
|
+
if (done.length > 0)
|
|
586
|
+
return new Refusal(refusal.code, refusal.message, 3, refusal.where, say(view, `Run "${rerun}" to finish.`));
|
|
587
|
+
return error;
|
|
588
|
+
};
|
|
400
589
|
const step = (id, run) => {
|
|
401
590
|
if (signal?.aborted)
|
|
402
591
|
throw new Interrupted(say(view, `Run "${rerun}" to finish.`));
|
|
403
|
-
let
|
|
592
|
+
let applied;
|
|
404
593
|
try {
|
|
405
|
-
|
|
594
|
+
applied = run();
|
|
406
595
|
}
|
|
407
596
|
catch (error) {
|
|
408
|
-
|
|
409
|
-
|
|
410
|
-
|
|
411
|
-
const busy = lockRefusal(error, view.root);
|
|
412
|
-
if (busy !== null)
|
|
413
|
-
throw busy;
|
|
414
|
-
if (done.length > 0)
|
|
415
|
-
throw new Refusal(refusal.code, refusal.message, 3, refusal.where, say(view, `Run "${rerun}" to finish.`));
|
|
416
|
-
throw error;
|
|
597
|
+
if (id === 'projection')
|
|
598
|
+
throw projectionFailure(error, root, host, rerun);
|
|
599
|
+
throw failure(error);
|
|
417
600
|
}
|
|
418
|
-
done.push({ id,
|
|
601
|
+
done.push({ id, ...applied });
|
|
419
602
|
checkpoint(id);
|
|
420
603
|
};
|
|
604
|
+
/**
|
|
605
|
+
* Design item 9 (plan amendment C16): the host's join receipts. Receipts that cannot be read are never replaced, and a
|
|
606
|
+
* rerun alone would refuse again, so their refusal names deleting them first: they are derived, and the rerun records
|
|
607
|
+
* them again. Any other failure is `failure`'s.
|
|
608
|
+
*/
|
|
609
|
+
const joinFailure = (error) => {
|
|
610
|
+
if (refusedPath(error) !== JOINS || pendingJournal(root) !== undefined)
|
|
611
|
+
return failure(error);
|
|
612
|
+
const refusal = refusalOf(error);
|
|
613
|
+
return new Refusal(refusal.code, refusal.message, 3, { path: JOINS }, say(view, `Delete ${JOINS}, then run "${rerun}".`));
|
|
614
|
+
};
|
|
615
|
+
/**
|
|
616
|
+
* The join recorded from the committed registration (`joinHost`), or dropped after a removal (`leaveHost`), once every
|
|
617
|
+
* element is applied, so an interrupted apply leaves no join, or the previous one, which `ia doctor` reports as
|
|
618
|
+
* unavailable or drifted rather than as current. A failure here names the rerun that finishes the set.
|
|
619
|
+
*/
|
|
620
|
+
const receipt = (run) => {
|
|
621
|
+
try {
|
|
622
|
+
run();
|
|
623
|
+
}
|
|
624
|
+
catch (error) {
|
|
625
|
+
throw joinFailure(error);
|
|
626
|
+
}
|
|
627
|
+
};
|
|
628
|
+
// Review finding B-N1: receipts that cannot be read refuse before anything is written, the payload included, rather
|
|
629
|
+
// than after the MCP registration (`joinHost` and `leaveHost` read them again under the host lock).
|
|
630
|
+
try {
|
|
631
|
+
readJoins(root);
|
|
632
|
+
}
|
|
633
|
+
catch (error) {
|
|
634
|
+
throw joinFailure(error);
|
|
635
|
+
}
|
|
636
|
+
const project = (rendered, cache) => () => {
|
|
637
|
+
const { status, guard } = applyHostProjection(root, host, rendered, undefined, undefined, cache);
|
|
638
|
+
return { status, guard };
|
|
639
|
+
};
|
|
421
640
|
if (!view.remove) {
|
|
422
641
|
const cache = materialize(view, packageRoot);
|
|
423
642
|
const mcp = replan(view, 'mcp', MCP_PATH[host], () => planHost(root, host, cache));
|
|
424
|
-
|
|
425
|
-
const
|
|
426
|
-
|
|
427
|
-
|
|
428
|
-
|
|
429
|
-
|
|
430
|
-
|
|
431
|
-
|
|
643
|
+
// Review C3-N2: the rendering the plan's gated session made, re-planned against the files as they are now.
|
|
644
|
+
const { rendered } = view;
|
|
645
|
+
// Only a removal's view carries no rendering (collectHost); an apply always has the one its gated plan made.
|
|
646
|
+
if (rendered === null)
|
|
647
|
+
throw new Error('A host apply view carries no rendering');
|
|
648
|
+
// The hook groups run the guard in the payload just materialized and verified (plan amendment C9).
|
|
649
|
+
replanProjection(root, host, rendered, (conflict) => refusalFor(view, 'projection', conflict), {
|
|
650
|
+
verified: cache,
|
|
651
|
+
});
|
|
652
|
+
step('mcp', () => ({ status: applyHost(mcp).status }));
|
|
432
653
|
done.push(skipped('context'));
|
|
433
|
-
step('projection', (
|
|
654
|
+
step('projection', project(rendered, { verified: cache }));
|
|
655
|
+
receipt(() => joinHost(root, host, rendered.receipt.revision));
|
|
434
656
|
return { status: 'host-registered', elements: done, observed: false };
|
|
435
657
|
}
|
|
436
658
|
// A removal plans only what the view found owned; `none` means there is nothing of that element to remove.
|
|
437
659
|
const absent = (id) => view.elements.find((element) => element.id === id).action === 'none';
|
|
438
|
-
|
|
439
|
-
const hooks = host === 'claude' && !absent('hooks')
|
|
440
|
-
? replan(view, 'hooks', SETTINGS, () => planGuardRegistration(root, { remove: HOST_REGISTRATION }))
|
|
441
|
-
: null;
|
|
660
|
+
replanProjection(root, host, null, (conflict) => refusalFor(view, 'projection', conflict));
|
|
442
661
|
const mcp = absent('mcp')
|
|
443
662
|
? null
|
|
444
663
|
: replan(view, 'mcp', MCP_PATH[host], () => planHost(root, host, null, HOST_REGISTRATION));
|
|
445
|
-
step('projection', (
|
|
664
|
+
step('projection', project(null, null));
|
|
446
665
|
done.push(skipped('context'));
|
|
447
|
-
|
|
448
|
-
|
|
449
|
-
else
|
|
450
|
-
step('hooks', () => (hooks === null ? 'absent' : applyGuardRegistration(hooks).status));
|
|
451
|
-
step('mcp', () => (mcp === null ? 'absent' : applyHost(mcp).status));
|
|
666
|
+
step('mcp', () => ({ status: mcp === null ? 'absent' : applyHost(mcp).status }));
|
|
667
|
+
receipt(() => leaveHost(root, host));
|
|
452
668
|
return { status: 'host-removed', elements: done, observed: false };
|
|
453
669
|
}
|
|
670
|
+
/**
|
|
671
|
+
* A conflict as the `--json` envelopes print it (review finding A-F4): its code, path and reason. The descriptors a
|
|
672
|
+
* refusal carries to word its own repair (`hook`, `folder`) stay internal; the repair is the refusal's `next`.
|
|
673
|
+
*/
|
|
674
|
+
export const printedConflict = (conflict) => conflict === null ? null : { code: conflict.code, path: conflict.path, reason: conflict.reason };
|
|
454
675
|
/** §4 `--json`: the plan always, and `applied` only after an apply. */
|
|
455
676
|
const hostEnvelope = (view, applied) => ({
|
|
456
677
|
version: 1,
|
|
@@ -461,7 +682,7 @@ const hostEnvelope = (view, applied) => ({
|
|
|
461
682
|
plan: {
|
|
462
683
|
release: view.release,
|
|
463
684
|
home: view.home,
|
|
464
|
-
elements: view.elements,
|
|
685
|
+
elements: view.elements.map((element) => ({ ...element, conflict: printedConflict(element.conflict) })),
|
|
465
686
|
undo: view.undo,
|
|
466
687
|
...(view.userPlugin === null ? {} : { userPlugin: view.userPlugin }),
|
|
467
688
|
},
|
|
@@ -472,7 +693,7 @@ const FILE_SYMBOL = {
|
|
|
472
693
|
update: 'updated',
|
|
473
694
|
unchanged: 'info',
|
|
474
695
|
remove: 'removed',
|
|
475
|
-
|
|
696
|
+
foreign: 'info',
|
|
476
697
|
};
|
|
477
698
|
const elementSymbol = (element) => element.conflict !== null
|
|
478
699
|
? 'error'
|
|
@@ -482,8 +703,10 @@ const elementSymbol = (element) => element.conflict !== null
|
|
|
482
703
|
function elementFields(view) {
|
|
483
704
|
return view.elements.map((element) => {
|
|
484
705
|
const facts = [element.action, element.capability, ...(element.id === 'projection' ? [] : element.paths)];
|
|
485
|
-
if (element.id === '
|
|
706
|
+
if (element.id === 'context' && element.capability === 'unsupported by host')
|
|
486
707
|
facts.push(CODEX_HOOKS.replace(/\.$/, ''));
|
|
708
|
+
if (element.guard === 'retire')
|
|
709
|
+
facts.push(GUARD_RETIRE);
|
|
487
710
|
if (element.conflict !== null)
|
|
488
711
|
facts.push(`${element.conflict.code} ${element.conflict.reason}`);
|
|
489
712
|
return {
|
|
@@ -494,20 +717,42 @@ function elementFields(view) {
|
|
|
494
717
|
};
|
|
495
718
|
});
|
|
496
719
|
}
|
|
497
|
-
/**
|
|
498
|
-
const
|
|
720
|
+
/** A projection plan's B11 step as its plan says it, in `ia host` and `ia project` alike. */
|
|
721
|
+
export const GUARD_RETIRE = `first retires the steward guard registered in ${SETTINGS}`;
|
|
722
|
+
/**
|
|
723
|
+
* Each projected file with its action, at `column`; a foreign steward file says why it is left alone. `ia host` nests
|
|
724
|
+
* the rows under its projection element and `ia project` lists them as its file plan, so both word them alike.
|
|
725
|
+
*/
|
|
726
|
+
export const projectionFileRows = (files, column, caps) => files.flatMap((file) => entry([
|
|
499
727
|
[
|
|
500
728
|
atom(file.path, 'cyan', 0),
|
|
501
|
-
...words(file.action === '
|
|
502
|
-
? "
|
|
729
|
+
...words(file.action === 'foreign'
|
|
730
|
+
? "foreign; not this workspace's projection to write or delete, left in place"
|
|
503
731
|
: file.action, null, 2),
|
|
504
732
|
],
|
|
505
|
-
],
|
|
506
|
-
|
|
507
|
-
|
|
508
|
-
|
|
509
|
-
|
|
510
|
-
|
|
733
|
+
], { column, symbol: FILE_SYMBOL[file.action] }, caps));
|
|
734
|
+
const HOOK_SYMBOL = {
|
|
735
|
+
create: 'added',
|
|
736
|
+
update: 'updated',
|
|
737
|
+
unchanged: 'info',
|
|
738
|
+
remove: 'removed',
|
|
739
|
+
};
|
|
740
|
+
/** Each authored `@hook`'s group with its action (plan amendment C9), worded alike by `ia host` and `ia project`. */
|
|
741
|
+
export const projectionHookRows = (hooks, column, caps) => hooks.flatMap((hook) => entry([[atom(hook.hook, 'cyan', 0), ...words(`hook group ${hook.action}`, null, 2)]], { column, symbol: HOOK_SYMBOL[hook.action] }, caps));
|
|
742
|
+
/** Each authored record the host does not take, with the reason, worded alike by `ia host` and `ia project`. */
|
|
743
|
+
export const unsupportedRows = (rows, column, caps) => rows.flatMap((row) => entry([[atom(row.identity, 'cyan', 0), ...words(`${row.word} not taken: ${row.reason}`, null, 2)]], { column, symbol: 'warning' }, caps));
|
|
744
|
+
/**
|
|
745
|
+
* Each projected file, then each hook group and each record not taken, nested at the elements block's content column
|
|
746
|
+
* (§6.4 rule 3), under the element they belong to.
|
|
747
|
+
*/
|
|
748
|
+
const fileBlock = (view, caps) => {
|
|
749
|
+
const projection = view.elements.find((element) => element.id === 'projection'), column = indentOf(1) + blockSymbolWidth(view.elements.map(elementSymbol), caps.ascii) + 2;
|
|
750
|
+
return [
|
|
751
|
+
...projectionFileRows(projection?.files ?? [], column, caps),
|
|
752
|
+
...projectionHookRows(projection?.hooks ?? [], column, caps),
|
|
753
|
+
...unsupportedRows(projection?.unsupported ?? [], column, caps),
|
|
754
|
+
];
|
|
755
|
+
};
|
|
511
756
|
const headerBlock = (view, caps) => [
|
|
512
757
|
...headerLine('Plan', `host ${view.host}${view.remove ? ' --remove' : ''}`, [{ text: `release ${truncateDigest(view.release, caps.ascii)}`, column: 35 }], caps),
|
|
513
758
|
...headerLine('Root', view.root, [], caps),
|
|
@@ -519,9 +764,9 @@ const elementsBlock = (view, caps) => [
|
|
|
519
764
|
...fileBlock(view, caps),
|
|
520
765
|
];
|
|
521
766
|
/**
|
|
522
|
-
* §5.3's machine-local sentence and, for a Claude registration, §5.4's approval note and the guard's
|
|
523
|
-
*
|
|
524
|
-
*
|
|
767
|
+
* §5.3's machine-local sentence and, for a Claude registration, §5.4's approval note and the guard's retirement (only
|
|
768
|
+
* Claude ever registered the guard, B11). `ia init --host` prints the same blocks after its host step, so the two verbs
|
|
769
|
+
* cannot word them differently.
|
|
525
770
|
*/
|
|
526
771
|
export const hostNotes = (host, caps, remove = false) => [
|
|
527
772
|
entry([words(MACHINE_LOCAL[host])], { depth: 1, symbol: 'warning' }, caps),
|
|
@@ -542,7 +787,7 @@ const notesBlocks = (view, caps) => [
|
|
|
542
787
|
? [entry([words(USER_PLUGIN_MISSING)], { depth: 1, symbol: 'info' }, caps)]
|
|
543
788
|
: []),
|
|
544
789
|
];
|
|
545
|
-
export function renderHostPlan(view, applied, caps) {
|
|
790
|
+
export function renderHostPlan(view, applied, caps, supplied) {
|
|
546
791
|
const conflicted = view.elements.some((element) => element.conflict !== null);
|
|
547
792
|
return document([
|
|
548
793
|
headerBlock(view, caps),
|
|
@@ -552,15 +797,18 @@ export function renderHostPlan(view, applied, caps) {
|
|
|
552
797
|
words(applied.status === 'host-registered'
|
|
553
798
|
? 'Registered: written; not observed answering.'
|
|
554
799
|
: 'Removed the owned host set.'),
|
|
800
|
+
...(applied.elements.some((element) => element.guard === 'retired') ? [words(GUARD_RETIRED)] : []),
|
|
555
801
|
], { depth: 1, symbol: 'success' }, caps),
|
|
556
802
|
elementsBlock(view, caps),
|
|
557
803
|
...notesBlocks(view, caps),
|
|
558
804
|
entry([
|
|
559
805
|
...(applied === null && !conflicted
|
|
560
|
-
? commandFacts('Apply with "', `${view.invocation} --apply --yes`, '".', 3, caps)
|
|
806
|
+
? commandFacts('Apply with "', `${view.invocation} --apply --yes`, '".', 3, caps, [view.root, supplied])
|
|
561
807
|
: []),
|
|
562
808
|
// `plan.undo` stays unrooted (§4 `--json`); the printed command carries --root when it was given.
|
|
563
|
-
...(view.remove
|
|
809
|
+
...(view.remove
|
|
810
|
+
? []
|
|
811
|
+
: commandFacts('Undo with "', say(view, `"${view.undo}"`).slice(1, -1), '".', 3, caps, [view.root])),
|
|
564
812
|
...(applied !== null && !view.remove ? [words('Run "ia doctor" for the observed host state.')] : []),
|
|
565
813
|
], { depth: 0, symbol: 'step' }, caps),
|
|
566
814
|
], { leadingBlank: true });
|
|
@@ -594,7 +842,7 @@ export async function runHost(context) {
|
|
|
594
842
|
}
|
|
595
843
|
const rendered = (applied) => json
|
|
596
844
|
? { exitCode: 0, stdout: JSON.stringify(hostEnvelope(view, applied)) + '\n', stderr: '' }
|
|
597
|
-
: { exitCode: 0, stdout: renderHostPlan(view, applied, caps), stderr: '' };
|
|
845
|
+
: { exitCode: 0, stdout: renderHostPlan(view, applied, caps, args.value('root')), stderr: '' };
|
|
598
846
|
// §4: a plan with a conflict is a successful report; only --apply refuses it.
|
|
599
847
|
if (!args.flag('apply'))
|
|
600
848
|
return rendered(null);
|
|
@@ -605,7 +853,10 @@ export async function runHost(context) {
|
|
|
605
853
|
exitCode: 0,
|
|
606
854
|
stdout: document([
|
|
607
855
|
entry([words('Nothing was applied.')], { depth: 0, symbol: 'info' }, caps),
|
|
608
|
-
entry(commandFacts('Apply with "', `${view.invocation} --apply --yes`, '".', 3, caps
|
|
856
|
+
entry(commandFacts('Apply with "', `${view.invocation} --apply --yes`, '".', 3, caps, [
|
|
857
|
+
view.root,
|
|
858
|
+
args.value('root'),
|
|
859
|
+
]), { depth: 0, symbol: 'step' }, caps),
|
|
609
860
|
], { leadingBlank: true }),
|
|
610
861
|
stderr: '',
|
|
611
862
|
};
|