@tenphi/harnesspm 0.0.0-stage → 0.1.0

package/dist/exec-outputs.js

@@ -0,0 +1,360 @@
+// Executable outputs (spec 4.3, 4.4, 5.2–5.4) with trust (spec 6.2) and ownership of shared files (spec 4.7).
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { stringify } from 'yaml';
+import { AGENTS, WIDENING_AGENT_KEYS } from './exec-units.js';
+import { tomlString } from './render.js';
+import { ensureDir, isFile, isRecord, readJsonIfExists, readTextIfExists, writeIfChanged } from './util.js';
+/** Trust of a package's executable units (spec 6.2). The project and added harnesses are trusted. */
+export function trustOf(pkg, res, lock) {
+    if (pkg.layer !== 'dependencies')
+        return { trusted: true };
+    const value = res.config.trust[pkg.name];
+    if (value === true)
+        return { trusted: true };
+    if (value === 'pin') {
+        const approved = lock?.packages[pkg.name]?.approved;
+        if (approved === undefined || approved === pkg.version)
+            return { trusted: true };
+        return { trusted: false, reason: `version ${pkg.version} is not approved (approved: ${approved}); run \`npx harnesspm approve ${pkg.name}\`` };
+    }
+    return { trusted: false, reason: `not trusted; add it to "trust" in harnesspm.json` };
+}
+export function emptyEntries() {
+    return { claude: { allow: [], deny: [], ask: [], hooks: [], mcp: {} }, codex: { hooks: [], rules: [], mcp: {} }, agentFiles: new Map(), pending: [], warnings: [] };
+}
+function tomlValue(value) {
+    if (typeof value === 'string')
+        return JSON.stringify(value);
+    if (typeof value === 'number' || typeof value === 'boolean')
+        return String(value);
+    if (Array.isArray(value)) {
+        const items = value.map(tomlValue);
+        return items.every((i) => i !== undefined) ? `[${items.join(', ')}]` : undefined;
+    }
+    if (isRecord(value)) {
+        const items = Object.entries(value).map(([k, v]) => [k, tomlValue(v)]);
+        return items.every(([, v]) => v !== undefined) ? `{ ${items.map(([k, v]) => `${JSON.stringify(k)} = ${v}`).join(', ')} }` : undefined;
+    }
+    return undefined;
+}
+export function tomlTables(prefix, tables) {
+    return Object.entries(tables)
+        .map(([name, table]) => {
+        const lines = Object.entries(table).flatMap(([k, v]) => {
+            const value = tomlValue(v);
+            return value === undefined ? [] : [`${k} = ${value}`];
+        });
+        return `[${prefix}.${JSON.stringify(name)}]\n${lines.join('\n')}`;
+    })
+        .join('\n\n');
+}
+/** Words of a command prefix, for Claude Code's Bash rules. */
+const bashRule = (words) => `Bash(${words.join(' ')} *)`;
+const codexRule = (words, decision) => `prefix_rule(pattern = ${JSON.stringify(words)}, decision = "${decision}")`;
+/**
+ * The entries that `packages` ask for. `npx` is the command prefix: `npx harnesspm` where the project
+ * depends on harnesspm, `npx -y @tenphi/harnesspm` elsewhere. Allow rules use the same prefix as the commands.
+ */
+export function desiredEntries(res, packages, trust, where) {
+    const entries = emptyEntries();
+    const mine = (units) => units.filter((u) => packages.has(u.pkg));
+    const pendingCounts = new Map();
+    const pend = (pkg, what) => {
+        const counts = pendingCounts.get(pkg) ?? new Map();
+        counts.set(what, (counts.get(what) ?? 0) + 1);
+        pendingCounts.set(pkg, counts);
+    };
+    for (const skill of mine(res.skills))
+        if (trust(skill.pkg).trusted)
+            entries.claude.allow.push(`Skill(${skill.name})`);
+    for (const script of mine(res.scripts)) {
+        if (!trust(script.pkg).trusted) {
+            pend(script.pkg, 'script');
+            continue;
+        }
+        if (!script.allow)
+            continue;
+        const words = [...where.npx(script.pkg).split(' '), 'run', `${script.pkg.plugin}:${script.name}`];
+        // `Bash(<prefix> *)` also matches the command without arguments (observed with Claude Code 2.1.322).
+        entries.claude.allow.push(bashRule(words));
+        entries.codex.rules.push(codexRule(words, 'allow'));
+    }
+    for (const hook of mine(res.hooks)) {
+        if (!trust(hook.pkg).trusted) {
+            pend(hook.pkg, 'hook');
+            continue;
+        }
+        for (const agent of AGENTS) {
+            if (!(agent in hook.matchers))
+                continue;
+            const matcher = hook.matchers[agent];
+            const entry = {
+                event: hook.event,
+                ...(matcher !== undefined ? { matcher } : {}),
+                command: `${where.npx(hook.pkg)} run --agent ${agent} ${hook.pkg.plugin}:${hook.run}`,
+                ...(hook.timeout !== undefined ? { timeout: hook.timeout } : {}),
+            };
+            entries[agent].hooks.push(entry);
+        }
+    }
+    for (const server of mine(res.mcp)) {
+        if (!trust(server.pkg).trusted) {
+            pend(server.pkg, 'MCP server');
+            continue;
+        }
+        const name = `${server.pkg.plugin}-${server.name}`;
+        const type = server.config['type'];
+        for (const agent of AGENTS) {
+            let config;
+            if (type === 'stdio') {
+                const [command, ...prefix] = where.npx(server.pkg).split(' ');
+                config = { command, args: [...prefix, 'mcp', '--agent', agent, `${server.pkg.plugin}:${server.name}`] };
+                if (agent === 'claude')
+                    config = { type: 'stdio', ...config };
+            }
+            else if (agent === 'claude') {
+                config = { type: type === 'sse' ? 'sse' : 'http', url: server.config['url'], ...(isRecord(server.config['headers']) ? { headers: server.config['headers'] } : {}) };
+            }
+            else if (type === 'streamable-http') {
+                config = { url: server.config['url'], ...(isRecord(server.config['headers']) ? { http_headers: server.config['headers'] } : {}) };
+            }
+            else
+                entries.warnings.push(`${server.id}: Codex has no SSE transport, so the server is written for Claude Code only`);
+            if (config)
+                entries[agent].mcp[name] = config;
+        }
+        entries.claude.allow.push(`mcp__${name}`);
+    }
+    for (const perms of mine(res.permissions)) {
+        for (const words of perms.deny) {
+            entries.claude.deny.push(bashRule(words));
+            entries.codex.rules.push(codexRule(words, 'forbidden'));
+        }
+        for (const words of perms.ask) {
+            entries.claude.ask.push(bashRule(words));
+            entries.codex.rules.push(codexRule(words, 'prompt'));
+        }
+    }
+    // Sub-agents are text, but some agent-specific keys widen what the agent may do (spec 2.6).
+    for (const agentUnit of mine(res.agents)) {
+        const trusted = trust(agentUnit.pkg).trusted;
+        const keys = (agent) => {
+            const source = agent === 'claude' ? agentUnit.claude : agentUnit.codex;
+            const result = {};
+            for (const [key, value] of Object.entries(source)) {
+                if (!trusted && WIDENING_AGENT_KEYS[agent].includes(key))
+                    entries.warnings.push(`${agentUnit.id}: "${key}" is left out, because ${agentUnit.pkg.name} is not trusted`);
+                else
+                    result[key] = value;
+            }
+            return result;
+        };
+        const note = `Generated by harnesspm from ${agentUnit.id}. To change it, run \`npx harnesspm why ${agentUnit.id}\`.`;
+        const front = stringify({ name: agentUnit.name, description: agentUnit.description, ...keys('claude') }).trimEnd();
+        entries.agentFiles.set(path.join(where.claudeAgents, `${agentUnit.name}.md`), `---\n${front}\n---\n\n<!-- ${note} -->\n\n${agentUnit.body}\n`);
+        const codexKeys = Object.entries(keys('codex')).flatMap(([k, v]) => {
+            const value = tomlValue(v);
+            return value === undefined ? [] : [`${k} = ${value}`];
+        });
+        entries.agentFiles.set(path.join(where.codexAgents, `${agentUnit.name}.toml`), `# ${note}\nname = ${JSON.stringify(agentUnit.name)}\ndescription = ${JSON.stringify(agentUnit.description)}\n${codexKeys.map((l) => `${l}\n`).join('')}developer_instructions = ${tomlString(agentUnit.body)}\n`);
+    }
+    for (const [pkg, counts] of pendingCounts) {
+        const what = [...counts].map(([kind, n]) => `${n} ${kind}${n === 1 ? '' : 's'}`).join(', ');
+        entries.pending.push(`${pkg.name}: ${what} (${trust(pkg).reason})`);
+    }
+    return entries;
+}
+const emptyOwned = () => ({ claude: { allow: [], deny: [], ask: [], hooks: [], mcp: [] }, codex: { hooks: [], mcp: {}, rules: [] }, agentFiles: [] });
+function readOwned(stateFile) {
+    const raw = readJsonIfExists(stateFile);
+    return isRecord(raw) && isRecord(raw['exec']) ? raw['exec'] : {};
+}
+function writeOwned(stateFile, state) {
+    const raw = readJsonIfExists(stateFile);
+    const data = isRecord(raw) ? raw : {};
+    data['exec'] = state;
+    ensureDir(path.dirname(stateFile));
+    writeIfChanged(stateFile, `${JSON.stringify(data, null, 2)}\n`);
+}
+const hookKey = (h) => `${h.event}\u0000${h.matcher ?? ''}\u0000${h.command}`;
+/** Keeps what a model run may keep: entries it already had. Returns the entries and what is held back. */
+function limit(wanted, had, key, widen) {
+    if (widen)
+        return { kept: wanted, held: [] };
+    const before = new Set(had.map(key));
+    return { kept: wanted.filter((w) => before.has(key(w))), held: wanted.filter((w) => !before.has(key(w))) };
+}
+/** Replaces the owned hook entries in an agent's hooks object. */
+function mergeHooks(hooks, previous, next) {
+    const drop = new Set(previous.map(hookKey));
+    const result = {};
+    for (const [event, groups] of Object.entries(hooks)) {
+        const kept = groups
+            .map((g) => ({ ...g, hooks: (g.hooks ?? []).filter((h) => !drop.has(hookKey({ event, ...(g.matcher !== undefined ? { matcher: g.matcher } : {}), command: h.command ?? '' }))) }))
+            .filter((g) => g.hooks.length > 0);
+        if (kept.length > 0)
+            result[event] = kept;
+    }
+    for (const entry of next) {
+        const list = (result[entry.event] ??= []);
+        list.push({ ...(entry.matcher !== undefined ? { matcher: entry.matcher } : {}), hooks: [{ type: 'command', command: entry.command, ...(entry.timeout !== undefined ? { timeout: entry.timeout } : {}) }] });
+    }
+    return result;
+}
+function editJson(file, edit) {
+    const raw = readJsonIfExists(file);
+    const data = isRecord(raw) ? raw : {};
+    const before = JSON.stringify(data);
+    edit(data);
+    if (JSON.stringify(data) === before)
+        return false;
+    if (Object.keys(data).length === 0) {
+        fs.rmSync(file, { force: true });
+        return true;
+    }
+    ensureDir(path.dirname(file));
+    fs.writeFileSync(file, `${JSON.stringify(data, null, 2)}\n`);
+    return true;
+}
+function setList(holder, key, previous, next) {
+    const current = Array.isArray(holder[key]) ? holder[key].filter((v) => typeof v === 'string') : [];
+    const kept = current.filter((v) => !previous.includes(v));
+    const result = [...kept, ...next.filter((v) => !kept.includes(v))];
+    if (result.length > 0)
+        holder[key] = result;
+    else
+        delete holder[key];
+}
+/** Widening entries that `entries` asks for but harnesspm does not own yet, without writing anything. */
+export function heldEntries(group, entries, stateFile) {
+    const prev = readOwned(stateFile)[group] ?? emptyOwned();
+    const missing = (wanted, had, key) => limit(wanted, had, key, false).held;
+    return [
+        ...missing(entries.claude.allow, prev.claude.allow, (s) => s).map((a) => `allow ${a}`),
+        ...missing(entries.claude.hooks, prev.claude.hooks, hookKey).map((h) => `Claude Code hook: ${h.command}`),
+        ...missing(Object.keys(entries.claude.mcp), prev.claude.mcp, (s) => s).map((n) => `Claude Code MCP server ${n}`),
+        ...missing(entries.codex.hooks, prev.codex.hooks, hookKey).map((h) => `Codex hook: ${h.command}`),
+        ...missing(Object.keys(entries.codex.mcp), Object.keys(prev.codex.mcp), (s) => s).map((n) => `Codex MCP server ${n}`),
+    ];
+}
+export function applyEntries(group, entries, targets, widen) {
+    const state = readOwned(targets.stateFile);
+    const prev = state[group] ?? emptyOwned();
+    const writeClaude = targets.writeClaude !== false;
+    const writeCodex = targets.writeCodex !== false;
+    const changed = [];
+    const held = [];
+    const files = [];
+    const allow = limit(entries.claude.allow, prev.claude.allow, (s) => s, widen);
+    const claudeHooks = limit(entries.claude.hooks, prev.claude.hooks, hookKey, widen);
+    const claudeMcpNames = limit(Object.keys(entries.claude.mcp), prev.claude.mcp, (s) => s, widen);
+    const codexHooks = limit(entries.codex.hooks, prev.codex.hooks, hookKey, widen);
+    const codexMcpNames = limit(Object.keys(entries.codex.mcp), Object.keys(prev.codex.mcp), (s) => s, widen);
+    const allowRules = entries.codex.rules.filter((r) => r.includes('decision = "allow"'));
+    const codexAllow = limit(allowRules, prev.codex.rules.filter((r) => r.includes('decision = "allow"')), (s) => s, widen);
+    // A model run never removes a restriction either.
+    const keepRestrictions = (next, before) => (widen ? next : [...new Set([...next, ...before])]);
+    const deny = keepRestrictions(entries.claude.deny, prev.claude.deny);
+    const ask = keepRestrictions(entries.claude.ask, prev.claude.ask);
+    const codexRestrict = keepRestrictions(entries.codex.rules.filter((r) => !r.includes('decision = "allow"')), prev.codex.rules.filter((r) => !r.includes('decision = "allow"')));
+    held.push(...allow.held.map((a) => `allow ${a}`), ...claudeHooks.held.map((h) => `Claude Code hook: ${h.command}`), ...claudeMcpNames.held.map((n) => `Claude Code MCP server ${n}`));
+    held.push(...codexHooks.held.map((h) => `Codex hook: ${h.command}`), ...codexMcpNames.held.map((n) => `Codex MCP server ${n}`), ...codexAllow.held.map((r) => `Codex rule ${r}`));
+    // Claude Code settings: permissions and hooks.
+    if (writeClaude &&
+        editJson(targets.claudeSettings, (data) => {
+            const permissions = isRecord(data['permissions']) ? data['permissions'] : {};
+            setList(permissions, 'allow', prev.claude.allow, allow.kept);
+            setList(permissions, 'deny', prev.claude.deny, deny);
+            setList(permissions, 'ask', prev.claude.ask, ask);
+            if (Object.keys(permissions).length > 0)
+                data['permissions'] = permissions;
+            else
+                delete data['permissions'];
+            const hooks = mergeHooks(isRecord(data['hooks']) ? data['hooks'] : {}, prev.claude.hooks, claudeHooks.kept);
+            if (Object.keys(hooks).length > 0)
+                data['hooks'] = hooks;
+            else
+                delete data['hooks'];
+        }))
+        changed.push(targets.claudeSettings);
+    if (isFile(targets.claudeSettings))
+        files.push(targets.claudeSettings);
+    // Claude Code MCP servers: ~/.claude.json, at user scope or in the project's local scope.
+    const claudeMcp = Object.fromEntries(claudeMcpNames.kept.map((n) => [n, entries.claude.mcp[n]]));
+    if (writeClaude && (Object.keys(claudeMcp).length > 0 || prev.claude.mcp.length > 0)) {
+        if (editJson(targets.claudeJson, (data) => {
+            let holder = data;
+            if (targets.claudeProject !== undefined) {
+                const projects = isRecord(data['projects']) ? data['projects'] : {};
+                holder = isRecord(projects[targets.claudeProject]) ? projects[targets.claudeProject] : {};
+                projects[targets.claudeProject] = holder;
+                data['projects'] = projects;
+            }
+            const servers = isRecord(holder['mcpServers']) ? holder['mcpServers'] : {};
+            for (const name of prev.claude.mcp)
+                delete servers[name];
+            Object.assign(servers, claudeMcp);
+            if (Object.keys(servers).length > 0)
+                holder['mcpServers'] = servers;
+            else
+                delete holder['mcpServers'];
+            if (targets.claudeProject !== undefined && Object.keys(holder).length === 0)
+                delete data['projects'][targets.claudeProject];
+            if (isRecord(data['projects']) && Object.keys(data['projects']).length === 0)
+                delete data['projects'];
+        }))
+            changed.push(targets.claudeJson);
+    }
+    // Codex hooks.json, owned entries only.
+    if (writeCodex && (codexHooks.kept.length > 0 || prev.codex.hooks.length > 0)) {
+        if (editJson(targets.codexHooks, (data) => {
+            const hooks = mergeHooks(isRecord(data['hooks']) ? data['hooks'] : {}, prev.codex.hooks, codexHooks.kept);
+            if (Object.keys(hooks).length > 0)
+                data['hooks'] = hooks;
+            else
+                delete data['hooks'];
+        }))
+            changed.push(targets.codexHooks);
+        if (isFile(targets.codexHooks))
+            files.push(targets.codexHooks);
+    }
+    const codexMcp = Object.fromEntries(codexMcpNames.kept.map((n) => [n, entries.codex.mcp[n]]));
+    const nextOwned = {
+        claude: writeClaude ? { allow: allow.kept, deny, ask, hooks: claudeHooks.kept, mcp: claudeMcpNames.kept } : prev.claude,
+        codex: writeCodex ? { hooks: codexHooks.kept, mcp: codexMcp, rules: [...codexAllow.kept, ...codexRestrict] } : prev.codex,
+        agentFiles: [...entries.agentFiles.keys()].sort(),
+    };
+    // Codex rules: one file that all groups share.
+    const nextState = { ...state, [group]: nextOwned };
+    const allRules = [...new Set(Object.values(nextState).flatMap((o) => o?.codex.rules ?? []))];
+    if (!writeCodex) {
+        // The repository owns its Codex files.
+    }
+    else if (allRules.length > 0) {
+        if (writeIfChanged(targets.codexRules, `# Generated by \`harnesspm sync\`. Do not edit.\n${allRules.join('\n')}\n`))
+            changed.push(targets.codexRules);
+        files.push(targets.codexRules);
+    }
+    else if (isFile(targets.codexRules)) {
+        fs.rmSync(targets.codexRules);
+        changed.push(targets.codexRules);
+    }
+    // Sub-agent files.
+    for (const [file, content] of entries.agentFiles) {
+        if (!writeCodex && file.endsWith('.toml'))
+            continue;
+        if (writeIfChanged(file, content))
+            changed.push(file);
+        files.push(file);
+    }
+    for (const old of prev.agentFiles) {
+        if (!entries.agentFiles.has(old) && isFile(old) && (readTextIfExists(old) ?? '').includes('Generated by harnesspm from')) {
+            fs.rmSync(old);
+            changed.push(old);
+        }
+    }
+    writeOwned(targets.stateFile, nextState);
+    const allCodexMcp = Object.assign({}, ...Object.values(nextState).map((o) => o?.codex.mcp ?? {}));
+    return { changed, held, codexMcp: allCodexMcp, files };
+}

package/dist/exec-units.js

@@ -0,0 +1,144 @@
+// Scripts, hooks, MCP servers, permissions (spec chapter 5) and sub-agents (spec 2.6).
+import * as path from 'node:path';
+import { parseFrontmatter } from './frontmatter.js';
+import { NS } from './manifest.js';
+import { isFile, isRecord, listDir, readJson, readText } from './util.js';
+export const AGENTS = ['claude', 'codex'];
+/** Events both agents support (spec 5.2). */
+export const PORTABLE_EVENTS = ['SessionStart', 'SessionEnd', 'UserPromptSubmit', 'PreToolUse', 'PermissionRequest', 'PostToolUse', 'PreCompact', 'PostCompact', 'SubagentStart', 'SubagentStop', 'Stop'];
+/** Events only one agent supports. Others are dropped with a warning. */
+const AGENT_EVENTS = {
+    claude: [...PORTABLE_EVENTS, 'Notification'],
+    codex: PORTABLE_EVENTS,
+};
+function commandLists(value, field, problems) {
+    if (value === undefined)
+        return [];
+    if (Array.isArray(value) && value.every((v) => Array.isArray(v) && v.length > 0 && v.every((w) => typeof w === 'string')))
+        return value;
+    problems.push(`permissions.json: "${field}" must be a list of command prefixes, such as [["git", "push", "--force"]]`);
+    return [];
+}
+/** Finds the executable units and sub-agents of a package. Problems are what `harnesspm check` reports. */
+export function discoverExecUnits(pkg, problems) {
+    const scripts = Object.entries(pkg.ext.scripts).map(([name, def]) => ({
+        kind: 'scripts',
+        id: `${pkg.plugin}:scripts/${name}`,
+        name,
+        file: path.resolve(pkg.harnessDir, def.file),
+        ...(def.description !== undefined ? { description: def.description } : {}),
+        allow: def.allow === true,
+        pkg,
+    }));
+    const hooks = [];
+    const hooksFile = path.join(pkg.harnessDir, NS, 'hooks.json');
+    if (isFile(hooksFile)) {
+        const raw = readJson(hooksFile);
+        const byEvent = isRecord(raw) && isRecord(raw['hooks']) ? raw['hooks'] : {};
+        for (const [event, list] of Object.entries(byEvent)) {
+            if (!Array.isArray(list)) {
+                problems.push(`hooks.json: "${event}" must be a list`);
+                continue;
+            }
+            for (const def of list) {
+                if (!isRecord(def) || typeof def['id'] !== 'string' || typeof def['run'] !== 'string') {
+                    problems.push(`hooks.json: every ${event} hook needs "id" and "run"`);
+                    continue;
+                }
+                if (pkg.ext.scripts[def['run']] === undefined)
+                    problems.push(`hooks.json: hook "${def['id']}" runs "${def['run']}", which is not in "scripts"`);
+                const matcher = def['matcher'];
+                let matchers;
+                if (matcher === undefined || typeof matcher === 'string')
+                    matchers = { claude: matcher, codex: matcher };
+                else if (isRecord(matcher)) {
+                    matchers = {};
+                    for (const agent of AGENTS)
+                        if (typeof matcher[agent] === 'string')
+                            matchers[agent] = matcher[agent];
+                    for (const key of Object.keys(matcher))
+                        if (!AGENTS.includes(key))
+                            problems.push(`hooks.json: hook "${def['id']}" has an unknown agent "${key}" in "matcher"`);
+                }
+                else {
+                    problems.push(`hooks.json: hook "${def['id']}": "matcher" must be a string or an object`);
+                    continue;
+                }
+                for (const agent of AGENTS)
+                    if (agent in matchers && !AGENT_EVENTS[agent].includes(event))
+                        delete matchers[agent];
+                if (Object.keys(matchers).length === 0)
+                    problems.push(`hooks.json: hook "${def['id']}" uses ${event}, which no agent it names supports`);
+                hooks.push({
+                    kind: 'hooks',
+                    id: `${pkg.plugin}:hooks/${def['id']}`,
+                    name: def['id'],
+                    event,
+                    matchers,
+                    run: def['run'],
+                    ...(typeof def['timeout'] === 'number' ? { timeout: def['timeout'] } : {}),
+                    pkg,
+                });
+            }
+        }
+    }
+    const mcp = [];
+    const mcpFile = path.join(pkg.harnessDir, 'mcp.json');
+    if (isFile(mcpFile)) {
+        const raw = readJson(mcpFile);
+        const servers = isRecord(raw) && isRecord(raw['mcpServers']) ? raw['mcpServers'] : {};
+        for (const [name, config] of Object.entries(servers)) {
+            if (!isRecord(config)) {
+                problems.push(`mcp.json: server "${name}" must be an object`);
+                continue;
+            }
+            const type = config['type'] ?? 'stdio';
+            if (type === 'stdio' && typeof config['command'] !== 'string')
+                problems.push(`mcp.json: stdio server "${name}" needs a "command"`);
+            if ((type === 'streamable-http' || type === 'sse') && typeof config['url'] !== 'string')
+                problems.push(`mcp.json: server "${name}" needs a "url"`);
+            if (!['stdio', 'streamable-http', 'sse'].includes(String(type)))
+                problems.push(`mcp.json: server "${name}" has an unknown type "${String(type)}"`);
+            mcp.push({ kind: 'mcp', id: `${pkg.plugin}:mcp/${name}`, name, config: { ...config, type }, pkg });
+        }
+    }
+    let permissions;
+    const permFile = path.join(pkg.harnessDir, NS, 'permissions.json');
+    if (isFile(permFile)) {
+        const raw = readJson(permFile);
+        const data = isRecord(raw) ? raw : {};
+        for (const key of Object.keys(data)) {
+            if (key === 'allow')
+                problems.push('permissions.json: "allow" is not supported. Set "allow": true on a script instead (spec 5.4).');
+            else if (key !== 'deny' && key !== 'ask')
+                problems.push(`permissions.json: unknown field "${key}"`);
+        }
+        permissions = { kind: 'permissions', id: `${pkg.plugin}:permissions`, deny: commandLists(data['deny'], 'deny', problems), ask: commandLists(data['ask'], 'ask', problems), pkg };
+    }
+    const agentsDir = path.join(pkg.harnessDir, NS, 'agents');
+    const agents = [];
+    for (const file of listDir(agentsDir).filter((f) => f.endsWith('.md'))) {
+        const full = path.join(agentsDir, file);
+        const { data, body } = parseFrontmatter(readText(full), full);
+        const name = typeof data['name'] === 'string' ? data['name'] : file.slice(0, -3);
+        if (typeof data['description'] !== 'string')
+            problems.push(`agents/${file}: needs a "description"`);
+        agents.push({
+            kind: 'agents',
+            id: `${pkg.plugin}:agents/${name}`,
+            name,
+            description: typeof data['description'] === 'string' ? data['description'] : '',
+            body: body.trim(),
+            claude: isRecord(data['claude']) ? data['claude'] : {},
+            codex: isRecord(data['codex']) ? data['codex'] : {},
+            file: full,
+            pkg,
+        });
+    }
+    return { scripts, hooks, mcp, ...(permissions ? { permissions } : {}), agents };
+}
+/** Sub-agent keys that widen what the agent may do. Written only for trusted owners. */
+export const WIDENING_AGENT_KEYS = {
+    claude: ['permissionMode'],
+    codex: ['sandbox_mode', 'approval_policy'],
+};

package/dist/fetch.js

@@ -0,0 +1,93 @@
+// harnesspm fetch: the harness packages in the lock, without an install (spec 4.2, 13.6).
+import { spawnSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { readLock } from './lock.js';
+import { computePlan, STATE_DIR } from './outputs.js';
+import { extractBlock } from './render.js';
+import { resolve, resolvePackageDir } from './resolve.js';
+import { HarnessError, ensureDir, isRecord, linkIfChanged, readJsonIfExists, readTextIfExists, writeIfChanged } from './util.js';
+function sri(file, algorithm) {
+    return `${algorithm}-${createHash(algorithm).update(fs.readFileSync(file)).digest('base64')}`;
+}
+function installedVersion(dir) {
+    const pkg = readJsonIfExists(path.join(dir, 'package.json'));
+    return isRecord(pkg) && typeof pkg['version'] === 'string' ? pkg['version'] : undefined;
+}
+/** Downloads one package with npm, checks its integrity and unpacks it. Never runs its code. */
+function download(projectDir, name, spec, integrity, target) {
+    const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'harnesspm-fetch-'));
+    try {
+        const packSpec = spec.startsWith('file:') ? path.resolve(projectDir, spec.slice('file:'.length)) : spec;
+        const packed = spawnSync('npm', ['pack', packSpec, '--silent', '--ignore-scripts', '--pack-destination', tmp], { cwd: projectDir, encoding: 'utf8' });
+        if (packed.status !== 0)
+            throw new HarnessError(`Cannot download ${name} (${spec}): ${packed.stderr.trim()}`);
+        const tarball = path.join(tmp, packed.stdout.trim().split('\n').pop().trim());
+        if (integrity !== undefined) {
+            const algorithm = integrity.split('-')[0];
+            const actual = sri(tarball, algorithm);
+            if (actual !== integrity)
+                throw new HarnessError(`${name}: the downloaded tarball does not match the integrity in the lock`);
+        }
+        const unpacked = path.join(tmp, 'unpacked');
+        ensureDir(unpacked);
+        const tar = spawnSync('tar', ['-xzf', tarball, '-C', unpacked], { encoding: 'utf8' });
+        if (tar.status !== 0)
+            throw new HarnessError(`Cannot unpack ${name}: ${tar.stderr.trim()}`);
+        fs.rmSync(target, { recursive: true, force: true });
+        ensureDir(path.dirname(target));
+        fs.renameSync(path.join(unpacked, 'package'), target);
+    }
+    finally {
+        fs.rmSync(tmp, { recursive: true, force: true });
+    }
+}
+export function fetchLocked(projectDir) {
+    const lock = readLock(projectDir);
+    if (!lock)
+        throw new HarnessError('No harnesspm.lock.json here. Run `npx harnesspm sync` where the dependencies are installed, and commit the lock.');
+    const report = { fetched: [], reused: [], warnings: [] };
+    const located = new Map();
+    for (const [name, entry] of Object.entries(lock.packages)) {
+        if (entry.project)
+            continue;
+        const installed = resolvePackageDir(name, projectDir);
+        if (installed && installedVersion(installed) === entry.version) {
+            located.set(name, installed);
+            report.reused.push(name);
+            continue;
+        }
+        const target = path.join(projectDir, STATE_DIR, 'fetched', name);
+        if (installedVersion(target) !== entry.version) {
+            const spec = entry.resolved ?? `${name}@${entry.version}`;
+            if (entry.integrity === undefined)
+                report.warnings.push(`${name}: the lock has no integrity, so the download is not checked`);
+            download(projectDir, name, spec, entry.integrity, target);
+            report.fetched.push(`${name} ${entry.version}`);
+        }
+        else
+            report.reused.push(name);
+        located.set(name, target);
+    }
+    // Stable paths and generated files (docs indexes, patched rules), so the committed pointers work.
+    const team = resolve(projectDir, { locate: (name) => located.get(name) });
+    report.warnings.push(...team.warnings);
+    const plan = computePlan(team, team);
+    const agents = readTextIfExists(path.join(projectDir, 'AGENTS.md'));
+    if (extractBlock(agents) !== extractBlock(plan.committed.agentsMd))
+        report.warnings.push('AGENTS.md does not match the packages in the lock. Run `npx harnesspm sync` where the dependencies are installed.');
+    // Only files under node_modules/.harnesspm: a job without an install needs no agent settings.
+    const state = path.join(projectDir, STATE_DIR) + path.sep;
+    for (const root of plan.generatedRoots)
+        if (root.startsWith(state))
+            fs.rmSync(root, { recursive: true, force: true });
+    for (const [file, content] of plan.generated)
+        if (file.startsWith(state))
+            writeIfChanged(file, content);
+    for (const [link, target] of plan.links)
+        if (link.startsWith(path.join(state, 'pkgs') + path.sep))
+            linkIfChanged(link, target);
+    return report;
+}

package/dist/frontmatter.js

@@ -0,0 +1,35 @@
+import { parse, stringify } from 'yaml';
+import { HarnessError, isRecord } from './util.js';
+const FRONTMATTER = /^---\r?\n(?:([\s\S]*?)\r?\n)?---[ \t]*(?:\r?\n|$)/;
+/** Splits a Markdown file into its YAML frontmatter and its body. */
+export function parseFrontmatter(text, file = 'file') {
+    const match = FRONTMATTER.exec(text);
+    if (!match)
+        return { data: {}, body: text, hasFrontmatter: false };
+    let data;
+    try {
+        data = match[1] ? parse(match[1]) : {};
+    }
+    catch (error) {
+        throw new HarnessError(`Invalid frontmatter in ${file}: ${error.message}`);
+    }
+    if (data === null || data === undefined)
+        data = {};
+    if (!isRecord(data))
+        throw new HarnessError(`Frontmatter in ${file} must be a mapping`);
+    return { data, body: text.slice(match[0].length), hasFrontmatter: true };
+}
+export function withFrontmatter(data, body) {
+    if (Object.keys(data).length === 0)
+        return body;
+    return `---\n${stringify(data).trimEnd()}\n---\n\n${body.replace(/^\n+/, '')}`;
+}
+export function stringList(value) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value === 'string')
+        return [value];
+    if (Array.isArray(value) && value.every((v) => typeof v === 'string'))
+        return value;
+    return undefined;
+}

package/dist/homes.js

@@ -0,0 +1,17 @@
+// Where each agent keeps its user-level files. Tests and people can move them with environment variables.
+import * as os from 'node:os';
+import * as path from 'node:path';
+export function claudeHome() {
+    return process.env['CLAUDE_CONFIG_DIR'] ?? path.join(os.homedir(), '.claude');
+}
+/** Claude Code keeps MCP servers of user and local scope here. */
+export function claudeJsonFile() {
+    const dir = process.env['CLAUDE_CONFIG_DIR'];
+    return dir !== undefined ? path.join(dir, '.claude.json') : path.join(os.homedir(), '.claude.json');
+}
+export function codexHome() {
+    return process.env['CODEX_HOME'] ?? path.join(os.homedir(), '.codex');
+}
+export function agentsHome() {
+    return path.join(os.homedir(), '.agents');
+}