create-agent-rig 0.9.0 → 0.10.0

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

@@ -1,23 +1,60 @@
-import { access, mkdir, readFile, writeFile } from 'node:fs/promises';
+import { access, lstat, 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 { ALL_LAYERS, DEFAULT_LAYERS, MANIFEST_REL, readManifest, sha256, writeManifest, } from '../lib/manifest.js';
+import { resolveWritableInside } from '../lib/safe-path.js';
 import { substituteContent } from '../lib/substitute.js';
-import { agentOsInitDir, agentOsUniversalDir } from '../templates.js';
+import { 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';
+/**
+ * The layers this install writes, given what a previous run (if any)
+ * recorded and whether this run opted in.
+ *
+ * Never narrows what a previous run already installed: `--layer workflow` is
+ * additive, and a rig that already carries the workflow layer keeps it on a
+ * plain re-run with no flag (RP-180's "existing dogfood repositories can
+ * explicitly retain the layer" applies to `init` re-runs, not only to
+ * `upgrade`).
+ */
+function effectiveLayers(previous, withWorkflow) {
+    const wantsWorkflow = withWorkflow || (previous?.layers.includes('workflow') ?? false);
+    return wantsWorkflow ? [...ALL_LAYERS] : [...DEFAULT_LAYERS];
+}
 const SETTINGS = '.claude/settings.json';
 const CODEX_HOOKS = '.codex/hooks.json';
 const MAPS = ['CLAUDE.md', 'AGENTS.md'];
+/**
+ * Plain, static files this install always ships alongside the process layer,
+ * beside the two generated wiring files and the two maps above — neither
+ * architecture-specific (RP-177 retired that group entirely) nor subject to
+ * the maps' overwrite refusal, so they are appended here rather than folded
+ * into either list.
+ */
+const STATIC_EXTRAS = ['.codex/config.toml'];
 async function loadManifest() {
     const raw = await readFile(path.join(agentOsUniversalDir(), 'layers.json'), 'utf8');
     return JSON.parse(raw);
 }
+/**
+ * Exactly `layers.json`'s own array for one layer — never the always-added
+ * extras (`SETTINGS`, `CODEX_HOOKS`, `STATIC_EXTRAS`, `MAPS`) `initManifest`
+ * appends to every layer regardless of which one was asked for. A caller
+ * that wants to know whether a SPECIFIC layer's own files are on disk (RP-180
+ * round 3, `commands/upgrade.ts`'s `detectLayersOnDisk`) needs this
+ * distinction: those extras exist for any rig at all, Core-only included, so
+ * checking `initManifest([layer])`'s full output against disk would report
+ * every layer as "present" always.
+ */
+export async function layerOnlyPaths(layer) {
+    const manifest = await loadManifest();
+    return manifest[layer];
+}
 async function exists(p) {
     try {
         await access(p);
@@ -41,30 +78,25 @@ export function projectNameFor(repoDir) {
     return slug === '' ? 'project' : slug;
 }
 /**
- * `init` installs only the PROCESS layer (hooks-and-reach brief §3/§4): rules
- * that assume nothing about the codebase shape. Architecture rules reference
- * `packages/core` and friends — installing them into an arbitrary repo would
- * describe a structure that does not exist, which is worse than no rule.
- *
- * It also installs two things the process manifest does not name, because both
- * are meaningless in the generated shape and load-bearing here:
+ * `init` installs the PROCESS layer (hooks-and-reach brief §3/§4): rules that
+ * assume nothing about the codebase shape. Since RP-177 it is the ONLY
+ * flavour `create-agent-rig` ships — the architecture group (rules describing
+ * `packages/core` and friends) was retired outright, not merely excluded here,
+ * so there is no wider install for `create` to fall back to and no override
+ * layer left to shadow a universal file.
  *
- * - `CLAUDE.md` — the map, taken from the init override layer, which describes
- *   the rig this command installs rather than the generated monorepo;
- * - `.claude/settings.json` — the wiring, derived from the shipped settings so
- *   it names exactly the hooks that travelled.
+ * `.claude/settings.json` and `.codex/hooks.json` are generated rather than
+ * copied: derived from the shipped settings so they name exactly the hooks
+ * that travelled.
  */
-export async function initManifest() {
+export async function initManifest(layers = DEFAULT_LAYERS) {
     const manifest = await loadManifest();
     const universal = agentOsUniversalDir();
-    const override = agentOsInitDir();
-    const files = await mapConcurrent([...manifest.process, ...MAPS], 16, async (rel) => {
-        const overridden = path.join(override, rel);
-        return {
-            rel,
-            source: (await exists(overridden)) ? overridden : path.join(universal, rel),
-        };
-    });
+    const layerFiles = layers.flatMap((layer) => manifest[layer]);
+    const files = [...layerFiles, ...STATIC_EXTRAS, ...MAPS].map((rel) => ({
+        rel,
+        source: path.join(universal, rel),
+    }));
     files.push({ rel: SETTINGS, source: null });
     files.push({ rel: CODEX_HOOKS, source: null });
     return files;
@@ -78,14 +110,12 @@ export async function initManifest() {
  * `__PROJECT_NAME__` in `stop-flag.mjs` is a kill switch that silently never
  * fires.
  */
-export async function initFileContents(repoDir, project) {
+export async function initFileContents(repoDir, project, layers = DEFAULT_LAYERS) {
     const projectName = project?.name ?? projectNameFor(repoDir);
     const ctx = {
         projectName,
-        projectScope: project?.scope ?? projectName,
-        region: project?.region ?? '',
     };
-    const files = await initManifest();
+    const files = await initManifest(layers);
     const contents = new Map();
     const sourceFiles = files.filter((file) => file.source !== null);
     const rendered = await mapConcurrent(sourceFiles, 16, async ({ rel, source }) => ({
@@ -107,13 +137,15 @@ export async function initFileContents(repoDir, project) {
     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);
+export async function initInstallSet(repoDir, project, layers = DEFAULT_LAYERS) {
+    const files = await initManifest(layers);
+    const contents = await initFileContents(repoDir, project, layers);
     return files.map(({ rel, source }) => ({ rel, source, content: contents.get(rel) ?? '' }));
 }
-export async function planInit(repoDir) {
-    const files = (await initManifest()).map((f) => f.rel);
+export async function planInit(repoDir, options = {}) {
+    const previous = await readManifest(repoDir);
+    const layers = effectiveLayers(previous, options.withWorkflow === true);
+    const files = (await initManifest(layers)).map((f) => f.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 };
 }
@@ -123,28 +155,46 @@ export async function initProject(repoDir, options) {
     // 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);
     const previous = await readManifest(repoDir);
+    const layers = effectiveLayers(previous, options.withWorkflow === true);
+    const files = (await initManifest(layers)).map((f) => f.rel);
+    // Resolve the whole write set before the first edit. A lexical child can
+    // still escape through a symlink at the leaf or in any existing parent, and
+    // discovering that after another payload file was written would leave a
+    // partial install. The manifest is a write too, even on an otherwise-empty
+    // re-run, so it belongs in the same preflight.
+    const destinations = new Map();
+    for (const rel of [...files, MANIFEST_REL]) {
+        const dest = await resolveWritableInside(repoDir, rel);
+        if (dest === null) {
+            throw new InitError(`Refusing to write "${rel}" through a symlink or outside ${repoDir}.`);
+        }
+        destinations.set(rel, dest);
+    }
     // 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]) {
+        const dest = destinations.get(map);
+        if (dest !== undefined && (await exists(dest))) {
+            // A map this rig wrote and that still matches its manifest is safe to
+            // skip on an idempotent re-run. An unrecorded or edited map remains the
+            // user's guidance and is still refused.
+            if (previous?.files[map] !== undefined &&
+                sha256(await readFile(dest)) === previous.files[map]) {
                 continue;
             }
-            throw new InitError(`This repo already has an ${map}. Refusing to overwrite it. ` +
+            // "AGENTS.md" starts with a vowel SOUND ("a" said as a letter, /eɪ/);
+            // "CLAUDE.md" does not — so the article is picked per file rather than
+            // hardcoded to "an", which read as "an CLAUDE.md".
+            const article = /^[aeiou]/i.test(map) ? 'an' : 'a';
+            throw new InitError(`This repo already has ${article} ${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 contents = await initFileContents(repoDir, options.project, layers);
     const plannedCount = files.length;
     const actions = await mapConcurrent(files, 16, async (rel) => {
-        const dest = path.join(repoDir, rel);
+        const dest = destinations.get(rel);
         if (await exists(dest)) {
             // never overwrite a file init did not write (a user's own copy)
             return { rel, verdict: 'skipped' };
@@ -152,23 +202,51 @@ export async function initProject(repoDir, options) {
         if (options.dryRun)
             return { rel, verdict: 'planned' };
         await mkdir(path.dirname(dest), { recursive: true });
-        await writeFile(dest, contents.get(rel) ?? '');
+        const checked = await resolveWritableInside(repoDir, rel);
+        if (checked === null) {
+            throw new InitError(`Refusing to write "${rel}" through a symlink or outside ${repoDir}.`);
+        }
+        await writeFile(checked, contents.get(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);
+    if (!options.dryRun) {
+        await recordInstall(repoDir, written, skipped, contents, layers, options.project);
+    }
     return { written, skipped, plannedCount };
 }
+/**
+ * The text of a regular file, or `null` for anything else at that path — a
+ * directory, a symlink, a file this process cannot read. `kept` records only
+ * bytes that are the file itself: hashing through a link would put the hash of
+ * something outside the repository into a committed manifest, and a read that
+ * throws here would abort the install after every other file was written.
+ */
+async function readRegularFile(abs) {
+    try {
+        if (!(await lstat(abs)).isFile())
+            return null;
+        return await readFile(abs);
+    }
+    catch {
+        return null;
+    }
+}
 /**
  * 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.
+ * Only files actually **written** are recorded in `files`. A file `init` kept
+ * is somebody else's — claiming it there would let the next upgrade replace a
+ * user's own document with the rig's. It is recorded in `kept` instead, with
+ * the sha256 of the bytes found on disk (RP-182): not a claim of ownership, a
+ * record that the rig saw the file and left it — so the next upgrade can say
+ * "kept by init, unchanged since" or "edited since" rather than only "not a
+ * version this rig ever released". A path already in `files` is never moved to
+ * `kept` by a later run that skips it: the rig wrote those bytes. 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'`,
@@ -196,21 +274,40 @@ export async function initProject(repoDir, options) {
  * 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) {
+async function recordInstall(repoDir, written, skipped, contents, layers, project) {
     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 kept = { ...(previous?.kept ?? {}) };
+    for (const rel of written)
+        delete kept[rel];
+    for (const rel of skipped) {
+        if (files[rel] !== undefined)
+            continue; // the rig wrote it once; still its bytes to vouch for
+        const found = await readRegularFile(path.join(repoDir, rel));
+        if (found === null)
+            delete kept[rel];
+        else
+            kept[rel] = sha256(found);
+    }
     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
+        // No manifest: prefer the caller's already-validated identity (`create`,
+        // RP-177) and only fall back to slugging the directory name when there is
+        // none. 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: '' },
+        project: previous?.project ?? project ?? { name, scope: name, region: '' },
         stacks: previous?.stacks ?? [],
+        // `layers` is what THIS run resolved (already unioned with whatever the
+        // previous manifest recorded — RP-180's `effectiveLayers`), not
+        // re-derived here: a second computation of the same union is exactly the
+        // "second copy that goes stale" `invariants.md` warns about.
+        layers: [...layers],
         files,
+        ...(Object.keys(kept).length > 0 ? { kept } : {}),
     };
     await writeManifest(repoDir, manifest);
 }