create-agent-rig 0.8.0 → 0.9.1

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

@@ -315,17 +315,34 @@ export async function planUpgrade(repoDir, options = {}) {
                 nextFiles[file.rel] = recorded;
         }
         else {
+            // A path `init` found and left alone carries its provenance in `kept`
+            // (RP-182): the reason can then say what happened to the file since,
+            // instead of only that no release ever shipped these bytes. It names no
+            // version — `manifest.version` is rewritten by every upgrade, so it is
+            // not the version of the init that kept the file.
+            const kept = recorded === undefined ? manifest?.kept?.[file.rel] : undefined;
+            const keptReason = (since) => `kept by init (already here, not the rig's bytes), ${since} since — treated as yours`;
             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',
+                reason: kept !== undefined
+                    ? keptReason(sha256(current) === kept ? 'unchanged' : 'edited')
+                    : 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
+            // deliberately NOT recorded in `files`: the rig does not own these bytes
         }
     }
+    // `kept` travels forward untouched, minus every path the plan now vouches
+    // for in `files` — a kept file that turned out to be a released version, or
+    // is byte-identical to this release, has become the rig's to manage.
+    const nextKept = {};
+    for (const [rel, hash] of Object.entries(manifest?.kept ?? {})) {
+        if (nextFiles[rel] === undefined)
+            nextKept[rel] = hash;
+    }
     // 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.
@@ -352,6 +369,7 @@ export async function planUpgrade(repoDir, options = {}) {
             project,
             stacks: [...stacks],
             files: nextFiles,
+            ...(Object.keys(nextKept).length > 0 ? { kept: nextKept } : {}),
         },
     };
 }

package/packages/cli/dist/index.js

@@ -2,13 +2,16 @@
 import { parseArgs } from 'node:util';
 import { CreateError, createProject } from './commands/create.js';
 import { InitError, initFileContents, initProject, planInit } from './commands/init.js';
+import { execFileRunner, setupSubsystems } from './commands/setup.js';
 import { UpgradeError, applyUpgrade, planUpgrade } from './commands/upgrade.js';
 import { makePalette } from './lib/colors.js';
 import { readManifest } from './lib/manifest.js';
+import { SubsystemsError, refreshSubsystems, subsystemsManifestPath } from './lib/subsystems.js';
 import { promptConfirm, promptTarget } from './lib/prompts.js';
 import { collectGovernance, renderSummary } from './lib/summary.js';
 import { DEFAULT_TARGET, TARGET_NAMES } from './lib/targets.js';
-import { packageVersion } from './lib/version.js';
+import { packageVersion, rigHandshake } from './lib/version.js';
+import { runMemory } from './commands/memory.js';
 const USAGE = `Usage: create-agent-rig <dir> [options]
 
 Scaffolds a new project into <dir>: a Claude Code + Codex agent operating system
@@ -20,7 +23,8 @@ Options
                     required when not a terminal — default: ${DEFAULT_TARGET})
   --no-git          skip git init + the pristine-template baseline commit
   --no-color        plain output (NO_COLOR is respected too)
-  --version         print the version
+  --version         print the version (--version --json: the contract handshake,
+                    one JSON object with the name, version and contract version)
   -h, --help        this text
 
 Also: create-agent-rig init [--dry-run]
@@ -32,7 +36,70 @@ Also: create-agent-rig init [--dry-run]
 
 Also: create-agent-rig upgrade [--dry-run] [--yes]
   Bring the rig in the CURRENT repo up to this version. Replaces the files it
-  installed and you did not touch; everything else is reported, never merged.`;
+  installed and you did not touch; everything else is reported, never merged.
+  Re-runs the subsystem manifest derivation when one exists (see setup).
+
+Also: create-agent-rig setup --memory-root <checkout> [--memory-ref <sha>] [--dry-run]
+  Record the Memory executable in this machine's subsystem manifest
+  (~/.config/create-agent-rig/subsystems.json; %APPDATA% on Windows) from the
+  one declared root. Performs the --version --json handshake first and refuses
+  a foreign contract major with exit 4 before writing anything.
+
+Also: create-agent-rig memory <doctor|load> [args…]
+  Run a Memory verb through the registered executable: the --version --json
+  handshake first (a foreign contract major exits 4 and the verb never runs),
+  then the verb and its arguments, Memory's answer passed through unchanged.
+  Your arguments go to Memory as written; a load that names no --timeout-ms
+  gets --timeout-ms 45000 appended (Memory's own deadline, kept under the rig's
+  60 s bound). No manifest answers unsupported/absent (exit 0); an invalid
+  invocation exits 2.`;
+async function runSetup(rawArgs) {
+    let values;
+    try {
+        ({ values } = parseArgs({
+            args: rawArgs,
+            options: {
+                'memory-root': { type: 'string' },
+                'memory-ref': { type: 'string' },
+                'dry-run': { type: 'boolean' },
+                'no-color': { type: 'boolean' },
+            },
+            allowPositionals: false,
+        }));
+    }
+    catch (error) {
+        process.stderr.write(`${error.message}\n\n${USAGE}\n`);
+        return 1;
+    }
+    const memoryRoot = values['memory-root'];
+    if (memoryRoot === undefined) {
+        process.stderr.write(`setup needs --memory-root <checkout>\n\n${USAGE}\n`);
+        return 1;
+    }
+    try {
+        const result = await setupSubsystems({
+            memoryRoot,
+            memoryRef: values['memory-ref'] ?? null,
+            dryRun: values['dry-run'] === true,
+        });
+        if (result.outcome === 'refused') {
+            process.stderr.write(`Memory handshake: ${JSON.stringify(result.handshake)}\n`);
+            return result.exitCode;
+        }
+        process.stdout.write(`Memory handshake: ${JSON.stringify(result.handshake)}\n` +
+            (result.outcome === 'dry-run'
+                ? `Dry run — nothing written (would write ${result.file}).\n`
+                : `Wrote ${result.file}\n`));
+        return 0;
+    }
+    catch (error) {
+        if (error instanceof SubsystemsError) {
+            process.stderr.write(`setup: ${error.message} (${error.code})\n`);
+            return 1;
+        }
+        throw error;
+    }
+}
 async function runInit(rawArgs) {
     let values;
     try {
@@ -219,15 +286,48 @@ async function runUpgrade(rawArgs) {
     }
     const result = await applyUpgrade(cwd, plan);
     process.stdout.write(`\nWrote ${result.written.length} files.\n`);
+    // The subsystem manifest is machine-scoped and written by `setup`; an
+    // upgrade re-runs the same derivation so `installedVersion` follows the
+    // executable the root now holds. It is never part of the rig manifest or of
+    // `result.written` — that file list is the repository's, this one is the
+    // user's. Absent stays absent: creating it is `setup`'s act.
+    try {
+        const refreshed = await refreshSubsystems({
+            file: subsystemsManifestPath(process.env, process.platform),
+            run: execFileRunner,
+            nodeExecutable: process.execPath,
+            platform: process.platform,
+        });
+        if (refreshed !== 'absent')
+            process.stdout.write(`Subsystem manifest: ${typeof refreshed === 'string' ? refreshed : JSON.stringify(refreshed)}\n`);
+    }
+    catch (error) {
+        if (!(error instanceof SubsystemsError))
+            throw error;
+        process.stdout.write(`Subsystem manifest: not refreshed — ${error.message} (${error.code})\n`);
+    }
     return 0;
 }
 async function main() {
     if (process.argv[2] === 'init') {
         return runInit(process.argv.slice(3));
     }
+    if (process.argv[2] === 'setup') {
+        return runSetup(process.argv.slice(3));
+    }
     if (process.argv[2] === 'upgrade') {
         return runUpgrade(process.argv.slice(3));
     }
+    if (process.argv[2] === 'memory') {
+        // The consumer path of the RP-19 handshake: manifest → `--version --json`
+        // → exit 4 on a foreign major → doctor/load passed through (`load` gains a
+        // default `--timeout-ms` when the caller names none — commands/memory.ts).
+        const [verb = '', ...args] = process.argv.slice(3);
+        const result = await runMemory({ verb, args });
+        process.stdout.write(result.stdout);
+        process.stderr.write(result.stderr);
+        return result.exitCode;
+    }
     let positionals;
     let values;
     try {
@@ -237,6 +337,9 @@ async function main() {
                 help: { type: 'boolean', short: 'h' },
                 target: { type: 'string' },
                 version: { type: 'boolean' },
+                // `--json` is read on `--version` alone: the handshake object of
+                // docs/command-contract.md, one JSON line and nothing else on stdout.
+                json: { type: 'boolean' },
                 'no-git': { type: 'boolean' },
                 'no-color': { type: 'boolean' },
             },
@@ -248,6 +351,10 @@ async function main() {
         return 1;
     }
     if (values.version) {
+        if (values.json) {
+            process.stdout.write(`${JSON.stringify(await rigHandshake())}\n`);
+            return 0;
+        }
         process.stdout.write(`${await packageVersion()}\n`);
         return 0;
     }

package/packages/cli/dist/lib/manifest.js

@@ -91,20 +91,38 @@ export function parseManifest(raw) {
         return null;
     if (!isStringRecord(m.files))
         return null;
+    // Present in a shape this reader does not accept voids the manifest, exactly
+    // as `files` does; absent is every manifest written before the field existed.
+    if (m.kept !== undefined && !isStringRecord(m.kept))
+        return null;
     return {
         version: m.version,
         kind: m.kind,
         project: { name: project.name, scope: project.scope, region: project.region },
         stacks: [...m.stacks],
         files: { ...m.files },
+        ...(m.kept !== undefined ? { kept: { ...m.kept } } : {}),
     };
 }
-/** Stable bytes: sorted paths, so a re-run produces no diff of its own. */
+const sortedRecord = (record) => {
+    const sorted = {};
+    for (const rel of Object.keys(record).sort())
+        sorted[rel] = record[rel];
+    return sorted;
+};
+/**
+ * Stable bytes: sorted paths, so a re-run produces no diff of its own. An
+ * empty `kept` is omitted, not written as `{}` — a manifest that kept nothing
+ * must serialise byte-identical to one written before the key existed.
+ */
 export function serializeManifest(manifest) {
-    const files = {};
-    for (const rel of Object.keys(manifest.files).sort())
-        files[rel] = manifest.files[rel];
-    return `${JSON.stringify({ ...manifest, files }, null, 2)}\n`;
+    const { kept, ...rest } = manifest;
+    const body = {
+        ...rest,
+        files: sortedRecord(manifest.files),
+        ...(kept !== undefined && Object.keys(kept).length > 0 ? { kept: sortedRecord(kept) } : {}),
+    };
+    return `${JSON.stringify(body, null, 2)}\n`;
 }
 export async function readManifest(repoDir) {
     try {

package/packages/cli/dist/lib/subsystems.js

@@ -0,0 +1,269 @@
+// The machine-scoped subsystem manifest (ADR-RP-002 R6, RP-147): installation
+// metadata, not a service registry. One writer (`setup`; `upgrade` re-runs the
+// same derivation), one scope (the user's configuration root), one entry per
+// subsystem carrying the resolved executable invocation and the contract major
+// it must answer. No search path, no fallback chain, no PATH scan: the
+// executable is derived from the one root the owner declared, and every
+// substantive call performs the `--version --json` handshake first.
+//
+// Handshake results carry no path — a status is machine JSON a consumer may
+// print, and the manifest itself is the only place a location is written.
+import { statSync } from 'node:fs';
+import { mkdir, readFile, rename, rm, writeFile } from 'node:fs/promises';
+import { randomBytes } from 'node:crypto';
+import path from 'node:path';
+export const SUBSYSTEMS_SCHEMA_VERSION = 1;
+export const MEMORY_CONTRACT_MAJOR = 1;
+const MEMORY_EXECUTABLE_REL = ['shared-memory', 'memory.mjs'];
+const HANDSHAKE_TIMEOUT_MS = 15_000;
+export class SubsystemsError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = 'SubsystemsError';
+        this.code = code;
+    }
+}
+/**
+ * Exactly one location per platform. An unset root is refused, not guessed:
+ * a manifest written under a guessed home is a manifest nothing else reads.
+ */
+export function subsystemsManifestPath(env, platform) {
+    if (platform === 'win32') {
+        const root = env.APPDATA;
+        if (!root)
+            throw new SubsystemsError('config-root-unavailable', 'APPDATA is not set');
+        return path.join(root, 'create-agent-rig', 'subsystems.json');
+    }
+    const home = env.HOME;
+    if (!home)
+        throw new SubsystemsError('config-root-unavailable', 'HOME is not set');
+    return path.join(home, '.config', 'create-agent-rig', 'subsystems.json');
+}
+/** The path module of the DECLARED platform, so an entry's encoding is pinned by the platform argument, not by the host. */
+const pathFor = (platform) => (platform === 'win32' ? path.win32 : path.posix);
+export function memoryExecutablePath(memoryRoot, platform) {
+    return pathFor(platform).join(memoryRoot, ...MEMORY_EXECUTABLE_REL);
+}
+/**
+ * The pure half of the derivation: root → invocation, in the declared
+ * platform's encoding. The root is the single declared input
+ * (`setup --memory-root`), so it must be absolute under that platform — a
+ * relative root would make the entry mean a different executable from every
+ * working directory. No filesystem here, so both encodings are pinned by tests
+ * on any host.
+ */
+export function memoryInvocation(input, platform) {
+    if (!pathFor(platform).isAbsolute(input.memoryRoot))
+        throw new SubsystemsError('memory-root-relative', 'the Memory root must be an absolute path');
+    return [input.nodeExecutable, memoryExecutablePath(input.memoryRoot, platform)];
+}
+function isFile(file) {
+    try {
+        return statSync(file).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * The whole derivation: the invocation above, plus the check that the
+ * executable is already there on this host — the manifest records what
+ * exists, it does not promise what an install will bring. So `platform` is
+ * the host's here; the pure half is what a foreign platform's encoding is
+ * tested through.
+ */
+export function deriveMemoryEntry(input, platform) {
+    const invocation = memoryInvocation(input, platform);
+    if (!isFile(invocation[1]))
+        throw new SubsystemsError('memory-executable-absent', `no ${MEMORY_EXECUTABLE_REL.join('/')} under the declared Memory root`);
+    return {
+        memoryRoot: input.memoryRoot,
+        invocation,
+        contractMajor: MEMORY_CONTRACT_MAJOR,
+        memoryRef: input.memoryRef,
+        installedVersion: input.installedVersion,
+    };
+}
+const majorOf = (contractVersion) => {
+    const match = /^(\d+)\.\d+$/.exec(contractVersion);
+    return match ? Number(match[1]) : null;
+};
+/**
+ * `--version --json` and its classification. The consumer compares the
+ * contract major alone; a foreign major is the consumer's refusal (exit 4 in
+ * `setup`), never something Memory emits. A failure payload is
+ * INTEGRATION-FAILED, never absence: the executable answered.
+ */
+export async function handshake(entry, run, options = {}) {
+    const [file, script] = entry.invocation;
+    // Absence is the runner's answer (ENOENT), not a pre-check: the executable
+    // the manifest names is exactly what this call must exercise.
+    const result = await run(file, [script, '--version', '--json'], {
+        timeoutMs: options.timeoutMs ?? HANDSHAKE_TIMEOUT_MS,
+    });
+    if (result.spawnError) {
+        if (result.spawnError.code === 'ENOENT')
+            return { status: 'unsupported', reason: 'absent' };
+        return { status: 'integration-failed', reason: 'invalid-payload' };
+    }
+    let payload;
+    try {
+        payload = JSON.parse(result.stdout);
+    }
+    catch {
+        return { status: 'integration-failed', reason: 'invalid-payload' };
+    }
+    if (typeof payload !== 'object' || payload === null)
+        return { status: 'integration-failed', reason: 'invalid-payload' };
+    const record = payload;
+    // The executable answered, and answered a failure — a broken VERSION file is
+    // the Memory-side shape (RP-19). The manifest's promise about what is
+    // installed no longer holds, so this is `manifest-stale`, never absence.
+    if (result.code !== 0 || record.result === 'integration-failed')
+        return { status: 'integration-failed', reason: 'manifest-stale' };
+    const { name, version, contractVersion } = record;
+    if (typeof version !== 'string' || typeof contractVersion !== 'string')
+        return { status: 'integration-failed', reason: 'invalid-payload' };
+    if (name !== 'memory')
+        return { status: 'integration-failed', reason: 'manifest-stale' };
+    const major = majorOf(contractVersion);
+    if (major === null)
+        return { status: 'integration-failed', reason: 'manifest-stale' };
+    if (major !== MEMORY_CONTRACT_MAJOR)
+        return { status: 'foreign-major', contractVersion, requiredMajor: MEMORY_CONTRACT_MAJOR };
+    return { status: 'ok', version, contractVersion };
+}
+/** Stable bytes: fixed key order, two-space indent, trailing newline. */
+export function serializeSubsystemsManifest(manifest) {
+    const memory = manifest.entries.memory;
+    const ordered = {
+        schemaVersion: SUBSYSTEMS_SCHEMA_VERSION,
+        entries: {
+            memory: {
+                memoryRoot: memory.memoryRoot,
+                invocation: [memory.invocation[0], memory.invocation[1]],
+                contractMajor: MEMORY_CONTRACT_MAJOR,
+                memoryRef: memory.memoryRef,
+                installedVersion: memory.installedVersion,
+            },
+        },
+    };
+    return `${JSON.stringify(ordered, null, 2)}\n`;
+}
+const isString = (value) => typeof value === 'string';
+export function parseSubsystemsManifest(text) {
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+    if (typeof parsed !== 'object' || parsed === null)
+        return null;
+    const root = parsed;
+    if (root.schemaVersion !== SUBSYSTEMS_SCHEMA_VERSION)
+        return null;
+    const entries = root.entries;
+    if (typeof entries !== 'object' || entries === null)
+        return null;
+    const memory = entries.memory;
+    if (typeof memory !== 'object' || memory === null)
+        return null;
+    const m = memory;
+    const invocation = m.invocation;
+    if (!isString(m.memoryRoot) ||
+        !Array.isArray(invocation) ||
+        invocation.length !== 2 ||
+        !invocation.every(isString) ||
+        m.contractMajor !== MEMORY_CONTRACT_MAJOR ||
+        !(m.memoryRef === null || isString(m.memoryRef)) ||
+        !isString(m.installedVersion))
+        return null;
+    return {
+        schemaVersion: SUBSYSTEMS_SCHEMA_VERSION,
+        entries: {
+            memory: {
+                memoryRoot: m.memoryRoot,
+                // `every(isString)` above proved both elements are strings, but
+                // Array.prototype.every does not narrow a tuple's element type.
+                invocation: [invocation[0], invocation[1]],
+                contractMajor: MEMORY_CONTRACT_MAJOR,
+                // Checked above as `null` or a string; the `||` chain does not narrow `m.memoryRef`.
+                memoryRef: m.memoryRef,
+                installedVersion: m.installedVersion,
+            },
+        },
+    };
+}
+/** `null` when absent — no evidence; a present file that does not parse is an error, not silence. */
+export async function readSubsystemsManifest(file) {
+    let text;
+    try {
+        text = await readFile(file, 'utf8');
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return null;
+        throw new SubsystemsError('manifest-unreadable', `cannot read ${path.basename(file)}`);
+    }
+    const manifest = parseSubsystemsManifest(text);
+    if (manifest === null)
+        throw new SubsystemsError('manifest-unreadable', `${path.basename(file)} is not a schemaVersion ${SUBSYSTEMS_SCHEMA_VERSION} subsystem manifest`);
+    return manifest;
+}
+/**
+ * Atomic and idempotent: the bytes land in a sibling temp file and are renamed
+ * over the target, so a reader never sees a torn manifest and a re-run of the
+ * same derivation produces no diff of its own.
+ */
+export async function writeSubsystemsManifest(file, manifest) {
+    const dir = path.dirname(file);
+    await mkdir(dir, { recursive: true });
+    const temp = path.join(dir, `.${path.basename(file)}.tmp-${process.pid}-${randomBytes(4).toString('hex')}`);
+    try {
+        await writeFile(temp, serializeSubsystemsManifest(manifest));
+        await rename(temp, file);
+    }
+    catch (error) {
+        // See packages/cli/test/subsystems.test.ts › "removes its temp file and
+        // rethrows when the rename is refused".
+        await rm(temp, { force: true });
+        throw error;
+    }
+}
+/**
+ * What `upgrade` re-runs: the same derivation from the recorded root, the same
+ * handshake, and a rewrite only when the handshake is ok. A manifest that is
+ * absent is left absent (`setup` is the one writer that creates it); one whose
+ * executable no longer answers is left untouched and the result says why.
+ */
+export async function refreshSubsystems(options) {
+    const manifest = await readSubsystemsManifest(options.file);
+    if (manifest === null)
+        return 'absent';
+    const previous = manifest.entries.memory;
+    let entry;
+    try {
+        entry = deriveMemoryEntry({
+            memoryRoot: previous.memoryRoot,
+            nodeExecutable: options.nodeExecutable,
+            memoryRef: previous.memoryRef,
+            installedVersion: previous.installedVersion,
+        }, options.platform);
+    }
+    catch (error) {
+        if (error instanceof SubsystemsError && error.code === 'memory-executable-absent')
+            return { status: 'unsupported', reason: 'absent' };
+        throw error;
+    }
+    const result = await handshake(entry, options.run);
+    if (result.status !== 'ok')
+        return result;
+    await writeSubsystemsManifest(options.file, {
+        schemaVersion: SUBSYSTEMS_SCHEMA_VERSION,
+        entries: { memory: { ...entry, installedVersion: result.version } },
+    });
+    return 'refreshed';
+}

package/packages/cli/dist/lib/version.js

@@ -13,3 +13,18 @@ export async function packageVersion() {
     const pkg = JSON.parse(await readFile(pkgPath, 'utf8'));
     return pkg.version;
 }
+/**
+ * The version of the command contract (`docs/command-contract.md`) this rig
+ * implements. Independent of the package version: many releases ship against
+ * one contract, and a consumer compares this field's major alone.
+ */
+export const RIG_CONTRACT_VERSION = '1.0';
+/** What `--version --json` answers — the handshake object of the contract. */
+export async function rigHandshake() {
+    return {
+        schemaVersion: 1,
+        name: 'create-agent-rig',
+        version: await packageVersion(),
+        contractVersion: RIG_CONTRACT_VERSION,
+    };
+}