create-agent-rig 0.3.2 → 0.5.0

package/packages/cli/dist/commands/init.js

@@ -1,12 +1,19 @@
 import { access, mkdir, readFile, writeFile } from 'node:fs/promises';
 import path from 'node:path';
 import { settingsForInstalledHooks } from '../lib/init-settings.js';
+import { mapConcurrent } from '../lib/copy-tree.js';
+import { readManifest, sha256, writeManifest } from '../lib/manifest.js';
 import { substituteContent } from '../lib/substitute.js';
 import { agentOsInitDir, agentOsUniversalDir } from '../templates.js';
+import { packageVersion } from '../lib/version.js';
 /** A user-facing failure: message is printed as-is, no stack trace. */
 export class InitError extends Error {
 }
+/** What `--force` answers with now that `upgrade` owns the case it stood in for. */
+export const FORCE_DEPRECATED = 'deprecated — init --force replaced only CLAUDE.md; run create-agent-rig upgrade instead';
 const SETTINGS = '.claude/settings.json';
+const CODEX_HOOKS = '.codex/hooks.json';
+const MAPS = ['CLAUDE.md', 'AGENTS.md'];
 async function loadManifest() {
     const raw = await readFile(path.join(agentOsUniversalDir(), 'layers.json'), 'utf8');
     return JSON.parse(raw);
@@ -51,15 +58,15 @@ export async function initManifest() {
     const manifest = await loadManifest();
     const universal = agentOsUniversalDir();
     const override = agentOsInitDir();
-    const files = [];
-    for (const rel of [...manifest.process, 'CLAUDE.md']) {
+    const files = await mapConcurrent([...manifest.process, ...MAPS], 16, async (rel) => {
         const overridden = path.join(override, rel);
-        files.push({
+        return {
             rel,
             source: (await exists(overridden)) ? overridden : path.join(universal, rel),
-        });
-    }
+        };
+    });
     files.push({ rel: SETTINGS, source: null });
+    files.push({ rel: CODEX_HOOKS, source: null });
     return files;
 }
 /**
@@ -71,57 +78,136 @@ export async function initManifest() {
  * `__PROJECT_NAME__` in `stop-flag.mjs` is a kill switch that silently never
  * fires.
  */
-export async function initFileContents(repoDir) {
-    const projectName = projectNameFor(repoDir);
-    const ctx = { projectName, projectScope: projectName, region: '' };
+export async function initFileContents(repoDir, project) {
+    const projectName = project?.name ?? projectNameFor(repoDir);
+    const ctx = {
+        projectName,
+        projectScope: project?.scope ?? projectName,
+        region: project?.region ?? '',
+    };
     const files = await initManifest();
     const contents = new Map();
-    for (const { rel, source } of files) {
-        if (source === null)
-            continue;
-        contents.set(rel, substituteContent(await readFile(source, 'utf8'), ctx));
+    const sourceFiles = files.filter((file) => file.source !== null);
+    const rendered = await mapConcurrent(sourceFiles, 16, async ({ rel, source }) => ({
+        rel,
+        content: substituteContent(await readFile(source, 'utf8'), ctx),
+    }));
+    for (const { rel, content } of rendered) {
+        contents.set(rel, content);
     }
     const installedHooks = new Set(files.map((f) => f.rel).filter((rel) => rel.startsWith('.claude/hooks/')));
-    const shipped = JSON.parse(await readFile(path.join(agentOsUniversalDir(), SETTINGS), 'utf8'));
+    const [shippedSettings, shippedCodexHooks] = await Promise.all([
+        readFile(path.join(agentOsUniversalDir(), SETTINGS), 'utf8'),
+        readFile(path.join(agentOsUniversalDir(), CODEX_HOOKS), 'utf8'),
+    ]);
+    const shipped = JSON.parse(shippedSettings);
     contents.set(SETTINGS, `${JSON.stringify(settingsForInstalledHooks(shipped, installedHooks), null, 2)}\n`);
+    const shippedCodex = JSON.parse(shippedCodexHooks);
+    contents.set(CODEX_HOOKS, `${JSON.stringify(settingsForInstalledHooks(shippedCodex, installedHooks), null, 2)}\n`);
     return contents;
 }
+/** The process layer as a set of {@link InstalledFile}s — what `upgrade` reads. */
+export async function initInstallSet(repoDir, project) {
+    const files = await initManifest();
+    const contents = await initFileContents(repoDir, project);
+    return files.map(({ rel, source }) => ({ rel, source, content: contents.get(rel) ?? '' }));
+}
 export async function planInit(repoDir) {
     const files = (await initManifest()).map((f) => f.rel);
-    const conflicts = [];
-    for (const rel of files) {
-        if (await exists(path.join(repoDir, rel)))
-            conflicts.push(rel);
-    }
+    const conflicts = (await mapConcurrent(files, 16, async (rel) => (await exists(path.join(repoDir, rel))) ? rel : null)).filter((rel) => rel !== null);
     return { files: files.map((p) => ({ path: p })), conflicts };
 }
 export async function initProject(repoDir, options) {
+    // Refused before anything is read or written, so a deprecated flag cannot
+    // half-install: `upgrade` covers what this stood in for, and it decides per
+    // file from the manifest instead of overriding one refusal wholesale.
+    if (options.force)
+        throw new InitError(FORCE_DEPRECATED);
     const files = (await initManifest()).map((f) => f.rel);
-    // Refuse to clobber an existing CLAUDE.md unless forced — init edits
-    // someone's working repository (brief §4, non-negotiable).
-    if (!options.force && files.includes('CLAUDE.md')) {
-        if (await exists(path.join(repoDir, 'CLAUDE.md'))) {
-            throw new InitError('This repo already has a CLAUDE.md. Refusing to overwrite it. ' +
-                'Merge the agent-os map in by hand, or re-run with --force to replace it.');
+    const previous = await readManifest(repoDir);
+    // Refuse to clobber an existing CLAUDE.md — init edits someone's working
+    // repository (brief §4, non-negotiable).
+    for (const map of MAPS) {
+        if (files.includes(map) && (await exists(path.join(repoDir, map)))) {
+            // A create rig whose CLAUDE.md was deleted is the legacy route into init.
+            // Its generated AGENTS.md must not newly close that route, but only the
+            // manifest can distinguish that file from a user's own Codex guidance.
+            if (map === 'AGENTS.md' &&
+                previous?.files[map] !== undefined &&
+                sha256(await readFile(path.join(repoDir, map), 'utf8')) === previous.files[map]) {
+                continue;
+            }
+            throw new InitError(`This repo already has an ${map}. Refusing to overwrite it. ` +
+                'Merge the agent-os map in by hand, or run create-agent-rig upgrade to refresh a rig.');
         }
     }
     const contents = await initFileContents(repoDir);
-    const written = [];
-    const skipped = [];
     const plannedCount = files.length;
-    for (const rel of files) {
+    const actions = await mapConcurrent(files, 16, async (rel) => {
         const dest = path.join(repoDir, rel);
-        const isForceableMeta = rel === 'CLAUDE.md';
-        if ((await exists(dest)) && !(isForceableMeta && options.force)) {
+        if (await exists(dest)) {
             // never overwrite a file init did not write (a user's own copy)
-            skipped.push(rel);
-            continue;
+            return { rel, verdict: 'skipped' };
         }
         if (options.dryRun)
-            continue;
+            return { rel, verdict: 'planned' };
         await mkdir(path.dirname(dest), { recursive: true });
         await writeFile(dest, contents.get(rel) ?? '');
-        written.push(rel);
-    }
+        return { rel, verdict: 'written' };
+    });
+    const written = actions.filter(({ verdict }) => verdict === 'written').map(({ rel }) => rel);
+    const skipped = actions.filter(({ verdict }) => verdict === 'skipped').map(({ rel }) => rel);
+    if (!options.dryRun)
+        await recordInstall(repoDir, written, contents);
     return { written, skipped, plannedCount };
 }
+/**
+ * Record what was installed, so a later `upgrade` can tell a file it wrote
+ * from a file the user owns.
+ *
+ * Only files actually **written** are recorded. A file `init` kept is
+ * somebody else's — claiming it here would let the next upgrade replace a
+ * user's own document with the rig's. Earlier entries are preserved: a re-run
+ * writes nothing and must not therefore un-remember everything.
+ *
+ * 🔴 **`kind`, `project` and `stacks` are preserved, not rewritten.** Reached
+ * inside a rig `create` produced, this used to stamp `kind: 'init'`,
+ * `stacks: []` and an empty `region` over the truth — and `planUpgrade` trusts
+ * a manifest wholesale (it never re-detects), so the next upgrade routed to the
+ * `init` install set and the stack overlays left the plan entirely: not
+ * reported as deleted, not as a conflict, simply absent. `init` describes what
+ * it wrote; it does not get to re-describe how the rig was installed.
+ *
+ * ⚠ **The limit, stated because the fix reads as wider than it is:** this
+ * preserves a manifest, so a rig that has none — anything from before 0.4.0 —
+ * still gets `kind: 'init'`, no stacks and an empty region, and the advisory in
+ * `runInit` stays silent for the same reason. `upgrade`'s `detectInstall`
+ * recovers all three from the files on disk, so those values are not
+ * unavailable, only unavailable *here*: reaching for it would point
+ * `commands/init` at `commands/upgrade`, which already imports this module.
+ * The fallback below is the honest floor, not the best available answer.
+ *
+ * The item that asked for this also floated refusing `init` outright on a
+ * `create` manifest. It is already refused a step earlier and for a different
+ * reason — {@link initProject} throws on the existing `CLAUDE.md`. The gap that
+ * leaves is a `create` rig whose `CLAUDE.md` was deleted, and this function is
+ * what makes that case safe.
+ */
+async function recordInstall(repoDir, written, contents) {
+    const previous = await readManifest(repoDir);
+    const name = projectNameFor(repoDir);
+    const files = { ...(previous?.files ?? {}) };
+    for (const rel of written)
+        files[rel] = sha256(contents.get(rel) ?? '');
+    const manifest = {
+        version: await packageVersion(),
+        kind: previous?.kind ?? 'init',
+        // No manifest: fall back to the directory name, which is all this module
+        // reads. See the limit above — `upgrade` can do better from the files
+        // themselves, and `init` deliberately does not reach for it.
+        project: previous?.project ?? { name, scope: name, region: '' },
+        stacks: previous?.stacks ?? [],
+        files,
+    };
+    await writeManifest(repoDir, manifest);
+}

package/packages/cli/dist/commands/upgrade.js

@@ -0,0 +1,382 @@
+import { access, mkdir, readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { initInstallSet, projectNameFor } from './init.js';
+import { hookFilesReferencedIn } from '../lib/init-settings.js';
+import { loadHashHistory, presentInEveryRelease } from '../lib/history.js';
+import { agentOsInstallSet, agentOsLayerDirs } from '../lib/install-set.js';
+import { listTree } from '../lib/copy-tree.js';
+import { readManifest, sha256, writeManifest } from '../lib/manifest.js';
+import { isSafeSubstitutionValue, resolveInside } from '../lib/safe-path.js';
+import { detokenizeContent, substituteFileName } from '../lib/substitute.js';
+import { TARGETS } from '../lib/targets.js';
+import { packageVersion } from '../lib/version.js';
+/** A user-facing failure: message is printed as-is, no stack trace. */
+export class UpgradeError extends Error {
+}
+const SETTINGS = '.claude/settings.json';
+const CODEX_HOOKS = '.codex/hooks.json';
+const WIRING_PATHS = new Set([SETTINGS, CODEX_HOOKS]);
+/** The universal layer's architecture group — installed by `create`, never by `init`. */
+const ARCHITECTURE_ONLY = [
+    '.claude/rules/architecture.md',
+    '.claude/hooks/guard-core-purity.mjs',
+    '.claude/hooks/guard-web-boundary.mjs',
+];
+async function exists(p) {
+    try {
+        await access(p);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Where `rel` lives inside the rig — refused outright if it lands anywhere
+ * else. Nothing should be able to produce such a path once the manifest is
+ * validated, which is exactly why this stays: the whole command is writes into
+ * somebody's repository, and a containment check is cheap next to the cost of
+ * being wrong about that.
+ */
+function onDisk(repoDir, rel) {
+    const dest = resolveInside(repoDir, rel);
+    if (dest === null) {
+        throw new UpgradeError(`Refusing to touch "${rel}" — it resolves outside ${repoDir}.`);
+    }
+    return dest;
+}
+/**
+ * The file's bytes, or `null` when it is genuinely **absent**.
+ *
+ * Only "not there" is absence. Any other failure — a permission, a directory
+ * where a file should be, a path this command refuses to touch — is rethrown,
+ * because "I could not read your file" must never become "so I wrote mine over
+ * it": every caller of this treats `null` as grounds to install.
+ */
+async function readIfPresent(repoDir, rel) {
+    try {
+        return await readFile(onDisk(repoDir, rel), 'utf8');
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return null;
+        throw error;
+    }
+}
+/** Every stack overlay any target composes — the candidates a rig can carry. */
+function knownStacks() {
+    return [...new Set(Object.values(TARGETS).flatMap((t) => t.stacks))];
+}
+/**
+ * What a rig with no manifest looks like it is, from the files it has.
+ *
+ * Two signals, because one file is too thin a thread to hang a project's map
+ * on: the architecture rules and hooks, which `create` installs and `init`
+ * deliberately does not, **and** any stack-overlay file at all — `init`
+ * composes no overlays, so one of those is proof on its own. The region comes
+ * from the target whose stack set matches; it is the only value substitution
+ * needs that the directory name cannot give.
+ *
+ * 🔴 Limit: a `create` rig that deleted every architecture file *and* every
+ * stack file reads as an `init` rig. It is then offered the `init` flavour of
+ * `CLAUDE.md` — a map of a different project shape. Nothing but a manifest
+ * distinguishes those two rigs, which is why 0.4.0 writes one.
+ */
+async function detectInstall(repoDir) {
+    const ctx = { projectName: '', projectScope: '', region: '' };
+    const stacks = [];
+    for (const stack of knownStacks()) {
+        const [layer] = agentOsLayerDirs([stack]).slice(1);
+        if (layer === undefined)
+            continue;
+        const rels = await listTree(layer.dir, {
+            transformName: (name) => substituteFileName(name, ctx),
+        });
+        for (const rel of rels) {
+            if (await exists(onDisk(repoDir, rel))) {
+                stacks.push(stack);
+                break;
+            }
+        }
+    }
+    let architectural = stacks.length > 0;
+    for (const rel of ARCHITECTURE_ONLY) {
+        if (architectural)
+            break;
+        architectural = await exists(onDisk(repoDir, rel));
+    }
+    if (!architectural)
+        return { kind: 'init', stacks: [], region: '' };
+    const target = Object.values(TARGETS).find((t) => t.stacks.length === stacks.length && t.stacks.every((s) => stacks.includes(s)));
+    return { kind: 'create', stacks, region: target?.defaultRegion ?? '' };
+}
+async function installSetFor(repoDir, kind, project, stacks) {
+    if (kind === 'init')
+        return initInstallSet(repoDir, project);
+    return agentOsInstallSet(stacks, {
+        projectName: project.name,
+        projectScope: project.scope,
+        region: project.region,
+    });
+}
+/**
+ * Whether these bytes are a released version of this file.
+ *
+ * Two candidates are offered to the table: the bytes as they sit, and the
+ * bytes with the project's own values turned back into tokens — released
+ * template bytes carry `__PROJECT_NAME__`, installed bytes never do.
+ */
+function isReleasedVersion(history, rel, content, ctx) {
+    const known = history.files[rel];
+    if (known === undefined || known.hashes.length === 0)
+        return false;
+    const candidates = new Set([sha256(content), sha256(detokenizeContent(content, ctx))]);
+    return known.hashes.some((hash) => candidates.has(hash));
+}
+/**
+ * Would writing `next` over `current` stop calling a hook that is still there?
+ *
+ * The one question the hash arms cannot answer. They prove the bytes belong to
+ * the rig; they do not prove the replacement wires the same hooks, and
+ * Wiring files have flavours that differ in exactly that. A hook file
+ * still on disk with nothing wired to it is the quiet failure
+ * `lib/init-settings.ts` names: the rules claim it is enforced and nothing ever
+ * calls it.
+ *
+ * Only hooks whose FILE is still present count. One the user deleted on purpose
+ * is not being silenced by this write — it was already gone.
+ */
+async function unwiresAnInstalledHook(repoDir, current, next) {
+    const nextHooks = hookFilesReferencedIn(next);
+    for (const hook of hookFilesReferencedIn(current)) {
+        if (nextHooks.has(hook))
+            continue;
+        const onDisk = resolveInside(repoDir, hook);
+        if (onDisk !== null && (await exists(onDisk)))
+            return true;
+    }
+    return false;
+}
+/**
+ * What an upgrade would do, decided per file, writing nothing.
+ *
+ * The rule is the whole design: **replace what the rig installed and the user
+ * did not touch; report everything else.** There is no three-way merge and no
+ * patching — silently merging someone's edits into a file the agent loop obeys
+ * is how a rig stops meaning what its owner thinks it means.
+ */
+export async function planUpgrade(repoDir, options = {}) {
+    const manifest = await readManifest(repoDir);
+    // Detection is a whole-tree probe, and it answers a question the manifest
+    // has already answered when there is one.
+    const detected = manifest === null
+        ? await detectInstall(repoDir)
+        : { kind: manifest.kind, stacks: manifest.stacks, region: manifest.project.region };
+    const kind = manifest?.kind ?? detected.kind;
+    // With no manifest to read, guess the name the rig's own files were written
+    // with — and each command wrote them differently, so the guess branches the
+    // same way:
+    //
+    // - `init` substitutes the **slug** and records the slug (`init.ts`,
+    //   `projectNameFor` in both places), so for an init rig the slug is not an
+    //   approximation, it is the value;
+    // - `create` substitutes the name it was **given**, having validated it — and
+    //   that validation accepts a trailing `-` or `.`, which `projectNameFor`
+    //   strips. So slugging a create rig renames it: `my-app.` became `my-app`,
+    //   stopped matching its own installed files, and returned four of them as
+    //   conflicts.
+    //
+    // The one case where the raw name cannot be kept is a directory the manifest
+    // reader would refuse — `My App` produced `{"name":"My App"}`, which
+    // `parseManifest` voids, so the manifest this command exists to write was
+    // written and immediately unreadable and every later run reported "no
+    // manifest here (a pre-0.4.0 rig)". The condition is that reader's own
+    // exported predicate, not a second copy of its rule.
+    //
+    // 🔴 All three branches were bought by a defect, and two of those defects
+    // were introduced by fixing the other — the mirror is easy to miss, because
+    // each fix looks total until the other kind is tried. Change nothing here
+    // without running the three sibling cases in `upgrade.test.ts`.
+    //
+    // ⚠ It is still the *directory's* name, so a renamed or cloned rig with no
+    // manifest bootstraps the new name and its substituted files come back as
+    // conflicts — kept and reported, never overwritten. Committing the manifest
+    // is what removes the guess, and that is unchanged from 0.4.0.
+    const rawName = path.basename(path.resolve(repoDir));
+    const bootstrapName = kind === 'init' || !isSafeSubstitutionValue(rawName) ? projectNameFor(repoDir) : rawName;
+    const project = manifest?.project ?? {
+        name: bootstrapName,
+        scope: bootstrapName,
+        region: detected.region,
+    };
+    // Only overlays this version actually ships. An unknown name is not input
+    // being dropped — there is no layer behind it to install from — and reading
+    // a directory a manifest names would be reading a directory a manifest names.
+    const shipped = new Set(knownStacks());
+    const stacks = (manifest?.stacks ?? detected.stacks).filter((stack) => shipped.has(stack));
+    const history = options.history ?? (await loadHashHistory());
+    const files = await installSetFor(repoDir, kind, project, stacks);
+    const ctx = {
+        projectName: project.name,
+        projectScope: project.scope,
+        region: project.region,
+    };
+    const actions = [];
+    const contents = new Map();
+    const nextFiles = {};
+    let wiring = null;
+    const wiringByPath = new Map();
+    for (const file of files) {
+        const current = await readIfPresent(repoDir, file.rel);
+        const recorded = manifest?.files[file.rel];
+        contents.set(file.rel, file.content);
+        if (current === null) {
+            // Evidence, not a command. The manifest is the direct evidence; without
+            // one, a path that shipped in *every* release the table covers was there
+            // to be removed, so its absence is a decision. A path added later is
+            // simply missing from an older rig, and that one is delivered.
+            if (recorded !== undefined) {
+                actions.push({
+                    rel: file.rel,
+                    verdict: 'deleted',
+                    reason: 'installed by the rig, removed since — not restored',
+                });
+                nextFiles[file.rel] = recorded;
+            }
+            else if (presentInEveryRelease(history, file.rel)) {
+                actions.push({
+                    rel: file.rel,
+                    verdict: 'deleted',
+                    reason: `shipped in every release since ${history.versions[0]}, and is gone — not restored`,
+                });
+            }
+            else {
+                actions.push({ rel: file.rel, verdict: 'new', templatePath: file.source });
+                nextFiles[file.rel] = sha256(file.content);
+            }
+            continue;
+        }
+        // The two limits that keep wiring files' new replaceability from
+        // disarming the rig, both measured rather than reasoned about.
+        //
+        // 1. The released-hash fallback is not enough for THIS file. Every other
+        //    file has one flavour; this one has two — `create` wires all the hooks,
+        //    `init` wires only the ones it installs — and they share a history
+        //    entry. A manifest-less rig that ran `init` is recorded `kind: 'init'`,
+        //    so matching a released hash would write the narrow wiring over the
+        //    full one. The item asks for the manifest arm and says the rest is
+        //    reported, which is also the reading with no regression behind it.
+        // 2. Even the manifest arm is not enough on its own, because `kind` is
+        //    trusted from a file that travels in pull requests. So the decision is
+        //    gated on the wiring itself: if the replacement would stop calling a
+        //    hook still sitting in `.claude/hooks/`, it is handed over. That check
+        //    does not care which flavour anything claims to be.
+        const isWiring = WIRING_PATHS.has(file.rel);
+        const wouldUnwireAnInstalledHook = isWiring && (await unwiresAnInstalledHook(repoDir, current, file.content));
+        const vouched = isWiring
+            ? recorded !== undefined && sha256(current) === recorded
+            : (recorded !== undefined && sha256(current) === recorded) ||
+                isReleasedVersion(history, file.rel, current, ctx);
+        if (current === file.content) {
+            actions.push({ rel: file.rel, verdict: 'unchanged' });
+            nextFiles[file.rel] = sha256(file.content);
+        }
+        else if (vouched && !wouldUnwireAnInstalledHook) {
+            actions.push({
+                rel: file.rel,
+                verdict: 'update',
+                templatePath: file.source,
+                // Every other replacement is routine; this one rewrites what calls the
+                // guards, so it says so rather than arriving as one more `~` line.
+                ...(isWiring ? { reason: 'the hook wiring, replaced — you never edited it' } : {}),
+            });
+            nextFiles[file.rel] = sha256(file.content);
+        }
+        else if (isWiring) {
+            // Nothing vouches for these bytes, or replacing them would silence a hook
+            // that is still installed. Either way this is the one file whose conflict
+            // is a merge rather than a choice, so the released file is handed over.
+            wiring = file.content;
+            wiringByPath.set(file.rel, file.content);
+            actions.push({
+                rel: file.rel,
+                verdict: 'wiring',
+                // Say what was actually checked. This file no longer consults the
+                // released-hash table (see the limits above), so it cannot claim these
+                // bytes are not a release — only that the manifest does not vouch for
+                // them, which is the check that ran.
+                reason: wouldUnwireAnInstalledHook
+                    ? 'replacing it would stop calling a hook that is still installed — merge the entries below by hand'
+                    : recorded === undefined
+                        ? 'the manifest does not vouch for it — treated as yours, merge the entries below by hand'
+                        : 'edited since it was installed — merge the entries below by hand',
+            });
+            if (recorded !== undefined)
+                nextFiles[file.rel] = recorded;
+        }
+        else {
+            actions.push({
+                rel: file.rel,
+                verdict: 'conflict',
+                reason: recorded === undefined
+                    ? 'not a version this rig ever released — treated as yours'
+                    : 'edited since it was installed',
+                templatePath: file.source,
+            });
+            // deliberately NOT recorded: the rig does not own these bytes
+        }
+    }
+    // With no manifest, "there is a rig here" has to be *recognised*, not
+    // assumed from a file existing: `CLAUDE.md` and `.claude/settings.json` are
+    // in the install set and in nearly every repository ever opened by an agent.
+    // Recognition means bytes we know — a file already current, or one that
+    // matches a released version. Without that this command would silently
+    // perform an `init` nobody asked for.
+    if (manifest === null &&
+        !actions.some((a) => a.verdict === 'unchanged' || a.verdict === 'update'))
+        throw new UpgradeError(`No rig found in ${repoDir}. Nothing here is recognisable as a create-agent-rig ` +
+            'install — run `create-agent-rig init` to install the process layer, or upgrade ' +
+            'from the directory that holds the rig.');
+    return {
+        kind,
+        fromVersion: manifest?.version ?? null,
+        toVersion: await packageVersion(),
+        bootstrapped: manifest === null,
+        actions,
+        wiring,
+        wiringByPath,
+        contents,
+        manifest: {
+            version: await packageVersion(),
+            kind,
+            project,
+            stacks: [...stacks],
+            files: nextFiles,
+        },
+    };
+}
+/**
+ * Write the plan: the `update` and `new` files, then the manifest. Everything
+ * else in the plan is a sentence for a human, not an edit.
+ */
+export async function applyUpgrade(repoDir, plan, options = {}) {
+    const written = [];
+    if (options.dryRun === true)
+        return { written };
+    for (const action of plan.actions) {
+        if (action.verdict !== 'update' && action.verdict !== 'new')
+            continue;
+        const content = plan.contents.get(action.rel);
+        // Never a silent empty file: a missing entry is a defect in the plan, and
+        // truncating somebody's rule file is the worst way to report one.
+        if (content === undefined) {
+            throw new UpgradeError(`Internal: no content planned for "${action.rel}" — nothing written.`);
+        }
+        const dest = onDisk(repoDir, action.rel);
+        await mkdir(path.dirname(dest), { recursive: true });
+        await writeFile(dest, content);
+        written.push(action.rel);
+    }
+    await writeManifest(repoDir, plan.manifest);
+    return { written };
+}