create-agent-rig 0.3.2 → 0.4.0

package/packages/cli/dist/index.js

@@ -1,14 +1,13 @@
 #!/usr/bin/env node
-import { readFile } from 'node:fs/promises';
-import path from 'node:path';
-import { fileURLToPath } from 'node:url';
 import { parseArgs } from 'node:util';
 import { CreateError, createProject } from './commands/create.js';
 import { InitError, initFileContents, initProject, planInit } from './commands/init.js';
+import { UpgradeError, applyUpgrade, planUpgrade } from './commands/upgrade.js';
 import { makePalette } from './lib/colors.js';
-import { promptTarget } from './lib/prompts.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';
 const USAGE = `Usage: create-agent-rig <dir> [options]
 
 Scaffolds a new project into <dir>: agent operating system (.claude/, CLAUDE.md)
@@ -25,14 +24,11 @@ Options
 
 Also: create-agent-rig init [--dry-run] [--force]
   Install the process layer (rules, gates, stop rules — no architecture
-  assumptions) into the CURRENT existing repo. Refuses to clobber CLAUDE.md.`;
-async function packageVersion() {
-    // dist/index.js lives three levels under the package root — same walk as
-    // the templates resolver, valid in the repo and in the published package.
-    const pkgPath = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..', '..', 'package.json');
-    const pkg = JSON.parse(await readFile(pkgPath, 'utf8'));
-    return pkg.version;
-}
+  assumptions) into the CURRENT existing repo. Refuses to clobber CLAUDE.md.
+
+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.`;
 async function runInit(rawArgs) {
     let values;
     try {
@@ -77,10 +73,99 @@ async function runInit(rawArgs) {
     }
     return 0;
 }
+const MARK = {
+    update: '~',
+    new: '+',
+    conflict: '!',
+    deleted: '-',
+    wiring: '!',
+    unchanged: '·',
+};
+function renderUpgradePlan(repoDir, plan) {
+    const of = (verdict) => plan.actions.filter((a) => a.verdict === verdict);
+    const lines = [
+        `agent-rig upgrade — ${plan.kind} rig in ${repoDir}`,
+        plan.bootstrapped
+            ? `  no manifest here (a pre-0.4.0 rig) — matching files against released versions`
+            : `  installed by ${plan.fromVersion}`,
+        `  upgrading to ${plan.toVersion}`,
+        '',
+    ];
+    for (const verdict of ['update', 'new', 'deleted', 'conflict', 'wiring']) {
+        for (const action of of(verdict)) {
+            lines.push(`  ${MARK[verdict]} ${action.rel}` + (action.reason ? `  — ${action.reason}` : ''));
+            // A conflict is only useful if the new version can be diffed by hand.
+            if (verdict === 'conflict' && action.templatePath) {
+                lines.push(`      new version: ${action.templatePath}`);
+            }
+        }
+    }
+    const unchanged = of('unchanged').length;
+    lines.push('', `  ${of('update').length} to replace, ${of('new').length} new, ` +
+        `${of('conflict').length} yours (kept), ${unchanged} already current`);
+    return `${lines.join('\n')}\n`;
+}
+async function runUpgrade(rawArgs) {
+    let values;
+    try {
+        ({ values } = parseArgs({
+            args: rawArgs,
+            options: { 'dry-run': { type: 'boolean' }, yes: { type: 'boolean' } },
+            allowPositionals: false,
+        }));
+    }
+    catch (error) {
+        process.stderr.write(`${error.message}\n\n${USAGE}\n`);
+        return 1;
+    }
+    const cwd = process.cwd();
+    const plan = await planUpgrade(cwd);
+    process.stdout.write(renderUpgradePlan(cwd, plan));
+    // The one thing this command will not do for you — printed with the plan,
+    // because the dry run is where a reader decides whether there is work here,
+    // and a report that mentions entries it never shows is not a plan.
+    if (plan.wiring !== null) {
+        process.stdout.write(`\n!  .claude/settings.json is never replaced — it is where your own hooks live.\n` +
+            `   This version wires them like this; merge in what is missing:\n\n` +
+            plan.wiring.replace(/^/gm, '   ') +
+            '\n');
+    }
+    if (values['dry-run'] === true) {
+        process.stdout.write('\nDry run — nothing written.\n');
+        return 0;
+    }
+    // The plan above is the review step, so it has to be answered before
+    // anything is written. On a terminal that is a question; off one it is the
+    // same refusal `create` makes without --target — never guess for a run that
+    // cannot be asked, least of all when the answer rewrites its repository.
+    const isInteractive = Boolean(process.stdin.isTTY && process.stderr.isTTY);
+    if (values.yes !== true) {
+        if (!isInteractive) {
+            process.stderr.write('Refusing to rewrite files in a non-interactive run. ' +
+                'Re-run with --yes once the plan above is what you want (or --dry-run to keep looking).\n');
+            return 1;
+        }
+        const confirmed = await promptConfirm('\nApply this plan?', {
+            input: process.stdin,
+            output: process.stderr,
+            isInteractive,
+        });
+        if (!confirmed) {
+            process.stdout.write('Nothing written.\n');
+            return 0;
+        }
+    }
+    const result = await applyUpgrade(cwd, plan);
+    process.stdout.write(`\nWrote ${result.written.length} files.\n`);
+    return 0;
+}
 async function main() {
     if (process.argv[2] === 'init') {
         return runInit(process.argv.slice(3));
     }
+    if (process.argv[2] === 'upgrade') {
+        return runUpgrade(process.argv.slice(3));
+    }
     let positionals;
     let values;
     try {
@@ -144,7 +229,9 @@ main()
     process.exitCode = code;
 })
     .catch((error) => {
-    if (error instanceof CreateError || error instanceof InitError) {
+    if (error instanceof CreateError ||
+        error instanceof InitError ||
+        error instanceof UpgradeError) {
         process.stderr.write(`${error.message}\n`);
     }
     else {

package/packages/cli/dist/lib/copy-tree.js

@@ -34,6 +34,14 @@ export async function copyTree(srcDir, destDir, options = {}) {
  * composition for collisions before anything is copied.
  */
 export async function listTree(srcDir, options = {}) {
+    return (await listTreeEntries(srcDir, options)).map((entry) => entry.rel);
+}
+/**
+ * {@link listTree} with the source path kept alongside each destination — what
+ * an upgrade needs to read the new version of a file, and to name where it
+ * lives when it must not write it.
+ */
+export async function listTreeEntries(srcDir, options = {}) {
     const ignore = new Set(options.ignore ?? DEFAULT_IGNORE);
     const files = [];
     const walk = async (dir, relDir) => {
@@ -47,7 +55,7 @@ export async function listTree(srcDir, options = {}) {
                 await walk(path.join(dir, entry.name), relPath);
             }
             else if (entry.isFile()) {
-                files.push(relPath);
+                files.push({ rel: relPath, source: path.join(dir, entry.name) });
             }
         }
     };

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

@@ -0,0 +1,49 @@
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { templatesRoot } from '../templates.js';
+export const EMPTY_HISTORY = { versions: [], files: {} };
+/**
+ * Whether every release this table knows about carried this path.
+ *
+ * It is the one question that lets a manifest-less rig keep a **deletion**: if
+ * the file shipped in every version the rig could possibly be, then it is gone
+ * because somebody removed it — not because the rig predates it. A path added
+ * later is genuinely new to an older rig and must still be delivered.
+ */
+export function presentInEveryRelease(history, rel) {
+    const oldest = history.versions[0];
+    const entry = history.files[rel];
+    return oldest !== undefined && entry !== undefined && entry.since === oldest;
+}
+export function historyPath() {
+    return path.join(templatesRoot(), 'hash-history.json');
+}
+/**
+ * Fails open to an empty table: a missing or corrupt history means "nothing is
+ * recognised", which downgrades files to conflicts. That is the safe
+ * direction — the unsafe one is claiming a file is untouched when it is not.
+ */
+export async function loadHashHistory() {
+    let parsed;
+    try {
+        parsed = JSON.parse(await readFile(historyPath(), 'utf8'));
+    }
+    catch {
+        return EMPTY_HISTORY;
+    }
+    if (typeof parsed !== 'object' || parsed === null)
+        return EMPTY_HISTORY;
+    const { versions, files } = parsed;
+    if (!Array.isArray(versions) || typeof files !== 'object' || files === null)
+        return EMPTY_HISTORY;
+    const clean = {};
+    for (const [rel, entry] of Object.entries(files)) {
+        const { since, hashes } = (entry ?? {});
+        if (typeof since !== 'string')
+            continue;
+        if (!Array.isArray(hashes) || hashes.some((h) => typeof h !== 'string'))
+            continue;
+        clean[rel] = { since, hashes };
+    }
+    return { versions: versions.filter((v) => typeof v === 'string'), files: clean };
+}

package/packages/cli/dist/lib/install-set.js

@@ -0,0 +1,46 @@
+import { readFile } from 'node:fs/promises';
+import { listTreeEntries } from './copy-tree.js';
+import { substituteContent, substituteFileName } from './substitute.js';
+import { agentOsStackDir, agentOsUniversalDir } from '../templates.js';
+/**
+ * The agent-os layers of a target, in composition order. One definition, read
+ * by `create` when it copies them and by `upgrade` when it refreshes them —
+ * two lists would drift, and the one nobody looks at would be the wrong one.
+ */
+export function agentOsLayerDirs(stacks) {
+    return [
+        { name: 'agent-os/universal', dir: agentOsUniversalDir() },
+        ...stacks.map((stack) => ({ name: `agent-os/stack/${stack}`, dir: agentOsStackDir(stack) })),
+    ];
+}
+/**
+ * Exactly the agent-os bytes `create` writes, for a given target and project.
+ *
+ * The skeleton is deliberately absent: after generation the code is the user's
+ * project, not the rig's — `upgrade` refreshes the process layer and nothing
+ * else. Layers claim disjoint paths (`composition.ts` refuses otherwise), so
+ * this is a plain concatenation.
+ *
+ * 🔴 Two assumptions, both load-bearing and both true today: the layer is all
+ * **text** (this reads every file as UTF-8; a template test pins it for the
+ * process half) and none of it is **executable** (`upgrade` writes with a bare
+ * `writeFile` and does not carry the mode across the way `copyTree` does —
+ * nothing in `templates/agent-os` currently has a mode to carry). Adding the
+ * first binary asset or executable script here means teaching both.
+ */
+export async function agentOsInstallSet(stacks, ctx) {
+    const files = [];
+    for (const layer of agentOsLayerDirs(stacks)) {
+        const entries = await listTreeEntries(layer.dir, {
+            transformName: (name) => substituteFileName(name, ctx),
+        });
+        for (const entry of entries) {
+            files.push({
+                rel: entry.rel,
+                source: entry.source,
+                content: substituteContent(await readFile(entry.source, 'utf8'), ctx),
+            });
+        }
+    }
+    return files;
+}

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

@@ -0,0 +1,99 @@
+import { createHash } from 'node:crypto';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { isSafeSegment } from './safe-path.js';
+/**
+ * The install manifest: what this rig installed, at which version, and the
+ * hash each file had when it was written.
+ *
+ * It exists to answer the one hard question an upgrade has — *did the user
+ * edit this file?* — with evidence instead of a guess. It is **evidence, not a
+ * command**: a file the manifest names but the disk no longer has is reported,
+ * never silently restored.
+ *
+ * It is meant to be committed. Without it in the repository, an upgrade run on
+ * CI or on a colleague's machine is blind and falls back to the hash history.
+ */
+export const MANIFEST_REL = '.claude/.rig-manifest.json';
+export function sha256(data) {
+    return createHash('sha256').update(data).digest('hex');
+}
+function isStringRecord(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        !Array.isArray(value) &&
+        Object.values(value).every((v) => typeof v === 'string'));
+}
+/**
+ * A manifest, or `null` when there is nothing trustworthy to read.
+ *
+ * The distinction matters: `null` means "no evidence", which sends the upgrade
+ * to the hash history. A half-parsed manifest treated as an empty one would
+ * claim every file on disk belongs to the user, and upgrade nothing at all.
+ */
+export function parseManifest(raw) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed))
+        return null;
+    const m = parsed;
+    if (typeof m.version !== 'string')
+        return null;
+    if (m.kind !== 'create' && m.kind !== 'init')
+        return null;
+    const project = m.project;
+    if (typeof project !== 'object' ||
+        project === null ||
+        typeof project.name !== 'string' ||
+        typeof project.scope !== 'string' ||
+        typeof project.region !== 'string') {
+        return null;
+    }
+    // Values, not just types. These are substituted into file names and joined
+    // into paths, and this file is committed — it reaches a maintainer's disk
+    // through a pull request. A name of `../..` would send every write out of
+    // the repository, so an unsafe value invalidates the whole manifest rather
+    // than being quietly corrected into something plausible.
+    if (!isSafeSegment(project.name) || !isSafeSegment(project.scope))
+        return null;
+    if (project.region !== '' && !isSafeSegment(project.region))
+        return null;
+    if (!Array.isArray(m.stacks) || m.stacks.some((s) => typeof s !== 'string'))
+        return null;
+    if (m.stacks.some((s) => !isSafeSegment(s)))
+        return null;
+    if (!isStringRecord(m.files))
+        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 },
+    };
+}
+/** Stable bytes: sorted paths, so a re-run produces no diff of its own. */
+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`;
+}
+export async function readManifest(repoDir) {
+    try {
+        return parseManifest(await readFile(path.join(repoDir, ...MANIFEST_REL.split('/')), 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+export async function writeManifest(repoDir, manifest) {
+    const dest = path.join(repoDir, ...MANIFEST_REL.split('/'));
+    await mkdir(path.dirname(dest), { recursive: true });
+    await writeFile(dest, serializeManifest(manifest));
+}

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

@@ -1,4 +1,24 @@
 import { createInterface } from 'node:readline';
+/**
+ * A yes/no gate before something irreversible. **The default is no**, and a
+ * non-interactive caller gets `false` without being asked — the same rule the
+ * rest of this CLI follows: never guess for a run that cannot answer.
+ *
+ * Unlike the target prompt, an unrecognised answer is *not* forgiving: the
+ * question is asked before rewriting files in somebody's repository, and "I
+ * did not understand you" must not resolve to "go ahead".
+ */
+export function promptConfirm(question, streams) {
+    if (!streams.isInteractive)
+        return Promise.resolve(false);
+    const rl = createInterface({ input: streams.input, output: streams.output });
+    return new Promise((resolve) => {
+        rl.question(`${question} [y/N] `, (answer) => {
+            rl.close();
+            resolve(/^y(es)?$/i.test(answer.trim()));
+        });
+    });
+}
 /**
  * Pick a target interactively: by number, by name, or Enter for the default.
  * Anything unrecognised falls back to the default — generation should never

package/packages/cli/dist/lib/safe-path.js

@@ -0,0 +1,41 @@
+import path from 'node:path';
+/**
+ * Path safety for values that came from **outside the CLI** — the install
+ * manifest is committed to a repository, so it arrives in pull requests like
+ * any other file, and its values are substituted into paths.
+ *
+ * One module owns both halves so they cannot disagree: what may become a path
+ * segment, and where a resolved path is allowed to land.
+ */
+/** A value that can be substituted into a path without steering it. */
+export function isSafeSegment(value) {
+    return (value !== '' &&
+        value !== '.' &&
+        value !== '..' &&
+        !value.includes('/') &&
+        !value.includes('\\') &&
+        !value.includes('\0'));
+}
+/**
+ * `rel` resolved under `root`, or `null` when it would land anywhere else —
+ * including an absolute path, an empty path, and the classic sibling
+ * (`/tmp/rig` must not contain `/tmp/rig-evil`).
+ *
+ * This is the containment behind every write an upgrade makes. It is deliberate
+ * belt-and-braces: the values that build `rel` are validated where they are
+ * parsed, and this refuses the write anyway.
+ */
+export function resolveInside(root, rel) {
+    if (rel === '' || path.isAbsolute(rel))
+        return null;
+    const segments = rel.split('/');
+    // Refused, not repaired: joining an absolute or `..`-bearing path onto the
+    // root would silently turn hostile input into a plausible-looking write.
+    if (segments.some((segment) => !isSafeSegment(segment)))
+        return null;
+    const base = path.resolve(root);
+    const dest = path.resolve(base, ...segments);
+    if (dest === base)
+        return null;
+    return dest.startsWith(base + path.sep) ? dest : null;
+}

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

@@ -5,6 +5,38 @@ export function substituteContent(content, ctx) {
         .replaceAll('__REGION__', ctx.region)
         .replaceAll('@app/', `@${ctx.projectScope}/`);
 }
+/**
+ * The inverse of {@link substituteContent}, used **only to recognise** an
+ * installed file as a released version of its template: the released bytes
+ * carry tokens, the installed bytes carry the project's own name, and without
+ * this every token-carrying file (the kill switch, the loop skill, `CLAUDE.md`)
+ * would be a permanent conflict on every rig.
+ *
+ * 🔴 Limits, and both of them fail in the safe direction — an unrecognised file
+ * is reported and left alone, never overwritten:
+ *
+ * - `__PROJECT_SCOPE__` is not reversed. It substitutes to the same string as
+ *   `__PROJECT_NAME__`, so the two are indistinguishable after the fact; the
+ *   agent-os layer (the only layer an upgrade touches) uses neither the scope
+ *   token nor `@app/` in prose, which a template test pins.
+ * - A template that contains the project's name as a *literal* reverses into a
+ *   token that was never there. That costs nothing on its own — recognition
+ *   offers the untouched bytes as a candidate too, and those still match. It
+ *   bites only on a file carrying **both** a token and the literal, which then
+ *   reads as a conflict for that one project.
+ */
+export function detokenizeContent(content, ctx) {
+    let out = content;
+    // scope first: reversing the name first would rewrite `@name/` into
+    // `@__PROJECT_NAME__/` and the scope form could never match afterwards
+    if (ctx.projectScope !== '')
+        out = out.replaceAll(`@${ctx.projectScope}/`, '@app/');
+    if (ctx.region !== '')
+        out = out.replaceAll(ctx.region, '__REGION__');
+    if (ctx.projectName !== '')
+        out = out.replaceAll(ctx.projectName, '__PROJECT_NAME__');
+    return out;
+}
 /**
  * Files that must exist in the generated project under a dotted name, but are
  * stored un-dotted in the template because `npm publish` strips the dotted

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

@@ -0,0 +1,15 @@
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { templatesRoot } from '../templates.js';
+/**
+ * The version of the rig doing the installing — stamped into every manifest
+ * and printed by `--version`.
+ *
+ * Resolved through {@link templatesRoot} so there is one walk from this file
+ * to the package root, valid in the repo, the tarball and a git install alike.
+ */
+export async function packageVersion() {
+    const pkgPath = path.join(templatesRoot(), '..', 'package.json');
+    const pkg = JSON.parse(await readFile(pkgPath, 'utf8'));
+    return pkg.version;
+}

package/templates/agent-os/universal/.claude/skills/loop/SKILL.md

@@ -303,8 +303,23 @@ three poisons the only channel by which this project learns.
   the very next query.
 - **Closing:** close it with the merged PR linked, immediately after the
   post-merge verdict — not in a cleanup pass.
-
-Between those two moments the item keeps absorbing what happens **as it happens** —
+- **Write-back:** with the close, record what it **unblocked** — the items that
+  were waiting on this one, by name. It is the journal's `unblocked` field, and
+  it is **required, not a step for when it applies**: an absent line and an
+  unpaid debt are the same observation from outside, so the empty case has to
+  be written to mean anything. Which empty case matters — "nothing was waiting"
+  is an answer, "this queue has no dependency links" is the absence of one
+  (§0), and a queue that cannot be asked must never be reported as asked.
+
+  🔴 It is a **report, not an edit to those items.** Blocked state is
+  re-resolved from the blocker itself on every selection (§2), so nothing is
+  stuck waiting to be corrected — and a label fixed by hand is evidence
+  destroyed, which §2 forbids by name. What the write-back buys is the thing no
+  query can answer: whether anyone **looked**. Where the close changed a fact
+  rather than a state — an Operator-queue item it settles — the paragraph
+  closing this section applies instead, and that edit lands in the same PR.
+
+Between the opening and the close the item keeps absorbing what happens **as it happens** —
 a decision, a deviation, a defect found in passing, a tier discovered mid-work. A
 run that dies mid-task leaves its whole trail on the item; a run that batches its
 comments to the end leaves nothing.

package/templates/agent-os/universal/PLAN.md

@@ -31,7 +31,8 @@ must not take its history with it.
 The fields exist so an entry can be visibly **incomplete**. A journal with no
 stated shape decays into a diary that reads fine and proves nothing.
 
-<!-- Template — copy the block, drop the fields that do not apply:
+<!-- Template — copy the block, drop the fields that do not apply (`unblocked` is
+     the exception: it is stated even when the answer is "nothing"):
 
 ### <one-line summary of the session>
 
@@ -41,8 +42,18 @@ stated shape decays into a diary that reads fine and proves nothing.
 - **reviewed** — changes that went through a reviewer gate, and what it returned
 - **stopped at** — which stop condition ended the session (or "checkpoint,
   still running")
-- **queue hygiene** — queue items fixed in passing: stale state, a dependency
-  that was already satisfied, an item that describes work already done
+- **unblocked** — what the session's closes released. **The field that is never
+  dropped** — a missing line and an unpaid debt read identically from outside,
+  and this is the only record of whether anyone looked. It has **three**
+  answers and they do not substitute for each other: the items that were
+  waiting, by name; "nothing was waiting", where the queue carries dependency
+  links and none pointed here; and "this queue has no dependency links", where
+  it cannot answer at all — a flat-list queue is **absent**, not satisfied, and
+  writing "nothing was waiting" there claims a look that no query could perform
+- **queue hygiene** — queue state the session found unreliable and **reported**:
+  a stale marker, a dependency already satisfied, an item that describes work
+  already done. Reported, never corrected in passing — quietly fixing the
+  metadata destroys the evidence that the metadata is unreliable
 - **cost** — the counts the session actually observed: reviewer subagents run,
   CI runs consumed (re-runs included — the cheapest signal that a task fought
   its tests), deploys triggered