peer-ai 1.0.0-next.0

package/dist/render.js

@@ -0,0 +1,557 @@
+// peer-ai render: writes what each AI tool in the config reads, so every tool works the project
+// the same way. Instructions go in a marked block inside the project's own files (AGENTS.md,
+// CLAUDE.md, GEMINI.md, Copilot's instructions), and only that block is ever rewritten. Cursor gets
+// a rule file of its own. The MCP server is registered in each tool's project config, next to
+// whatever else is there. Peer AI's skills are written where each tool reads them, under a peer-ai-
+// prefix, and left out of git: they're rebuilt from the installed version (RFC 0004). So that cloud
+// agents, which start from a fresh clone, have them too, each tool's setup step runs
+// `peer-ai render --skills` before the agent starts. Running it twice changes nothing, and --check
+// reports drift for CI.
+import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, unlinkSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { SKILL_NAME_PREFIX, availableSkills, loadSkill, readSkillFiles, renderedName } from "peer-ai-skills";
+import { loadConfig } from "./assess.js";
+import { count, fail, formatChecks, ok, plural, skip } from "./checks.js";
+import { CONFIG_FILE } from "./detect.js";
+import { FEEDBACK_DIR } from "./feedback.js";
+import { VERSION } from "./package-info.js";
+import { WORKFLOW_FILE, sameFile, unchangedSinceRender, workflowFile } from "./pipeline.js";
+import { RUFF_FILE, ruffFile } from "./ruff.js";
+export const START = "<!-- peer-ai:start -->";
+export const END = "<!-- peer-ai:end -->";
+const GENERATED = `<!-- Generated by peer-ai render from ${CONFIG_FILE}. Change the config and run peer-ai render; edits inside this block are replaced. -->`;
+const SERVER = "peer-ai";
+const IMPORTS_AGENTS = /^@AGENTS\.md\s*$/m;
+/** How AI tools start the server: the project's own pinned copy, or this exact version. */
+export function serverCommand(root) {
+    const pkg = readJson(join(root, "package.json"));
+    const pinned = pkg?.devDependencies?.["peer-ai"] ?? pkg?.dependencies?.["peer-ai"];
+    return pinned === undefined
+        ? { command: "npx", args: ["-y", `peer-ai@${VERSION}`, "mcp"] }
+        : { command: "npx", args: ["peer-ai", "mcp"] };
+}
+/**
+ * The command that writes only the skills, for a session or a cloud agent to run before it starts.
+ * It uses the same peer-ai the MCP server does: the project's pinned copy, or this exact version.
+ */
+export function skillsCommand(root) {
+    const { command, args } = serverCommand(root);
+    return [command, ...args.slice(0, -1), "render", "--skills", "--quiet"].join(" ");
+}
+/** Recognises the skills command in a setup file, whichever version it names. */
+const SKILLS_COMMAND = /npx (?:-y )?peer-ai(?:@\S+)? render --skills(?: --quiet)?/;
+function readJson(path) {
+    try {
+        return JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch {
+        return undefined;
+    }
+}
+function readText(root, path) {
+    const full = join(root, path);
+    return existsSync(full) ? readFileSync(full, "utf8") : undefined;
+}
+/** The instructions every tool gets: short, because the MCP server serves the detail on demand. */
+export function instructions(config) {
+    const { project } = config;
+    const lines = [
+        "## Peer AI",
+        "",
+        `This project uses Peer AI${project.stage === undefined ? "" : ` at the ${project.stage} stage`}. Its MCP server, \`${SERVER}\`, holds the project map, the work items, and the gates work must pass before it ships.`,
+        "",
+        "- Start each session with `next_work`. It returns the work item for the current branch and where it stopped. For new work, create one with `create_work_item`.",
+        "- Keep the item's stage current with `advance_work_item`: `build` before you change code, `verify` once the change is complete, `ship` when it is verified, reviewed and ready to merge, and `done` once it is merged or released. When it refuses, fix what it lists.",
+        "- Before editing a file, call `standards_for_file` and follow what it returns.",
+        "- Record progress with `update_work_item`, so the next session resumes where this one stopped.",
+        "- Verify with `run_verify`. Never report a verify result yourself.",
+        "- Peer AI's skills are named `peer-ai-…`, such as `peer-ai-security-review`. `next_work` names the one to use for a gap, and the reviews a work item needs; follow each skill step by step. If none are installed, run `npx peer-ai render --skills`.",
+        "- For every review, write its report in `.peer-ai/reports/`, then record it with `record_review` and the report's path. Record failed and incomplete reviews too.",
+        "- For every document a skill writes, such as the requirements, check it with `check_document` and fix what it names.",
+        "- Don't edit the files in `.peer-ai/` by hand. The tools keep them valid.",
+        "- When `next_work` reports setup problems, fix what you can, such as running `npx peer-ai render`, before other work, and tell the person in plain words about anything only they can decide.",
+        "- When Peer AI gets something wrong, call `draft_feedback`. At a natural stopping point, show the person each draft in a few words and ask whether to send it.",
+    ];
+    const ownTracks = config.tracks.filter((track) => track.status !== "external");
+    if (config.tracks.length > 1) {
+        lines.push("", "Parts of the project:", "");
+        for (const track of config.tracks) {
+            const where = track.status === "external"
+                ? `in ${track.repo ?? "another repository"}`
+                : (track.path ?? "the repository root");
+            lines.push(`- \`${track.id}\` (${track.kind}, ${track.status}): ${where}`);
+        }
+    }
+    else if (ownTracks[0] !== undefined) {
+        lines.push("", `The project is one ${ownTracks[0].kind} part, \`${ownTracks[0].id}\`.`);
+    }
+    const commands = Object.entries(config.commands ?? {}).filter((entry) => typeof entry[1] === "string");
+    if (commands.length > 0) {
+        lines.push("", `Commands: ${commands.map(([name, command]) => `${name} \`${command}\``).join(", ")}.`);
+    }
+    const compliance = config.compliance;
+    const packs = [...(compliance?.packs ?? [])];
+    if (packs.length + (compliance?.jurisdictions?.length ?? 0) > 0) {
+        const where = compliance?.jurisdictions === undefined ? "" : ` for ${compliance.jurisdictions.join(", ")}`;
+        lines.push("", `Compliance${where}: ${packs.length === 0 ? "rule packs to be chosen" : packs.join(", ")}.`);
+    }
+    if ((config.rules ?? []).length > 0) {
+        lines.push("", "Every change respects the project's own rules:", "");
+        for (const rule of config.rules ?? []) {
+            lines.push(`- \`${rule.path}\`${rule.description === undefined ? "" : `: ${rule.description}`}`);
+        }
+    }
+    lines.push("", "If the peer-ai tools aren't available, run `npx peer-ai doctor`.");
+    return lines.join("\n");
+}
+const block = (body) => `${START}\n${GENERATED}\n\n${body}\n${END}`;
+const IGNORE_START = "# peer-ai:start";
+const IGNORE_END = "# peer-ai:end";
+/**
+ * The file with its marked block written or replaced, and nothing outside the block touched. The
+ * markers default to the instructions block; .gitignore uses its own.
+ */
+function withBlock(path, existing, body, markers = { start: START, end: END, block: block(body) }) {
+    const wanted = markers.block;
+    if (existing === undefined)
+        return { path, action: "create", content: `${wanted}\n` };
+    const from = existing.indexOf(markers.start);
+    if (from === -1) {
+        const separator = existing === "" ? "" : existing.endsWith("\n") ? "\n" : "\n\n";
+        return { path, action: "update", content: `${existing}${separator}${wanted}\n` };
+    }
+    const to = existing.indexOf(markers.end, from);
+    if (to === -1) {
+        return {
+            path,
+            action: "refused",
+            note: `It has ${markers.start} but no ${markers.end} after it. Add the end marker, or remove the start marker, then render again.`,
+        };
+    }
+    const content = `${existing.slice(0, from)}${wanted}${existing.slice(to + markers.end.length)}`;
+    return { path, action: content === existing ? "unchanged" : "update", content };
+}
+/** Registers the server under `key` in a JSON config, keeping every other entry as it is. */
+function withServer(root, path, key, entry) {
+    const existing = readText(root, path);
+    if (existing === undefined) {
+        return { path, action: "create", content: `${JSON.stringify({ [key]: { [SERVER]: entry } }, null, 2)}\n` };
+    }
+    const parsed = readJson(join(root, path));
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        return {
+            path,
+            action: "refused",
+            note: `It isn't plain JSON (comments aren't supported here), so add this under "${key}" by hand: "${SERVER}": ${JSON.stringify(entry)}`,
+        };
+    }
+    const config = parsed;
+    const servers = (typeof config[key] === "object" && config[key] !== null ? config[key] : {});
+    if (JSON.stringify(servers[SERVER]) === JSON.stringify(entry))
+        return { path, action: "unchanged" };
+    const content = `${JSON.stringify({ ...config, [key]: { ...servers, [SERVER]: entry } }, null, 2)}\n`;
+    return { path, action: "update", content };
+}
+function cursorRule(body) {
+    return [
+        "---",
+        "description: How to work in this project with Peer AI",
+        "alwaysApply: true",
+        "---",
+        "",
+        GENERATED.replace("edits inside this block are replaced", "this file is replaced"),
+        "",
+        body,
+        "",
+    ].join("\n");
+}
+/**
+ * A tool's own instructions file. When AGENTS.md carries the block, a new file just imports it, so
+ * the tool doesn't read the instructions twice; an existing file that imports it is left alone.
+ */
+function toolFile(root, path, body, agentsRendered) {
+    const existing = readText(root, path);
+    if (existing === undefined && agentsRendered) {
+        return { path, action: "create", content: "@AGENTS.md\n", note: "It imports AGENTS.md." };
+    }
+    if (existing !== undefined && IMPORTS_AGENTS.test(existing) && !existing.includes(START)) {
+        return { path, action: "unchanged", note: "It imports AGENTS.md, which carries the instructions." };
+    }
+    return withBlock(path, existing, body);
+}
+/**
+ * Where the tools in the config read skills. Codex, Cursor, Copilot and Gemini CLI read the shared
+ * .agents/skills; Claude Code reads .claude/skills, which Cursor and Copilot also read. So each
+ * skill is written as few times as the tools allow, and not at all when no tool is listed.
+ */
+export function skillFolders(tools) {
+    const folders = tools.includes("claude-code") ? [".claude/skills"] : [];
+    const needsShared = tools.some((tool) => tool === "codex" || tool === "gemini-cli" || tool === "other");
+    const readsEither = tools.some((tool) => tool === "cursor" || tool === "copilot");
+    if (needsShared || (readsEither && folders.length === 0))
+        folders.push(".agents/skills");
+    return folders;
+}
+const SKILL_HOMES = [".claude/skills", ".agents/skills"];
+const isDirectory = (path) => statSync(path, { throwIfNoEntry: false })?.isDirectory() === true;
+/**
+ * Every Peer AI skill in each folder its tools read, and every Peer AI skill that shouldn't be
+ * there any more: one this version no longer has, or one in a folder no listed tool reads.
+ */
+function planSkills(root, tools) {
+    const folders = skillFolders(tools);
+    const planned = [];
+    for (const home of SKILL_HOMES) {
+        const wanted = folders.includes(home) ? availableSkills() : [];
+        for (const id of wanted) {
+            const name = renderedName(id);
+            const path = `${home}/${name}`;
+            const files = loadSkill(id, { name });
+            const existing = isDirectory(join(root, path)) ? readSkillFiles(join(root, path)) : undefined;
+            const stale = existing === undefined ? [] : [...existing.keys()].filter((file) => !files.has(file));
+            const same = existing !== undefined && stale.length === 0 && [...files].every(([file, text]) => existing.get(file) === text);
+            planned.push({ path, action: existing === undefined ? "create" : same ? "unchanged" : "update", files, stale });
+        }
+        const names = new Set(wanted.map(renderedName));
+        const present = isDirectory(join(root, home)) ? readdirSync(join(root, home)) : [];
+        for (const entry of present.filter((entry) => entry.startsWith(SKILL_NAME_PREFIX) && !names.has(entry))) {
+            planned.push({ path: `${home}/${entry}`, action: "remove", files: new Map(), stale: [] });
+        }
+    }
+    return planned;
+}
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/** A JSON file changed by `change`, or refused when it isn't plain JSON, with what to add by hand. */
+function editJson(root, path, create, change, byHand) {
+    const existing = readText(root, path);
+    if (existing === undefined)
+        return { path, action: "create", content: `${JSON.stringify(create, null, 2)}\n` };
+    const parsed = readJson(join(root, path));
+    if (!isRecord(parsed)) {
+        return { path, action: "refused", note: `It isn't plain JSON (comments aren't supported here), so ${byHand}` };
+    }
+    const changed = change(parsed);
+    if (JSON.stringify(changed) === JSON.stringify(parsed))
+        return { path, action: "unchanged" };
+    return { path, action: "update", content: `${JSON.stringify(changed, null, 2)}\n` };
+}
+/**
+ * Claude Code runs a project's SessionStart hooks in every session, including cloud sessions,
+ * which start from a fresh clone. The hook writes the skills before the session begins.
+ */
+function claudeSessionHook(root, command) {
+    const hook = { type: "command", command };
+    const entry = { matcher: "startup", hooks: [hook] };
+    return editJson(root, ".claude/settings.json", { hooks: { SessionStart: [entry] } }, (settings) => {
+        const hooks = isRecord(settings.hooks) ? settings.hooks : {};
+        const groups = Array.isArray(hooks.SessionStart) ? hooks.SessionStart : [];
+        const isOurs = (item) => isRecord(item) && typeof item.command === "string" && SKILLS_COMMAND.test(item.command);
+        const inGroup = (group) => (isRecord(group) && Array.isArray(group.hooks) ? group.hooks : []);
+        const found = groups.some((group) => inGroup(group).some(isOurs));
+        const updated = groups.map((group) => isRecord(group) && Array.isArray(group.hooks)
+            ? { ...group, hooks: group.hooks.map((item) => (isOurs(item) ? { ...item, command } : item)) }
+            : group);
+        return { ...settings, hooks: { ...hooks, SessionStart: found ? updated : [...groups, entry] } };
+    }, `add a SessionStart hook that runs: ${command}`);
+}
+/** Cursor's cloud agents run the environment's start command each time an agent boots. */
+function cursorEnvironment(root, command) {
+    return editJson(root, ".cursor/environment.json", { start: command }, (environment) => {
+        const start = typeof environment.start === "string" ? environment.start : undefined;
+        const next = start === undefined || start === ""
+            ? command
+            : SKILLS_COMMAND.test(start)
+                ? start.replace(SKILLS_COMMAND, command)
+                : `${start} && ${command}`;
+        return { ...environment, start: next };
+    }, `add to its "start" command: ${command}`);
+}
+const CHECKOUT = "actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1";
+const SETUP_NODE = "actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0";
+/**
+ * Copilot's cloud agent runs the copilot-setup-steps job before it starts. A workflow that already
+ * exists is left to its owner, with the step to add.
+ */
+function copilotSetupSteps(root, command) {
+    const path = ".github/workflows/copilot-setup-steps.yml";
+    const existing = readText(root, path);
+    if (existing !== undefined) {
+        if (!SKILLS_COMMAND.test(existing)) {
+            return {
+                path,
+                action: "refused",
+                note: `It exists, so add this step to its copilot-setup-steps job: - run: ${command}`,
+            };
+        }
+        const content = existing.replace(SKILLS_COMMAND, command);
+        return { path, action: content === existing ? "unchanged" : "update", content };
+    }
+    const content = [
+        "# Prepares Copilot's cloud agent before it starts. Peer AI's step writes its skills, which stay",
+        "# out of git. Generated by peer-ai render; add your own steps after Peer AI's.",
+        "name: Copilot setup steps",
+        "on: workflow_dispatch",
+        "permissions:",
+        "  contents: read",
+        "jobs:",
+        "  copilot-setup-steps:",
+        "    runs-on: ubuntu-latest",
+        "    steps:",
+        `      - uses: ${CHECKOUT}`,
+        `      - uses: ${SETUP_NODE}`,
+        "        with:",
+        "          node-version: 24",
+        `      - run: ${command}`,
+        "",
+    ].join("\n");
+    return { path, action: "create", content };
+}
+const ATTRIBUTES_START = "# peer-ai:start";
+const ATTRIBUTES_END = "# peer-ai:end";
+/** Committed skills are marked as generated, so pull requests fold them away. */
+function markSkillsGenerated(root, folders) {
+    const lines = [
+        ATTRIBUTES_START,
+        "# Generated by peer-ai render: Peer AI's skills, rebuilt from the installed version.",
+        ...folders.map((folder) => `/${folder}/${SKILL_NAME_PREFIX}*/** linguist-generated=true`),
+        ATTRIBUTES_END,
+    ];
+    const markers = { start: ATTRIBUTES_START, end: ATTRIBUTES_END, block: lines.join("\n") };
+    return withBlock(".gitattributes", readText(root, ".gitattributes"), "", markers);
+}
+/**
+ * Keeps out of git, in a marked block of .gitignore, what never belongs there: the rendered skills,
+ * unless the project commits them, and feedback drafts, which stay on the person's machine until
+ * they send them (RFC 0007).
+ */
+function ignoreBlock(root, folders) {
+    const lines = [
+        IGNORE_START,
+        ...(folders.length === 0
+            ? ["# Generated by peer-ai render."]
+            : [
+                "# Generated by peer-ai render. Peer AI's skills are rebuilt from the installed version: run peer-ai render after cloning.",
+                ...folders.map((folder) => `/${folder}/${SKILL_NAME_PREFIX}*/`),
+            ]),
+        "# Feedback drafts stay on this machine until a person sends them.",
+        `/${FEEDBACK_DIR}/`,
+        IGNORE_END,
+    ];
+    const markers = { start: IGNORE_START, end: IGNORE_END, block: lines.join("\n") };
+    return withBlock(".gitignore", readText(root, ".gitignore"), "", markers);
+}
+export function planRender(root, config) {
+    const tools = config.tools ?? [];
+    const body = instructions(config);
+    const server = serverCommand(root);
+    const files = [];
+    const manual = [];
+    const uses = (tool) => tools.includes(tool);
+    const imports = (path) => IMPORTS_AGENTS.test(readText(root, path) ?? "");
+    // AGENTS.md is the file most tools read. A project that only uses Claude Code gets it when it
+    // already has one, or when CLAUDE.md or GEMINI.md imports it.
+    const agents = tools.length === 0 ||
+        tools.some((tool) => tool !== "claude-code") ||
+        existsSync(join(root, "AGENTS.md")) ||
+        imports("CLAUDE.md");
+    if (agents)
+        files.push(withBlock("AGENTS.md", readText(root, "AGENTS.md"), body));
+    if (uses("claude-code")) {
+        files.push(toolFile(root, "CLAUDE.md", body, agents));
+        files.push(withServer(root, ".mcp.json", "mcpServers", server));
+    }
+    if (uses("cursor")) {
+        const path = ".cursor/rules/peer-ai.mdc";
+        const content = cursorRule(body);
+        const existing = readText(root, path);
+        files.push({
+            path,
+            action: existing === undefined ? "create" : existing === content ? "unchanged" : "update",
+            content,
+        });
+        files.push(withServer(root, ".cursor/mcp.json", "mcpServers", server));
+    }
+    if (uses("copilot")) {
+        files.push(withBlock(".github/copilot-instructions.md", readText(root, ".github/copilot-instructions.md"), body));
+        files.push(withServer(root, ".vscode/mcp.json", "servers", { type: "stdio", ...server }));
+    }
+    if (uses("gemini-cli")) {
+        files.push(toolFile(root, "GEMINI.md", body, agents));
+        files.push(withServer(root, ".gemini/settings.json", "mcpServers", server));
+    }
+    const command = skillsCommand(root);
+    // Ruff reads settings from a file, not a package, so its settings for the project's stack
+    // profiles are written where the project's own Ruff settings can extend them (RFC 0006).
+    const ruff = ruffFile(config);
+    if (ruff !== undefined) {
+        const existing = readText(root, RUFF_FILE);
+        files.push({
+            path: RUFF_FILE,
+            action: existing === undefined ? "create" : existing === ruff ? "unchanged" : "update",
+            content: ruff,
+        });
+    }
+    // The pipeline profile's checks, as one workflow render owns while nobody changes it by hand.
+    const workflow = workflowFile(config);
+    if (workflow !== undefined) {
+        const existing = readText(root, WORKFLOW_FILE);
+        if (existing === undefined)
+            files.push({ path: WORKFLOW_FILE, action: "create", content: workflow });
+        else if (unchangedSinceRender(existing)) {
+            const same = sameFile(existing, workflow);
+            files.push({
+                path: WORKFLOW_FILE,
+                action: same ? "unchanged" : "update",
+                ...(same ? {} : { content: workflow }),
+            });
+        }
+        else {
+            files.push({
+                path: WORKFLOW_FILE,
+                action: "kept",
+                note: "It was changed by hand, so keeping it up to date with the config is yours now; peer-ai doctor checks it still has every job. Delete it to have render write Peer AI's again.",
+            });
+        }
+    }
+    if (uses("claude-code"))
+        files.push(claudeSessionHook(root, command));
+    if (uses("cursor"))
+        files.push(cursorEnvironment(root, command));
+    if (uses("copilot"))
+        files.push(copilotSetupSteps(root, command));
+    if (uses("codex")) {
+        manual.push(`Codex cloud keeps its setup script in the environment's settings, not the project. Add this line to it, so the skills and the MCP server are ready before the agent starts (its internet is off while it works): ${command}`);
+        manual.push(`Codex keeps MCP servers in your own config, not the project's. Register it once: codex mcp add ${SERVER} -- ${server.command} ${server.args.join(" ")}`, `Codex asks before run_verify, because it runs the project's verify command. To allow it without asking, add to ~/.codex/config.toml: [mcp_servers.${SERVER}.tools.run_verify] approval_mode = "approve"`);
+    }
+    if (uses("other")) {
+        manual.push(`For another tool, point it at AGENTS.md, and register the MCP server as: ${server.command} ${server.args.join(" ")}`);
+    }
+    const skills = planSkills(root, tools);
+    const folders = skillFolders(tools);
+    const committed = config.skills?.commit === true;
+    if (committed && folders.length > 0)
+        files.push(markSkillsGenerated(root, folders));
+    const ignoredSkills = committed || !skills.some((skill) => skill.action !== "remove") ? [] : folders;
+    files.push(ignoreBlock(root, ignoredSkills));
+    return { files, skills, manual };
+}
+function write(root, planned) {
+    if (planned.content === undefined)
+        return;
+    const full = join(root, planned.path);
+    mkdirSync(dirname(full), { recursive: true });
+    writeFileSync(full, planned.content);
+}
+function writeSkill(root, skill) {
+    const folder = join(root, skill.path);
+    if (skill.action === "remove") {
+        rmSync(folder, { recursive: true, force: true });
+        return;
+    }
+    for (const file of skill.stale)
+        unlinkSync(join(folder, file));
+    for (const [file, text] of skill.files) {
+        mkdirSync(dirname(join(folder, file)), { recursive: true });
+        writeFileSync(join(folder, file), text);
+    }
+}
+/** One line per skills folder, rather than one per file. */
+function skillChecks(skills) {
+    const homes = [...new Set(skills.map((skill) => skill.path.slice(0, skill.path.lastIndexOf("/"))))];
+    return homes.map((home) => {
+        const here = skills.filter((skill) => skill.path.startsWith(`${home}/`));
+        const changed = here.filter((skill) => skill.action !== "unchanged");
+        const names = (action) => here.filter((skill) => skill.action === action).map((skill) => skill.path.slice(home.length + 1));
+        if (changed.length === 0)
+            return ok("render", `${home}/: ${plural(here.length, "skill")}, up to date.`);
+        const parts = [
+            ["written", [...names("create"), ...names("update")]],
+            ["removed", names("remove")],
+        ];
+        const summary = parts
+            .filter(([, list]) => list.length > 0)
+            .map(([verb, list]) => `${verb} ${list.join(", ")}`)
+            .join("; ");
+        return ok("render", `${home}/: ${summary}.`);
+    });
+}
+function toCheck(planned, checking) {
+    switch (planned.action) {
+        case "refused":
+            return fail("render", `${planned.path} wasn't changed.`, planned.note ?? "");
+        case "kept":
+            return skip("render", `${planned.path} left as it is. ${planned.note ?? ""}`.trim());
+        case "unchanged":
+            return ok("render", `${planned.path} is up to date.${planned.note === undefined ? "" : ` ${planned.note}`}`);
+        default:
+            return checking
+                ? fail("render", `${planned.path} is out of date.`, "Run peer-ai render.")
+                : ok("render", `${planned.path} ${planned.action === "create" ? "created" : "updated"}.${planned.note === undefined ? "" : ` ${planned.note}`}`);
+    }
+}
+/** Exit code 0 when done or up to date; 1 when a file was refused, or out of date with --check; 2 without a valid config. */
+export function runRender(options, out) {
+    const { config, errors } = loadConfig(options.cwd);
+    if (config === undefined) {
+        if (errors === undefined)
+            out.error(`There is no ${CONFIG_FILE}. Run peer-ai init first.`);
+        else {
+            out.error(`${CONFIG_FILE} is not valid:`);
+            for (const error of errors)
+                out.error(`  ${error}`);
+        }
+        return 2;
+    }
+    const plan = planRender(options.cwd, config);
+    if (options.skills === true) {
+        for (const skill of plan.skills)
+            if (skill.action !== "unchanged")
+                writeSkill(options.cwd, skill);
+        if (options.quiet !== true)
+            for (const line of formatChecks(skillChecks(plan.skills)))
+                out.log(line);
+        return 0;
+    }
+    const committed = config.skills?.commit === true;
+    if (!options.check) {
+        for (const planned of plan.files)
+            if (planned.action !== "refused" && planned.action !== "kept")
+                write(options.cwd, planned);
+        for (const skill of plan.skills)
+            if (skill.action !== "unchanged")
+                writeSkill(options.cwd, skill);
+    }
+    // --check is for CI, which sees only what's committed. Skills usually aren't, so it leaves them
+    // out unless the project commits them; peer-ai doctor reports missing skills on a person's machine.
+    const skillLines = !options.check
+        ? skillChecks(plan.skills)
+        : committed
+            ? plan.skills
+                .filter((skill) => skill.action !== "unchanged")
+                .map((skill) => fail("render", `${skill.path}/ is out of date.`, "Run peer-ai render."))
+            : [];
+    const checks = [...plan.files.map((planned) => toCheck(planned, options.check)), ...skillLines];
+    if ((config.tools ?? []).length === 0) {
+        checks.push(skip("render", `No AI tools are listed in ${CONFIG_FILE}, so AGENTS.md is the only instructions file written.`));
+    }
+    const failures = count(checks, "fail");
+    if (options.quiet === true && failures === 0)
+        return 0;
+    out.log(`Peer AI render: ${config.project.name}`);
+    out.log("");
+    for (const line of formatChecks(checks))
+        out.log(line);
+    for (const step of plan.manual)
+        out.log(`  ! ${step}`);
+    out.log("");
+    if (options.check)
+        out.log(failures === 0 ? "Everything is up to date." : "Out of date: run peer-ai render.");
+    else if (failures > 0)
+        out.log("Some files couldn't be changed; see above.");
+    else if (!committed && plan.skills.some((skill) => skill.action !== "remove")) {
+        out.log("Done. Commit these files, so every clone and every tool gets them. The skills stay out of git: run peer-ai render after cloning.");
+    }
+    else
+        out.log("Done. Commit these files, so every clone and every tool gets them.");
+    return failures === 0 ? 0 : 1;
+}

package/dist/report.d.ts

@@ -0,0 +1,3 @@
+import { type Assessment } from "./assess.ts";
+import type { Stage } from "./init.ts";
+export declare function formatReport(assessment: Assessment, stage: Stage): string[];

package/dist/report.js

@@ -0,0 +1,93 @@
+// Turns an assessment into the report `peer-ai assess` prints: every item on the map, what the
+// project's stage still needs, what was inferred and should be confirmed, and compliance signals.
+import { MAP_ITEM_IDS } from "peer-ai-workflow";
+import { NEXT_STAGE, gaps } from "./assess.js";
+import { CONFIG_FILE } from "./detect.js";
+const SYMBOL = { present: "✓", partial: "◐", missing: "✗", "not-applicable": "–" };
+const WIDTH = Math.max(...MAP_ITEM_IDS.map((id) => id.length));
+function detail(item) {
+    const text = item.note ?? item.evidence?.join(", ") ?? "";
+    return text.length <= 90 ? text : `${text.slice(0, 89)}…`;
+}
+function list(names) {
+    return names.length <= 6 ? names.join(", ") : `${names.slice(0, 6).join(", ")} and ${String(names.length - 6)} more`;
+}
+export function formatReport(assessment, stage) {
+    const lines = [];
+    lines.push(`Peer AI assessment: ${assessment.name} (stage: ${stage})`);
+    lines.push(assessment.tracks.length === 0
+        ? "No parts found yet."
+        : `${String(assessment.tracks.length)} ${assessment.tracks.length === 1 ? "part" : "parts"}: ${list(assessment.tracks.map((track) => `${track.id} (${track.kind})`))}`);
+    lines.push("");
+    for (const id of MAP_ITEM_IDS) {
+        const item = assessment.items[id];
+        const text = detail(item);
+        lines.push(`  ${SYMBOL[item.status]} ${id.padEnd(WIDTH)}${text === "" ? "" : `  ${text}`}`.trimEnd());
+    }
+    lines.push("");
+    const needed = gaps(assessment, stage);
+    if (stage === "prototype")
+        lines.push("Nothing is required at the prototype stage.");
+    else if (needed.length === 0)
+        lines.push(`Everything the ${stage} stage needs is in place.`);
+    else {
+        lines.push(`Needed for ${stage} (${String(needed.length)}):`);
+        for (const id of needed)
+            lines.push(`  ${SYMBOL[assessment.items[id].status]} ${id}`);
+    }
+    const next = NEXT_STAGE[stage];
+    if (next !== undefined) {
+        const later = gaps(assessment, next).filter((id) => !needed.includes(id));
+        if (later.length > 0)
+            lines.push(`Later, for ${next}: ${later.join(", ")}.`);
+    }
+    if (assessment.legacyPlaybook) {
+        lines.push("");
+        lines.push("Left out: the peer-ai/ folder, a copy of the v0 playbook that 1.0 replaces.");
+    }
+    const inferred = MAP_ITEM_IDS.filter((id) => assessment.items[id].inferred === true);
+    if (inferred.length > 0) {
+        lines.push("");
+        lines.push(`Inferred from the code, not a document; check these: ${inferred.join(", ")}.`);
+    }
+    if (assessment.suggestedTraits.length > 0) {
+        lines.push("");
+        lines.push(`Traits to consider, each switching on extra rules. Add the ones that fit to project.traits in ${CONFIG_FILE}:`);
+        for (const { trait, evidence } of assessment.suggestedTraits)
+            lines.push(`  ${trait}: ${evidence}`);
+    }
+    if (assessment.suggestedProfiles.length > 0) {
+        lines.push("");
+        lines.push(`Stack profiles to consider, each with the tools that enforce its rules. Add the ones that fit to standards.profiles in ${CONFIG_FILE}:`);
+        for (const { profile, evidence } of assessment.suggestedProfiles)
+            lines.push(`  ${profile}: ${evidence}`);
+    }
+    if (assessment.suggestedStacks.length > 0) {
+        lines.push("");
+        lines.push(`Stacks to add to tracks in ${CONFIG_FILE}, so each stack profile applies only to the parts it fits:`);
+        for (const { track, stack } of assessment.suggestedStacks) {
+            lines.push(`  ${track}: "stack": ${JSON.stringify(stack)}`);
+        }
+    }
+    const { personalData, cardData, paymentProviders } = assessment.signals;
+    if (personalData.length + cardData.length + paymentProviders.length > 0) {
+        lines.push("");
+        lines.push("Compliance signals:");
+        if (personalData.length > 0) {
+            const first = personalData[0]?.file ?? "";
+            lines.push(`  Personal data in ${String(personalData.length)} fields: ${list(personalData.map((f) => f.name))} (first seen in ${first}).`);
+        }
+        if (cardData.length > 0) {
+            const first = cardData[0]?.file ?? "";
+            lines.push(`  Card-related names in the schema: ${list(cardData.map((f) => f.name))} (first seen in ${first}). Check that only the last four digits and a payment provider's token are stored: never a full card number or a CVV.`);
+        }
+        if (paymentProviders.length > 0)
+            lines.push(`  Payment providers: ${paymentProviders.join(", ")}.`);
+        const packs = [
+            ...(cardData.length > 0 || paymentProviders.length > 0 ? ["pci-dss"] : []),
+            ...(personalData.length > 0 ? ["the data protection law where you operate, such as ndpa or gdpr"] : []),
+        ];
+        lines.push(`  Rule packs to consider: ${packs.join("; ")}.`);
+    }
+    return lines;
+}