create-agent-rig 0.9.1 → 0.10.0

package/package.json

@@ -1,19 +1,15 @@
 {
   "name": "create-agent-rig",
-  "version": "0.9.1",
-  "description": "Scaffold a new project with an agent operating system (rules, gates, hooks) and a runnable code skeleton",
+  "version": "0.10.0",
+  "description": "Configure an agent operating system (rules, gates, hooks) for Claude Code and Codex in a new or existing repository — no application scaffolding",
   "keywords": [
-    "create",
-    "scaffold",
-    "generator",
-    "starter",
-    "template",
     "agent",
     "claude-code",
     "codex",
     "agent-os",
-    "aws-serverless",
-    "node-service"
+    "rules",
+    "hooks",
+    "governance"
   ],
   "license": "MIT",
   "repository": {
@@ -38,16 +34,14 @@
   "packageManager": "pnpm@11.16.0",
   "scripts": {
     "prepare": "node scripts/prepare.mjs",
-    "build": "tsc -p packages/cli/tsconfig.build.json",
+    "build": "node scripts/prepare.mjs --build-only",
     "lint": "eslint . && prettier --check .",
     "format": "prettier --write .",
     "typecheck": "tsc -p packages/cli/tsconfig.json && tsc -p tsconfig.json",
     "test": "pnpm build && vitest run",
-    "test:unit": "vitest run --project unit --project template --project benchmark",
+    "test:unit": "vitest run --project unit --project template",
     "test:smoke": "vitest run --project unit",
-    "test:e2e": "pnpm build && vitest run --project e2e",
-    "template:install": "pnpm --dir templates/skeleton/aws-serverless install",
-    "template:check": "pnpm --dir templates/skeleton/aws-serverless run check"
+    "test:e2e": "pnpm build && vitest run --project e2e"
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",

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

@@ -1,121 +1,89 @@
 import { execFile } from 'node:child_process';
-import { mkdir, readFile, readdir, stat } from 'node:fs/promises';
+import { mkdir, readdir, stat } from 'node:fs/promises';
 import path from 'node:path';
 import { promisify } from 'node:util';
-import { copyTree, listTree, mapConcurrent } from '../lib/copy-tree.js';
-import { ALLOWED_OVERWRITES, detectCollisions } from '../lib/composition.js';
-import { agentOsLayerDirs } from '../lib/install-set.js';
-import { sha256, writeManifest } from '../lib/manifest.js';
-import { substituteContent, substituteFileName } from '../lib/substitute.js';
 import { gitEnv } from '../lib/git-env.js';
-import { DEFAULT_TARGET, TARGETS, TARGET_NAMES } from '../lib/targets.js';
-import { skeletonDir } from '../templates.js';
-import { packageVersion } from '../lib/version.js';
+import { initProject } from './init.js';
 /** A user-facing failure: message is printed as-is, no stack trace. */
 export class CreateError extends Error {
 }
-/** Valid npm package name (unscoped part) — also used as the npm scope. */
-const NAME_PATTERN = /^[a-z0-9][a-z0-9._-]*$/;
+/**
+ * A safe, predictable project name — also what ends up in a filename (the
+ * kill switch, `~/.claude/<name>-loop-STOP`) and inside a single-quoted string
+ * literal in a generated script (`stop-flag.mjs`), so it is validated
+ * up front rather than silently slugged. There is no npm scope to validate
+ * for any more (RP-177 retired the application skeleton this pattern used to
+ * double as): the shape survives only because it is still the right shape for
+ * a directory/kill-switch name, not because anything downstream reads it as a
+ * package identifier.
+ *
+ * No trailing `-` or `.`: `projectNameFor` (the name `init` would derive from
+ * this same directory with no identity supplied) strips both, and a name this
+ * pattern accepted but that function would rewrite is exactly the mismatch
+ * that once made a freshly created rig fail to match its own installed files
+ * on the very next `upgrade`.
+ */
+const NAME_PATTERN = /^[a-z0-9](?:[a-z0-9._-]*[a-z0-9])?$/;
+/**
+ * `create <dir>` — a thin convenience wrapper (RP-177): make the directory,
+ * initialize Git, run the same install `init` runs inside it, then commit the
+ * pristine baseline. There is only one payload flavour; this command's entire
+ * value is not having to `mkdir`, `git init`, `cd` and run `init` by hand.
+ */
 export async function createProject(dirArg, options) {
     const projectDir = path.resolve(options.cwd, dirArg);
     const projectName = path.basename(projectDir);
     if (!NAME_PATTERN.test(projectName)) {
-        throw new CreateError(`Invalid project name "${projectName}": use lowercase letters, digits, ".", "_" and "-" ` +
-            '(it becomes the npm package name and scope).');
+        throw new CreateError(`Invalid project name "${projectName}": use lowercase letters, digits, ".", "_" and "-", ` +
+            'starting and ending with a letter or digit.');
     }
     await ensureEmptyOrAbsent(projectDir);
-    const targetName = options.target ?? DEFAULT_TARGET;
-    const target = TARGETS[targetName];
-    if (!target) {
-        throw new CreateError(`Unknown target "${targetName}". Known targets: ${TARGET_NAMES.join(', ')}.`);
-    }
-    const ctx = {
-        projectName,
-        projectScope: projectName,
-        region: target.defaultRegion ?? '',
-    };
-    const transforms = {
-        transformContent: (content) => substituteContent(content, ctx),
-        transformName: (name) => substituteFileName(name, ctx),
-    };
-    // Layer 2 (the skeleton) + layer 1 (agent-os: universal + stack overlays).
-    const agentOsLayers = agentOsLayerDirs(target.stacks);
-    const layers = [
-        { name: `skeleton/${target.skeletonDir}`, dir: skeletonDir(target.skeletonDir) },
-        ...agentOsLayers,
-    ];
-    // Composition safety: layers must claim disjoint paths. Checked before any
-    // copy — a collision is a template bug and must never be resolved by order.
-    const claimed = [];
-    for (const layer of layers) {
-        claimed.push({ name: layer.name, files: await listTree(layer.dir, transforms) });
-    }
-    const collisions = detectCollisions(claimed, ALLOWED_OVERWRITES);
-    if (collisions.length > 0) {
-        const detail = collisions
-            .map((c) => `  ${c.path} — claimed by ${c.layers.join(' and ')}`)
-            .join('\n');
-        throw new CreateError(`Template layers collide (fix the templates, not the order):\n${detail}`);
-    }
     await mkdir(projectDir, { recursive: true });
-    for (const layer of layers) {
-        await copyTree(layer.dir, projectDir, transforms);
-    }
-    await recordInstall(projectDir, agentOsLayers, transforms, ctx, targetName);
-    if (options.git !== false) {
-        await initGitBaseline(projectDir);
+    const gitReady = options.git !== false && (await initGitRepository(projectDir));
+    await initProject(projectDir, {
+        project: { name: projectName, scope: projectName, region: '' },
+        withWorkflow: options.withWorkflow,
+    });
+    if (gitReady) {
+        await commitGitBaseline(projectDir);
     }
     return { projectDir, projectName };
 }
-/**
- * Record the agent-os layer in `.claude/.rig-manifest.json`, so a later
- * `upgrade` can tell a file the rig wrote from a file the project's own people
- * changed.
- *
- * The skeleton is **not** recorded, and that is the boundary of the whole
- * upgrade story: once generated, the code belongs to the project. The hashes
- * are read back off the disk rather than recomputed, so the manifest states
- * what is actually there and cannot drift from what was copied. The manifest
- * lands before the baseline commit — it is part of the pristine template, and
- * it belongs in the project's git history.
- */
-async function recordInstall(projectDir, agentOsLayers, transforms, ctx, target) {
-    const files = {};
-    for (const layer of agentOsLayers) {
-        const paths = await listTree(layer.dir, transforms);
-        const hashes = await mapConcurrent(paths, 16, async (rel) => ({
-            rel,
-            hash: sha256(await readFile(path.join(projectDir, ...rel.split('/')), 'utf8')),
-        }));
-        for (const { rel, hash } of hashes) {
-            files[rel] = hash;
-        }
+const run = promisify(execFile);
+const gitInvocation = (projectDir) => ({
+    quiet: ['-c', 'gc.auto=0', '-c', 'maintenance.auto=false'],
+    where: { cwd: projectDir, env: gitEnv() },
+});
+async function initGitRepository(projectDir) {
+    const { quiet, where } = gitInvocation(projectDir);
+    try {
+        await run('git', [...quiet, 'init', '--quiet'], where);
+        return true;
+    }
+    catch {
+        // git missing or unusable — generation never fails on this.
+        return false;
     }
-    await writeManifest(projectDir, {
-        version: await packageVersion(),
-        kind: 'create',
-        project: { name: ctx.projectName, scope: ctx.projectScope, region: ctx.region },
-        stacks: [...(TARGETS[target]?.stacks ?? [])],
-        files,
-    });
 }
-const run = promisify(execFile);
-async function initGitBaseline(projectDir) {
+async function commitGitBaseline(projectDir) {
     // Disable git's background maintenance for these one-shot commands: a commit
     // can otherwise fork an auto-gc / maintenance process that keeps writing to
     // .git/objects/pack after we return — a non-deterministic tail that races any
     // caller cleaning up the directory, and pointless work on a one-commit repo.
-    const quiet = ['-c', 'gc.auto=0', '-c', 'maintenance.auto=false'];
-    const where = { cwd: projectDir, env: gitEnv() };
+    const { quiet, where } = gitInvocation(projectDir);
+    // Pin both repository locations even though cwd is already the child. If a
+    // later refactor calls this without a successful `git init`, Git must fail
+    // here rather than discover and mutate a parent repository.
+    const repository = [`--git-dir=${path.join(projectDir, '.git')}`, `--work-tree=${projectDir}`];
     try {
-        await run('git', [...quiet, 'init', '--quiet'], where);
-        await run('git', [...quiet, 'add', '-A'], where);
+        await run('git', [...quiet, ...repository, 'add', '-A'], where);
         // Explicit identity: the baseline must commit even where git has no
         // global user configured (fresh machines, CI). --no-verify here shields
         // the baseline from the USER'S global hooks only — the generated
         // project's own gates do not exist yet, so nothing is being bypassed.
         await run('git', [
             ...quiet,
+            ...repository,
             '-c',
             'user.name=create-agent-rig',
             '-c',

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

@@ -0,0 +1,213 @@
+import { parseArgs } from 'node:util';
+import { MANIFEST_REL, parseManifest, sha256 } from '../lib/manifest.js';
+import { readBounded, verifyIntegrations } from '../integrations/verify.js';
+import { DECLARATION_REL, MAX_DECLARATION_BYTES, parseDeclaration, } from '../integrations/declaration.js';
+import { REGISTRY } from '../integrations/registry.js';
+import { inspectSpecKit, SPEC_KIT_VERSION, } from '../integrations/spec-kit.js';
+import { inspectMemory } from '../integrations/memory-doctor.js';
+import { inspectGuards } from '../integrations/doctor-guards.js';
+import { inspectWorkflow } from '../integrations/doctor-workflow.js';
+function text(bytes) {
+    try {
+        return new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(bytes);
+    }
+    catch {
+        return undefined;
+    }
+}
+async function rigChecks(root, codexHash) {
+    const source = await readBounded(root, MANIFEST_REL, 1024 * 1024);
+    if (source.status === 'absent')
+        return [{ id: 'rig-manifest', status: 'warn', reason: 'not-installed' }];
+    const decoded = source.status === 'ok' ? text(source.bytes) : undefined;
+    const manifest = decoded === undefined ? null : parseManifest(decoded);
+    if (manifest === null || Object.keys(manifest.files).length > 4096)
+        return [{ id: 'rig-manifest', status: 'fail', reason: 'unreadable-manifest' }];
+    const checks = [{ id: 'rig-manifest', status: 'pass', reason: 'valid' }];
+    let contentDrift = false;
+    let lineDrift = false;
+    let absent = false;
+    let unreadable = false;
+    for (const [rel, recorded] of Object.entries(manifest.files)) {
+        const expected = rel === '.codex/config.toml' ? (codexHash ?? recorded) : recorded;
+        const file = await readBounded(root, rel, 1024 * 1024);
+        if (file.status === 'absent') {
+            absent = true;
+            continue;
+        }
+        if (file.status !== 'ok') {
+            unreadable = true;
+            continue;
+        }
+        if (sha256(file.bytes) === expected)
+            continue;
+        const decodedFile = text(file.bytes);
+        if (decodedFile !== undefined &&
+            (sha256(decodedFile.replace(/\r\n/g, '\n')) === expected ||
+                sha256(decodedFile.replace(/\r\n/g, '\n').replace(/\n/g, '\r\n')) === expected))
+            lineDrift = true;
+        else
+            contentDrift = true;
+    }
+    checks.push({
+        id: 'rig-owned-files',
+        status: unreadable ? 'fail' : absent || contentDrift || lineDrift ? 'warn' : 'pass',
+        reason: unreadable
+            ? 'unreadable-owned-file'
+            : absent
+                ? 'absent-owned-file'
+                : contentDrift
+                    ? 'content-drift'
+                    : lineDrift
+                        ? 'line-ending-drift'
+                        : 'pristine',
+    });
+    return checks;
+}
+/** Read-only diagnosis. Runtime observations are returned, never persisted. */
+export async function runDoctor(options) {
+    let json;
+    try {
+        const parsed = parseArgs({
+            args: options.args,
+            allowPositionals: false,
+            options: { json: { type: 'boolean' } },
+        });
+        json = parsed.values.json === true;
+    }
+    catch {
+        return { exitCode: 2, stdout: '', stderr: 'doctor accepts only --json\n' };
+    }
+    const source = await readBounded(options.cwd, DECLARATION_REL, MAX_DECLARATION_BYTES);
+    const declaration = source.status === 'ok' ? parseDeclaration(text(source.bytes) ?? '', REGISTRY) : undefined;
+    const intent = declaration?.status === 'ok' && declaration.rejected.length === 0 ? declaration : undefined;
+    const checks = await rigChecks(options.cwd, intent?.targets?.codex?.fileHash);
+    if (checks.some((check) => check.id === 'rig-manifest' && check.status === 'pass')) {
+        const [guards, workflow] = await Promise.all([
+            inspectGuards({ repoDir: options.cwd }),
+            inspectWorkflow({ repoDir: options.cwd }),
+        ]);
+        checks.push({ id: 'guards', ...guards }, { id: 'workflow', ...workflow });
+    }
+    const memory = await inspectMemory({ repoDir: options.cwd, env: options.env ?? process.env });
+    checks.push({ id: 'custom-memory', status: memory.status, reason: memory.reason });
+    let specKit;
+    const wiring = await verifyIntegrations({ repoDir: options.cwd, env: options.env });
+    const invalid = wiring.issues.some((issue) => issue.status !== 'missing');
+    const pendingHarness = wiring.integrations.some((entry) => Object.keys(entry.harnesses).length === 0);
+    checks.push({
+        id: 'integrations',
+        status: invalid ? 'fail' : pendingHarness ? 'warn' : 'pass',
+        reason: invalid
+            ? 'invalid-declaration'
+            : pendingHarness
+                ? 'harness-selection-pending'
+                : wiring.integrations.length
+                    ? 'declared'
+                    : 'not-selected',
+    });
+    for (const entry of wiring.integrations) {
+        if (Object.keys(entry.harnesses).length === 0) {
+            checks.push({
+                id: `${entry.id}:harness-selection`,
+                status: 'warn',
+                reason: 'harness-selection-pending',
+            });
+            continue;
+        }
+        if (entry.id === 'spec-kit') {
+            const selected = intent?.entries.find((candidate) => candidate.id === 'spec-kit');
+            if (selected?.version !== SPEC_KIT_VERSION) {
+                checks.push({ id: 'spec-kit', status: 'fail', reason: 'unsupported-requested-version' });
+            }
+            else {
+                const inspection = await inspectSpecKit({
+                    repoDir: options.cwd,
+                    harnesses: selected.harnesses ?? [],
+                    env: options.env,
+                });
+                specKit = inspection;
+                checks.push({ id: 'spec-kit', status: inspection.status, reason: inspection.reason });
+            }
+            continue;
+        }
+        for (const [harness, state] of Object.entries(entry.harnesses)) {
+            checks.push({
+                id: `${entry.id}:${harness}`,
+                status: state.wiring === 'unreadable'
+                    ? 'fail'
+                    : state.wiring === 'healthy'
+                        ? state.launcher === 'missing'
+                            ? 'warn'
+                            : 'pass'
+                        : 'warn',
+                reason: state.wiring === 'healthy'
+                    ? state.launcher === 'missing'
+                        ? 'launcher-missing'
+                        : 'wired'
+                    : state.wiring,
+            });
+        }
+    }
+    const status = checks.some((check) => check.status === 'fail')
+        ? 'fail'
+        : checks.some((check) => check.status === 'warn')
+            ? 'warn'
+            : 'pass';
+    const wiringNames = {
+        healthy: 'wired',
+        missing: 'absent',
+        drift: 'drifted',
+        unowned: 'foreign',
+        unreadable: 'unreadable',
+    };
+    const integrations = wiring.integrations
+        .filter((entry) => entry.id !== 'spec-kit')
+        .map((entry) => ({
+        id: entry.id,
+        harnesses: Object.fromEntries(Object.entries(entry.harnesses).map(([harness, state]) => [
+            harness,
+            { ...state, wiring: wiringNames[state.wiring] },
+        ])),
+    }));
+    const report = {
+        schemaVersion: 1,
+        status: status === 'pass' ? 'ok' : status,
+        checks: checks.map((check) => ({
+            ...check,
+            status: check.status === 'pass' ? 'ok' : check.status,
+            detail: check.reason === 'workflow-verified'
+                ? 'Workflow and frozen revalidation scripts match this package; the RP-26 decision is not observed.'
+                : check.reason.replaceAll('-', ' '),
+            fix: check.status === 'pass'
+                ? ''
+                : check.id.startsWith('rig-') || check.id === 'guards' || check.id === 'workflow'
+                    ? 'Review the installation with create-agent-rig upgrade before accepting changes.'
+                    : check.id === 'custom-memory'
+                        ? 'Check the machine-scoped Memory installation and its compatible version.'
+                        : check.id === 'spec-kit'
+                            ? 'Check the pinned Spec Kit launcher and authoritative integration status.'
+                            : 'Review create-agent-rig setup list and the intended provider wiring.',
+        })),
+        integrations,
+        memory: { ...memory, status: memory.status === 'pass' ? 'ok' : memory.status },
+        ...(specKit
+            ? {
+                specKit: {
+                    version: SPEC_KIT_VERSION,
+                    ...specKit,
+                    status: specKit.status === 'pass' ? 'ok' : specKit.status,
+                    connectivity: 'not-observed',
+                    trust: 'not-observed',
+                },
+            }
+            : {}),
+    };
+    return {
+        exitCode: status === 'fail' ? 1 : 0,
+        stdout: json
+            ? `${JSON.stringify(report)}\n`
+            : `${report.checks.map((check) => `${check.status}: ${check.id}: ${check.detail}${check.fix ? ` — ${check.fix}` : ''}`).join('\n')}\n`,
+        stderr: '',
+    };
+}