@tenphi/harnesspm 0.0.0-snapshot.376310a

package/dist/outputs.js

@@ -0,0 +1,453 @@
+// Repository outputs (spec 4.2, 4.3, 4.6): a plan, then apply it or compare it.
+import { createHash } from 'node:crypto';
+import { spawnSync } from 'node:child_process';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { caller, harnesspmHome } from './added.js';
+import { applyEntries, desiredEntries, tomlTables, trustOf } from './exec-outputs.js';
+import { claudeJsonFile } from './homes.js';
+import { parseFrontmatter } from './frontmatter.js';
+import { buildLock, LOCK_FILE, patchDrift, readLock, serializeLock } from './lock.js';
+import { alwaysOnText, extractBlock, hasClaudeImport, removeBlock, renderBlock, renderSections, sectionsFor, tomlString, upsertBlock, withClaudeImport, wrapBlock, } from './render.js';
+import { headings } from './sections.js';
+import { NPX_ANY, NPX_LOCAL, ensureDir, exists, gitExcludeFile, isDir, isFile, isSymlink, linkIfChanged, readText, readTextIfExists, realpath, relPosix, writeIfChanged, } from './util.js';
+export const STATE_DIR = path.join('node_modules', '.harnesspm');
+const TEAM_SECTION = ['# BEGIN harnesspm (generated by `harnesspm sync`; per-machine outputs)', '# END harnesspm'];
+const ADDED_SECTION = ['# BEGIN harnesspm: added harnesses (generated by `harnesspm sync`; per-machine outputs)', '# END harnesspm: added harnesses'];
+const CODEX_MARKER = '# Generated by `harnesspm sync` for added harnesses. Do not edit.';
+function repoSlug(projectDir) {
+    return `${path.basename(projectDir)}-${createHash('sha256').update(projectDir).digest('hex').slice(0, 8)}`;
+}
+function isTracked(projectDir, rel) {
+    return spawnSync('git', ['ls-files', '--error-unmatch', rel], { cwd: projectDir, encoding: 'utf8' }).status === 0;
+}
+function docsIndexText(dir, display) {
+    const lines = ['# Docs', ''];
+    const walk = (current) => {
+        for (const entry of fs.readdirSync(current, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+            const full = path.join(current, entry.name);
+            if (entry.isDirectory())
+                walk(full);
+            else if (/\.mdx?$/.test(entry.name)) {
+                const { data, body } = parseFrontmatter(readText(full), full);
+                const first = headings(body.split('\n')).find((h) => h.level === 1);
+                const title = typeof data['title'] === 'string' ? data['title'] : (first?.text ?? entry.name.replace(/\.mdx?$/, ''));
+                const description = typeof data['description'] === 'string' ? `: ${data['description']}` : '';
+                lines.push(`- [${title}](${display(full)})${description}`);
+            }
+        }
+    };
+    walk(dir);
+    return `${lines.join('\n')}\n`;
+}
+const isRepoAdded = (pkg) => pkg.layer === 'added' && (pkg.scope === 'local' || pkg.entry === true);
+export const isUserLevel = (pkg) => pkg.layer === 'added' && pkg.scope === 'user' && !pkg.entry;
+/**
+ * Paths that outputs show: stable package paths for dependencies, project-relative paths inside the
+ * project, absolute paths elsewhere. Generated docs indexes are added to `generated`.
+ */
+export function pathTools(res, generatedRoot, generated) {
+    const projectDir = res.projectDir;
+    const show = (abs) => (abs.startsWith(projectDir + path.sep) ? relPosix(projectDir, abs) : abs);
+    const display = (file) => {
+        let best;
+        for (const pkg of res.packages) {
+            if (pkg.layer !== 'dependencies')
+                continue;
+            if ((file === pkg.dir || file.startsWith(pkg.dir + path.sep)) && (!best || pkg.dir.length > best.dir.length))
+                best = pkg;
+        }
+        if (best)
+            return relPosix(projectDir, path.join(projectDir, STATE_DIR, 'pkgs', best.name, path.relative(best.dir, file)));
+        return show(file);
+    };
+    const generatedRule = (rule) => path.join(generatedRoot(rule.pkg), 'rules', rule.pkg.plugin, `${rule.name}.md`);
+    const paths = {
+        rule: (rule) => (rule.patches.length > 0 ? show(generatedRule(rule)) : display(rule.source)),
+        docsIndex: (pkg) => {
+            const docs = res.docs.find((d) => d.pkg === pkg);
+            if (!docs)
+                return undefined;
+            const llms = path.join(docs.dir, 'llms.txt');
+            if (isFile(llms))
+                return display(llms);
+            const file = path.join(generatedRoot(pkg), 'docs', pkg.plugin, 'llms.txt');
+            generated.set(file, docsIndexText(docs.dir, display));
+            return show(file);
+        },
+    };
+    return { show, display, generatedRule, paths };
+}
+/** The changes that added harnesses make to the repository's rules (spec 4.3, note 4). */
+function changesSection(team, full, rulePath) {
+    const added = new Set(full.packages.filter((p) => p.layer === 'added').map((p) => p.name));
+    const lines = [];
+    const texts = [];
+    for (const rule of team.rules) {
+        const changed = full.rules.find((r) => r.id === rule.id);
+        if (!changed) {
+            const by = full.excludedUnits.find((u) => u.id === rule.id)?.by;
+            if (by !== undefined && added.has(by))
+                lines.push(`- Ignore the rule ${rule.id} in AGENTS.md: ${by} turns it off on this machine.`);
+            continue;
+        }
+        if (changed.text === rule.text)
+            continue;
+        const by = [changed.replacedBy?.by, ...changed.patches.map((p) => p.by)].filter((b) => b !== undefined && added.has(b));
+        const who = [...new Set(by)].join(', ');
+        if (changed.activation === 'always')
+            texts.push(alwaysOnText(changed, `${rule.id}, changed by ${who}; use this text instead of the one in AGENTS.md`));
+        else
+            lines.push(`- Instead of the rule ${rule.id} in AGENTS.md, read ${rulePath(changed)} (changed by ${who})`);
+    }
+    if (lines.length === 0 && texts.length === 0)
+        return undefined;
+    return ["## Changes to this repository's rules", ...texts, ...(lines.length > 0 ? [lines.join('\n')] : [])].join('\n\n');
+}
+/**
+ * `team` is the dependency and project layers alone, for committed outputs. `full` adds the added
+ * harnesses, for per-machine outputs. Without `team`, only the outputs of added harnesses change.
+ */
+export function computePlan(team, full) {
+    const projectDir = full.projectDir;
+    const warnings = [];
+    const generated = new Map();
+    const links = new Map();
+    const teamExcludes = new Set([`/${STATE_DIR.split(path.sep).join('/')}/`]);
+    const addedExcludes = new Set();
+    const teamGen = path.join(projectDir, STATE_DIR);
+    const addedGen = path.join(harnesspmHome(), 'generated', repoSlug(projectDir));
+    const tools = pathTools(full, (pkg) => (pkg.layer === 'added' ? addedGen : teamGen), generated);
+    if (team)
+        for (const pkg of full.packages)
+            if (pkg.layer === 'dependencies')
+                links.set(path.join(projectDir, STATE_DIR, 'pkgs', pkg.name), pkg.dir);
+    const stable = (file) => path.resolve(projectDir, tools.display(file));
+    const seenRoots = new Set();
+    const roots = [path.join(projectDir, '.claude', 'skills'), path.join(projectDir, '.agents', 'skills')].filter((root) => {
+        const real = isDir(root) ? realpath(root) : root;
+        if (seenRoots.has(real))
+            return false;
+        seenRoots.add(real);
+        return true;
+    });
+    const addLink = (linkPath, target, into) => {
+        if (exists(linkPath) && !isSymlink(linkPath)) {
+            warnings.push(`${relPosix(projectDir, linkPath)} exists and is not a harnesspm link; left as it is`);
+            return;
+        }
+        links.set(linkPath, target);
+        into.add(`/${relPosix(projectDir, linkPath)}`);
+    };
+    for (const skill of full.skills) {
+        if (isUserLevel(skill.pkg))
+            continue;
+        const added = skill.pkg.layer === 'added';
+        if (!added && !team)
+            continue;
+        for (const root of roots)
+            addLink(path.join(root, skill.name), added ? skill.dir : stable(skill.dir), added ? addedExcludes : teamExcludes);
+    }
+    // Generated rule files: patched rules that agents read from a file, with this machine's text.
+    for (const rule of full.rules) {
+        if (rule.activation === 'always' || isUserLevel(rule.pkg))
+            continue;
+        if (rule.pkg.layer !== 'added' && !team)
+            continue;
+        const teamPatched = (team?.rules.find((r) => r.id === rule.id)?.patches.length ?? 0) > 0;
+        if (rule.patches.length > 0 || teamPatched)
+            generated.set(tools.generatedRule(rule), rule.text);
+    }
+    // File-scoped team rules also get a native Claude Code rule (spec 4.3, note 3).
+    if (team) {
+        for (const rule of full.rules.filter((r) => r.activation === 'file' && r.pkg.layer !== 'added')) {
+            const changed = rule.text !== readText(rule.original);
+            const target = changed ? tools.generatedRule(rule) : stable(rule.source);
+            if (changed)
+                generated.set(target, rule.text);
+            addLink(path.join(projectDir, '.claude', 'rules', 'harnesspm', rule.pkg.plugin, `${rule.name}.md`), target, teamExcludes);
+        }
+    }
+    let committed;
+    let lock = readLock(projectDir);
+    if (team) {
+        const previous = lock;
+        lock = buildLock(team, previous);
+        warnings.push(...patchDrift(previous, lock));
+        const teamGenerated = new Map();
+        const teamLock = lock;
+        const teamTools = pathTools(team, () => teamGen, teamGenerated);
+        const prefix = (pkg) => (trustOf(pkg, team, teamLock).trusted ? NPX_LOCAL : undefined);
+        // The root block holds what the root reaches and what every workspace shares (spec 3.6, 4.5).
+        const keys = team.workspaces.map((ws) => ws.key);
+        const shared = (pkg) => pkg.members.has('') || (keys.length > 0 && keys.every((k) => pkg.members.has(k)));
+        const rootContent = renderSections(sectionsFor(team, team.packages.filter(shared), teamTools.paths, prefix), teamTools.paths);
+        const block = wrapBlock(rootContent !== '' ? rootContent : 'No harness units yet.');
+        const workspaces = [];
+        for (const ws of team.workspaces) {
+            // Paths in a workspace's block are relative to its folder.
+            const toWs = (p) => (path.isAbsolute(p) ? p : relPosix(ws.dir, path.join(projectDir, p)));
+            const wsPaths = {
+                rule: (rule) => toWs(teamTools.paths.rule(rule)),
+                docsIndex: (pkg) => {
+                    const index = teamTools.paths.docsIndex(pkg);
+                    return index === undefined ? undefined : toWs(index);
+                },
+            };
+            const content = renderSections(sectionsFor(team, team.packages.filter((p) => !shared(p) && p.members.has(ws.key)), wsPaths, prefix), wsPaths);
+            const agentsFile = path.join(ws.dir, 'AGENTS.md');
+            const existing = readTextIfExists(agentsFile);
+            const agentsMd = content !== '' ? upsertBlock(existing, wrapBlock(content)) : extractBlock(existing) !== undefined ? removeBlock(existing) : existing;
+            const claudeFile = path.join(ws.dir, 'CLAUDE.md');
+            const claudeMd = content !== '' ? withClaudeImport(readTextIfExists(claudeFile)) : readTextIfExists(claudeFile);
+            workspaces.push({ dir: ws.dir, agentsMd, claudeMd });
+        }
+        for (const [file, content] of teamGenerated)
+            if (!generated.has(file))
+                generated.set(file, content);
+        committed = {
+            agentsMd: upsertBlock(readTextIfExists(path.join(projectDir, 'AGENTS.md')), block),
+            claudeMd: withClaudeImport(readTextIfExists(path.join(projectDir, 'CLAUDE.md'))),
+            lock: serializeLock(lock),
+            workspaces,
+        };
+    }
+    // Added harnesses with local scope, and every harness's entry for this repository (spec 4.3).
+    let content = renderSections(sectionsFor(full, full.packages.filter(isRepoAdded), tools.paths, () => NPX_ANY), tools.paths);
+    const changes = team ? changesSection(team, full, (rule) => tools.paths.rule(rule)) : undefined;
+    if (changes !== undefined)
+        content = content !== '' ? `${content}\n\n${changes}` : changes;
+    const localFile = path.join(projectDir, 'CLAUDE.local.md');
+    let localMd;
+    if (content !== '' && isTracked(projectDir, 'CLAUDE.local.md')) {
+        warnings.push('CLAUDE.local.md is tracked by git, so harnesspm does not write added harnesses into it');
+        localMd = readTextIfExists(localFile);
+    }
+    else if (content !== '') {
+        // CLAUDE.local.md counts as a CLAUDE.md: without one, Claude Code would stop reading AGENTS.md (spec 4.3, note 1).
+        const needsImport = !isFile(path.join(projectDir, 'CLAUDE.md')) && isFile(path.join(projectDir, 'AGENTS.md'));
+        localMd = upsertBlock(readTextIfExists(localFile), wrapBlock(content));
+        if (needsImport && !hasClaudeImport(localMd))
+            localMd = `@AGENTS.md\n\n${localMd}`;
+        addedExcludes.add('/CLAUDE.local.md');
+    }
+    else {
+        // Remove only harnesspm's own block. A file without one stays as it is.
+        const existing = readTextIfExists(localFile);
+        localMd = extractBlock(existing) === undefined ? existing : removeBlock(existing, /^\s*(@AGENTS\.md)?\s*$/);
+    }
+    // Codex files are per machine unless the repository commits its own .codex/ (spec 4.3, note 2).
+    const codexFile = path.join(projectDir, '.codex', 'config.toml');
+    const codexTracked = ['.codex/config.toml', '.codex/hooks.json', '.codex/rules'].some((rel) => isTracked(projectDir, rel));
+    const codexOurs = !codexTracked && (readTextIfExists(codexFile) ?? CODEX_MARKER).startsWith(CODEX_MARKER);
+    if (!codexOurs)
+        warnings.push('.codex/ belongs to the repository, so harnesspm writes nothing there and Codex misses some units. See `harnesspm status`.');
+    const claudeOurs = !isTracked(projectDir, '.claude/settings.local.json');
+    if (!claudeOurs)
+        warnings.push('.claude/settings.local.json is tracked by git, so harnesspm writes no hooks or permissions there');
+    // Executable units and sub-agents (spec 4.3, chapter 5), with trust (spec 6.2).
+    const trust = (pkg) => trustOf(pkg, full, lock);
+    const agentDirs = { claudeAgents: path.join(projectDir, '.claude', 'agents'), codexAgents: path.join(projectDir, '.codex', 'agents') };
+    const teamExec = team ? desiredEntries(full, new Set(full.packages.filter((p) => p.layer !== 'added')), trust, { ...agentDirs, npx: () => NPX_LOCAL }) : undefined;
+    const addedExec = desiredEntries(full, new Set(full.packages.filter(isRepoAdded)), trust, { ...agentDirs, npx: () => NPX_ANY });
+    warnings.push(...(teamExec?.warnings ?? []), ...addedExec.warnings);
+    return {
+        ...(committed ? { committed } : {}),
+        generated,
+        generatedRoots: [...(team ? [path.join(teamGen, 'rules'), path.join(teamGen, 'docs')] : []), addedGen],
+        links,
+        ...(team ? { teamExcludes: [...teamExcludes].sort() } : {}),
+        addedExcludes: [...addedExcludes].sort(),
+        localMd,
+        codexInstructions: content,
+        codexOurs,
+        claudeOurs,
+        exec: { ...(teamExec ? { team: teamExec } : {}), added: addedExec },
+        warnings,
+    };
+}
+function sectionRange(lines, marks) {
+    const start = lines.indexOf(marks[0]);
+    if (start < 0)
+        return undefined;
+    const end = lines.indexOf(marks[1], start);
+    return end < 0 ? undefined : [start, end];
+}
+function readSection(text, marks) {
+    const lines = (text ?? '').split('\n');
+    const range = sectionRange(lines, marks);
+    return range ? lines.slice(range[0] + 1, range[1]).filter((l) => l.startsWith('/')) : [];
+}
+function writeSection(text, marks, entries) {
+    const lines = (text ?? '').split('\n');
+    const range = sectionRange(lines, marks);
+    const section = entries.length > 0 ? [marks[0], ...entries, marks[1]] : [];
+    if (range)
+        lines.splice(range[0], range[1] - range[0] + 1, ...section);
+    else if (section.length > 0) {
+        while (lines.length > 0 && lines[lines.length - 1] === '')
+            lines.pop();
+        if (lines.length > 0)
+            lines.push('');
+        lines.push(...section);
+    }
+    while (lines.length > 0 && lines[lines.length - 1] === '')
+        lines.pop();
+    return lines.length > 0 ? `${lines.join('\n')}\n` : '';
+}
+function unlinkAndPrune(target, stopAt) {
+    fs.unlinkSync(target);
+    for (let dir = path.dirname(target); dir.startsWith(stopAt + path.sep); dir = path.dirname(dir)) {
+        try {
+            fs.rmdirSync(dir);
+        }
+        catch {
+            break;
+        }
+    }
+}
+export function repoStateFile(projectDir) {
+    const result = spawnSync('git', ['rev-parse', '--git-path', 'harnesspm/state.json'], { cwd: projectDir, encoding: 'utf8' });
+    const p = result.status === 0 ? result.stdout.trim() : path.join('.git', 'harnesspm', 'state.json');
+    return path.isAbsolute(p) ? p : path.join(projectDir, p);
+}
+export function repoTargets(projectDir, plan) {
+    return {
+        claudeSettings: path.join(projectDir, '.claude', 'settings.local.json'),
+        claudeJson: claudeJsonFile(),
+        claudeProject: projectDir,
+        codexHooks: path.join(projectDir, '.codex', 'hooks.json'),
+        codexRules: path.join(projectDir, '.codex', 'rules', 'harnesspm.rules'),
+        stateFile: repoStateFile(projectDir),
+        writeClaude: plan.claudeOurs,
+        writeCodex: plan.codexOurs,
+    };
+}
+/** Writes the plan. Returns the project-relative paths that changed and the entries held back. */
+export function applyPlan(projectDir, plan) {
+    const changed = [];
+    const held = [];
+    const note = (file, did) => {
+        if (did)
+            changed.push(relPosix(projectDir, file));
+    };
+    for (const root of plan.generatedRoots)
+        fs.rmSync(root, { recursive: true, force: true });
+    for (const [file, content] of plan.generated)
+        writeIfChanged(file, content);
+    for (const [linkPath, target] of plan.links)
+        note(linkPath, linkIfChanged(linkPath, target));
+    // Executable entries in shared files, before the excludes so that every written file is listed.
+    const widen = caller() !== 'model';
+    const targets = repoTargets(projectDir, plan);
+    const teamExcludes = plan.teamExcludes ? [...plan.teamExcludes] : undefined;
+    const addedExcludes = [...plan.addedExcludes];
+    let codexMcp = {};
+    for (const [group, entries, into] of [['team', plan.exec.team, teamExcludes], ['added', plan.exec.added, addedExcludes]]) {
+        if (!entries)
+            continue;
+        const applied = applyEntries(group, entries, targets, widen);
+        for (const file of applied.changed)
+            changed.push(file.startsWith(projectDir + path.sep) ? relPosix(projectDir, file) : file);
+        held.push(...applied.held);
+        codexMcp = applied.codexMcp;
+        for (const file of applied.files)
+            if (file.startsWith(projectDir + path.sep))
+                into?.push(`/${relPosix(projectDir, file)}`);
+    }
+    // .codex/config.toml: developer_instructions and MCP servers.
+    const codexFile = path.join(projectDir, '.codex', 'config.toml');
+    if (plan.codexOurs) {
+        const parts = [
+            ...(plan.codexInstructions !== '' ? [`developer_instructions = ${tomlString(plan.codexInstructions)}`] : []),
+            ...(Object.keys(codexMcp).length > 0 ? [tomlTables('mcp_servers', codexMcp)] : []),
+        ];
+        if (parts.length > 0) {
+            note(codexFile, writeIfChanged(codexFile, `${CODEX_MARKER}\n${parts.join('\n\n')}\n`));
+            addedExcludes.push('/.codex/config.toml');
+        }
+        else if (isFile(codexFile)) {
+            fs.rmSync(codexFile);
+            changed.push('.codex/config.toml');
+        }
+    }
+    for (const dir of [path.join(projectDir, '.codex', 'rules'), path.join(projectDir, '.codex', 'agents'), path.join(projectDir, '.codex'), path.join(projectDir, '.claude', 'agents')]) {
+        try {
+            fs.rmdirSync(dir);
+        }
+        catch {
+            // Not empty, or not there.
+        }
+    }
+    const excludeFile = gitExcludeFile(projectDir);
+    if (excludeFile) {
+        const before = readTextIfExists(excludeFile);
+        const prevTeam = readSection(before, TEAM_SECTION);
+        const prevAdded = readSection(before, ADDED_SECTION);
+        const keep = new Set([...(teamExcludes ?? prevTeam), ...addedExcludes]);
+        // Remove links from the last sync that this sync no longer writes.
+        for (const entry of new Set([...prevTeam, ...prevAdded])) {
+            const target = path.join(projectDir, entry);
+            if (keep.has(entry) || !isSymlink(target))
+                continue;
+            unlinkAndPrune(target, projectDir);
+            changed.push(entry.slice(1));
+        }
+        let text = before;
+        const sorted = (list) => [...new Set(list)].sort();
+        if (teamExcludes)
+            text = writeSection(text, TEAM_SECTION, sorted(teamExcludes));
+        text = writeSection(text, ADDED_SECTION, sorted(addedExcludes));
+        ensureDir(path.dirname(excludeFile));
+        writeIfChanged(excludeFile, text);
+    }
+    if (plan.committed) {
+        note(path.join(projectDir, 'AGENTS.md'), writeIfChanged(path.join(projectDir, 'AGENTS.md'), plan.committed.agentsMd));
+        note(path.join(projectDir, 'CLAUDE.md'), writeIfChanged(path.join(projectDir, 'CLAUDE.md'), plan.committed.claudeMd));
+        note(path.join(projectDir, LOCK_FILE), writeIfChanged(path.join(projectDir, LOCK_FILE), plan.committed.lock));
+        for (const ws of plan.committed.workspaces) {
+            const agentsFile = path.join(ws.dir, 'AGENTS.md');
+            if (ws.agentsMd !== undefined)
+                note(agentsFile, writeIfChanged(agentsFile, ws.agentsMd));
+            else if (isFile(agentsFile)) {
+                fs.rmSync(agentsFile);
+                changed.push(relPosix(projectDir, agentsFile));
+            }
+            if (ws.claudeMd !== undefined)
+                note(path.join(ws.dir, 'CLAUDE.md'), writeIfChanged(path.join(ws.dir, 'CLAUDE.md'), ws.claudeMd));
+        }
+    }
+    const localFile = path.join(projectDir, 'CLAUDE.local.md');
+    if (plan.localMd !== undefined)
+        note(localFile, writeIfChanged(localFile, plan.localMd));
+    else if (isFile(localFile)) {
+        fs.rmSync(localFile);
+        changed.push('CLAUDE.local.md');
+    }
+    return { changed, held };
+}
+/** Compares the committed outputs with the plan (spec 6.4). Returns the differences. */
+export function checkPlan(projectDir, plan) {
+    if (!plan.committed)
+        return ['the dependencies are not installed, so the committed outputs cannot be checked'];
+    const problems = [];
+    const agents = readTextIfExists(path.join(projectDir, 'AGENTS.md'));
+    if (extractBlock(agents) !== extractBlock(plan.committed.agentsMd))
+        problems.push('AGENTS.md: the harnesspm block is out of date');
+    if (!hasClaudeImport(readTextIfExists(path.join(projectDir, 'CLAUDE.md'))))
+        problems.push('CLAUDE.md: the @AGENTS.md line is missing');
+    if (readTextIfExists(path.join(projectDir, LOCK_FILE)) !== plan.committed.lock)
+        problems.push(`${LOCK_FILE} is out of date`);
+    for (const ws of plan.committed.workspaces) {
+        const rel = relPosix(projectDir, path.join(ws.dir, 'AGENTS.md'));
+        if (extractBlock(readTextIfExists(path.join(ws.dir, 'AGENTS.md'))) !== extractBlock(ws.agentsMd))
+            problems.push(`${rel}: the harnesspm block is out of date`);
+    }
+    const lock = JSON.parse(plan.committed.lock);
+    for (const [name, entry] of Object.entries(lock.packages)) {
+        if (entry.approved !== undefined && entry.approved !== entry.version) {
+            problems.push(`${name} ${entry.version} is pinned and not approved (approved: ${entry.approved}). Run \`npx harnesspm approve ${name}\`.`);
+        }
+    }
+    return problems;
+}

package/dist/render.js

@@ -0,0 +1,119 @@
+// Managed blocks (spec 4.6): AGENTS.md for the team, CLAUDE.local.md and user-level files for added harnesses.
+import { demoteHeadings, headings } from './sections.js';
+export const BLOCK_BEGIN = '<!-- BEGIN:harnesspm — generated by `harnesspm sync`. Do not edit. To change a rule, run `npx harnesspm why <ID>`. -->';
+export const BLOCK_END = '<!-- END:harnesspm -->';
+const BEGIN_PREFIX = '<!-- BEGIN:harnesspm';
+function withoutTitle(body) {
+    const lines = body.split('\n');
+    const first = headings(lines)[0];
+    if (first && first.level === 1)
+        lines.splice(first.line, 1);
+    return lines.join('\n').trim();
+}
+export function packageHeading(pkg) {
+    if (pkg.layer === 'project')
+        return `## ${pkg.name} (this project)`;
+    if (pkg.layer === 'added') {
+        const spec = pkg.added?.source.spec ?? pkg.name;
+        if (pkg.entry)
+            return `## ${pkg.plugin}: entry for this repository (${spec})`;
+        return `## ${pkg.plugin} (${spec}, ${pkg.scope} scope)`;
+    }
+    return `## ${pkg.name} ${pkg.version}${pkg.via !== undefined ? ` (via ${pkg.via})` : ''}`;
+}
+export function alwaysOnText(rule, label = rule.id) {
+    const body = demoteHeadings(withoutTitle(rule.body), 2);
+    return `### ${rule.title} (${label})${body !== '' ? `\n\n${body}` : ''}`;
+}
+export function pointerLine(rule, file) {
+    if (rule.activation === 'file') {
+        const globs = (rule.paths ?? []).map((p) => `\`${p}\``).join(', ');
+        const description = rule.description !== undefined ? ` — ${rule.description}` : '';
+        return `- When editing ${globs}, read ${file}${description} (${rule.id})`;
+    }
+    return `- ${rule.description}: read ${file} (${rule.id})`;
+}
+export function renderSections(sections, paths) {
+    const out = [];
+    for (const section of sections) {
+        const parts = [section.heading, ...(section.intro ?? [])];
+        for (const rule of section.rules.filter((r) => r.activation === 'always'))
+            parts.push(alwaysOnText(rule));
+        const pointers = section.rules.filter((r) => r.activation !== 'always').map((r) => pointerLine(r, paths.rule(r)));
+        if (section.docsIndex)
+            pointers.push(`- Docs: ${section.docsIndex.path} (${section.docsIndex.id})`);
+        pointers.push(...(section.scripts ?? []));
+        if (pointers.length > 0)
+            parts.push(pointers.join('\n'));
+        if (parts.length > 1)
+            out.push(parts.join('\n\n'));
+    }
+    return out.join('\n\n');
+}
+/** `runPrefix` returns the command prefix for a trusted package's scripts, or undefined to list none. */
+export function sectionsFor(res, packages, paths, runPrefix = () => undefined) {
+    return packages.map((pkg) => {
+        const index = paths.docsIndex(pkg);
+        const prefix = runPrefix(pkg);
+        const scripts = prefix === undefined
+            ? []
+            : res.scripts.filter((s) => s.pkg === pkg && s.description !== undefined).map((s) => `- Script: \`${prefix} run ${pkg.plugin}:${s.name}\` — ${s.description} (${s.id})`);
+        return {
+            heading: packageHeading(pkg),
+            rules: res.rules.filter((r) => r.pkg === pkg),
+            ...(index !== undefined ? { docsIndex: { path: index, id: `${pkg.plugin}:docs` } } : {}),
+            ...(scripts.length > 0 ? { scripts } : {}),
+        };
+    });
+}
+export function wrapBlock(content) {
+    return `${BLOCK_BEGIN}\n${content}\n${BLOCK_END}`;
+}
+/** The committed block: the dependency and project layers. */
+export function renderBlock(res, paths, runPrefix) {
+    const content = renderSections(sectionsFor(res, res.packages, paths, runPrefix), paths);
+    return wrapBlock(content !== '' ? content : 'No harness units yet.');
+}
+/** Puts the block into a Markdown file. Text outside the block never changes. */
+export function upsertBlock(existing, block) {
+    if (existing === undefined || existing.trim() === '')
+        return `${block}\n`;
+    const start = existing.indexOf(BEGIN_PREFIX);
+    const end = existing.indexOf(BLOCK_END, start);
+    if (start >= 0 && end > start)
+        return existing.slice(0, start) + block + existing.slice(end + BLOCK_END.length);
+    return `${existing.replace(/\s+$/, '')}\n\n${block}\n`;
+}
+/** Removes the block. Returns undefined when nothing else is left in the file. */
+export function removeBlock(existing, leftover = /^\s*$/) {
+    if (existing === undefined)
+        return undefined;
+    const start = existing.indexOf(BEGIN_PREFIX);
+    const end = existing.indexOf(BLOCK_END, start);
+    const rest = start >= 0 && end > start ? existing.slice(0, start).replace(/\s+$/, '') + existing.slice(end + BLOCK_END.length) : existing;
+    if (leftover.test(rest))
+        return undefined;
+    return `${rest.replace(/\s+$/, '')}\n`;
+}
+export function extractBlock(text) {
+    if (text === undefined)
+        return undefined;
+    const start = text.indexOf(BEGIN_PREFIX);
+    const end = text.indexOf(BLOCK_END, start);
+    return start >= 0 && end > start ? text.slice(start, end + BLOCK_END.length) : undefined;
+}
+export const CLAUDE_IMPORT = '@AGENTS.md';
+export function hasClaudeImport(text) {
+    return text !== undefined && /^@AGENTS\.md[ \t]*$/m.test(text);
+}
+export function withClaudeImport(existing) {
+    if (existing === undefined || existing.trim() === '')
+        return `${CLAUDE_IMPORT}\n`;
+    if (hasClaudeImport(existing))
+        return existing;
+    return `${CLAUDE_IMPORT}\n\n${existing}`;
+}
+/** TOML basic multi-line string. */
+export function tomlString(text) {
+    return `"""\n${text.replace(/\\/g, '\\\\').replace(/"""/g, '""\\"')}\n"""`;
+}