@tenphi/harnesspm 0.0.0-snapshot.376310a

package/dist/resolve.js

@@ -0,0 +1,396 @@
+// Resolution of the dependency and project layers (spec chapter 3).
+import * as path from 'node:path';
+import { CONFIG_FILE, emptyConfig, readConfig } from './config.js';
+import { discoverUnits, loadHarnessPackage, ruleMeta, } from './manifest.js';
+import { discoverExecUnits } from './exec-units.js';
+import { applyPatch } from './sections.js';
+import { findWorkspaces } from './workspaces.js';
+import { HarnessError, compareVersions, isFile, isRecord, readJsonIfExists, readText, realpath, relPosix } from './util.js';
+/** Finds `<name>` in node_modules from `fromDir` upward, the way Node.js does. */
+export function resolvePackageDir(name, fromDir) {
+    let dir = fromDir;
+    for (;;) {
+        const candidate = path.join(dir, 'node_modules', name, 'package.json');
+        if (isFile(candidate))
+            return realpath(path.dirname(candidate));
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            return undefined;
+        dir = parent;
+    }
+}
+function dependencyNames(pkgJson) {
+    const names = new Set();
+    for (const field of ['dependencies', 'devDependencies', 'optionalDependencies']) {
+        const deps = pkgJson[field];
+        if (isRecord(deps))
+            for (const name of Object.keys(deps))
+                names.add(name);
+    }
+    return [...names].sort();
+}
+const isUnitId = (entry) => entry.includes(':');
+export function resolve(projectDirInput, options = {}) {
+    const projectDir = realpath(projectDirInput);
+    const team = options.team ?? true;
+    const warnings = [];
+    const config = team ? readConfig(projectDir) : emptyConfig();
+    warnings.push(...config.warnings);
+    const pkgJsonRaw = readJsonIfExists(path.join(projectDir, 'package.json'));
+    const pkgJson = isRecord(pkgJsonRaw) ? pkgJsonRaw : {};
+    const projectName = typeof pkgJson['name'] === 'string' ? pkgJson['name'] : path.basename(projectDir);
+    const cache = new Map();
+    const load = (dir, layer) => {
+        if (!cache.has(dir))
+            cache.set(dir, loadHarnessPackage(dir, layer) ?? null);
+        return cache.get(dir) ?? undefined;
+    };
+    const occurrences = new Map();
+    const members = new Map();
+    const addMember = (name, key) => {
+        const set = members.get(name) ?? new Set();
+        set.add(key);
+        members.set(name, set);
+    };
+    const edges = new Map();
+    const excludedPackages = [];
+    const addOccurrence = (name, occurrence) => {
+        const list = occurrences.get(name) ?? [];
+        list.push(occurrence);
+        occurrences.set(name, list);
+    };
+    const addEdge = (from, to) => {
+        const set = edges.get(from) ?? new Set();
+        set.add(to);
+        edges.set(from, set);
+    };
+    /** `excluded` maps a package name to whoever excluded it on this path. */
+    const visit = (pkg, depth, excluded, stack, root) => {
+        const childExcluded = new Map(excluded);
+        for (const name of pkg.ext.exclude.filter((e) => !isUnitId(e)))
+            childExcluded.set(name, pkg.name);
+        for (const name of pkg.ext.extends) {
+            const by = childExcluded.get(name);
+            if (by !== undefined) {
+                excludedPackages.push({ name, by });
+                continue;
+            }
+            const dir = resolvePackageDir(name, pkg.dir) ?? options.locate?.(name);
+            if (!dir) {
+                warnings.push(`${pkg.name} extends ${name}, which is not installed`);
+                continue;
+            }
+            if (stack.includes(dir)) {
+                throw new HarnessError(`extends cycle: ${[...stack.map((d) => cache.get(d)?.name ?? d), name].join(' → ')}`);
+            }
+            const child = load(dir, 'dependencies');
+            if (!child) {
+                warnings.push(`${pkg.name} extends ${name}, which has no harness/ folder`);
+                continue;
+            }
+            addEdge(pkg.name, name);
+            addOccurrence(name, { dir, depth: depth + 1, direct: false, via: pkg.name });
+            addMember(name, root);
+            visit(child, depth + 1, childExcluded, [...stack, dir], root);
+        }
+    };
+    // Each workspace is resolved on its own dependencies, from its own folder (spec 3.6).
+    const workspaces = team ? findWorkspaces(projectDir).map((dir) => ({ key: relPosix(projectDir, dir), dir: realpath(dir) })) : [];
+    const roots = [{ key: '', dir: projectDir, deps: dependencyNames(pkgJson) }, ...workspaces.map((ws) => {
+            const raw = readJsonIfExists(path.join(ws.dir, 'package.json'));
+            return { key: ws.key, dir: ws.dir, deps: dependencyNames(isRecord(raw) ? raw : {}) };
+        })];
+    const rootExcluded = new Map(config.exclude.filter((e) => !isUnitId(e)).map((name) => [name, CONFIG_FILE]));
+    for (const root of team ? roots : []) {
+        for (const name of root.deps) {
+            if (rootExcluded.has(name)) {
+                excludedPackages.push({ name, by: CONFIG_FILE });
+                continue;
+            }
+            const dir = resolvePackageDir(name, root.dir) ?? options.locate?.(name);
+            if (!dir)
+                continue;
+            const pkg = load(dir, 'dependencies');
+            if (!pkg)
+                continue;
+            addOccurrence(name, { dir, depth: 0, direct: true });
+            addMember(name, root.key);
+            visit(pkg, 0, rootExcluded, [dir], root.key);
+        }
+    }
+    const projectHarness = team ? loadHarnessPackage(projectDir, 'project') : undefined;
+    if (projectHarness) {
+        projectHarness.name = projectName;
+        visit(projectHarness, 0, rootExcluded, [projectDir], '');
+    }
+    // A workspace's own harness belongs to that workspace, unless another workspace already reaches it as a dependency.
+    const workspaceHarnesses = [];
+    for (const ws of workspaces) {
+        const harness = loadHarnessPackage(ws.dir, 'project');
+        if (!harness)
+            continue;
+        workspaceHarnesses.push({ pkg: harness, key: ws.key });
+        visit(harness, 0, rootExcluded, [ws.dir], ws.key);
+    }
+    // One version per package in a repository (spec 3.5).
+    const chosen = new Map();
+    for (const [name, list] of occurrences) {
+        const sorted = [...list].sort((a, b) => {
+            if (a.direct !== b.direct)
+                return a.direct ? -1 : 1;
+            if (a.depth !== b.depth)
+                return a.depth - b.depth;
+            return compareVersions(load(b.dir, 'dependencies').version, load(a.dir, 'dependencies').version);
+        });
+        const first = sorted[0];
+        const versions = [...new Set(list.map((o) => load(o.dir, 'dependencies').version))];
+        if (new Set(list.map((o) => o.dir)).size > 1 && versions.length > 1) {
+            warnings.push(`${name}: found versions ${versions.join(', ')}; using ${load(first.dir, 'dependencies').version}`);
+        }
+        chosen.set(name, { pkg: load(first.dir, 'dependencies'), occurrence: first });
+    }
+    const closureOf = (name) => {
+        const result = new Set();
+        const stack = [...(edges.get(name) ?? [])];
+        while (stack.length > 0) {
+            const next = stack.pop();
+            if (result.has(next) || !chosen.has(next))
+                continue;
+            result.add(next);
+            stack.push(...(edges.get(next) ?? []));
+        }
+        return result;
+    };
+    // Upstream first: a package comes after the packages it extends. Unrelated packages by name.
+    const order = [];
+    const seen = new Set();
+    const walk = (name) => {
+        if (seen.has(name) || !chosen.has(name))
+            return;
+        seen.add(name);
+        for (const child of [...(edges.get(name) ?? [])].sort())
+            walk(child);
+        order.push(name);
+    };
+    for (const [name, { occurrence }] of [...chosen].sort(([a], [b]) => a.localeCompare(b)))
+        if (occurrence.direct)
+            walk(name);
+    for (const child of [...(edges.get(projectName) ?? [])].sort())
+        walk(child);
+    for (const name of [...chosen.keys()].sort())
+        walk(name);
+    const workspaceDirs = new Map(workspaces.map((ws) => [ws.dir, ws.key]));
+    const packages = order.map((name) => {
+        const { pkg, occurrence } = chosen.get(name);
+        const own = workspaceDirs.get(pkg.dir);
+        const set = new Set(members.get(name) ?? []);
+        if (own !== undefined)
+            set.add(own);
+        return {
+            ...pkg,
+            // A workspace that another workspace depends on is still this repository's own code.
+            ...(own !== undefined ? { layer: 'project' } : {}),
+            direct: occurrence.direct,
+            ...(occurrence.via !== undefined ? { via: occurrence.via } : {}),
+            closure: closureOf(name),
+            members: set,
+        };
+    });
+    if (projectHarness)
+        packages.push({ ...projectHarness, direct: true, closure: closureOf(projectName), members: new Set(['']) });
+    for (const { pkg, key } of workspaceHarnesses) {
+        if (packages.some((p) => p.dir === pkg.dir))
+            continue;
+        packages.push({ ...pkg, direct: true, closure: closureOf(pkg.name), members: new Set([key]) });
+    }
+    const everywhere = new Set(['', ...workspaces.map((ws) => ws.key)]);
+    for (const added of options.added ?? []) {
+        packages.push({ ...added.pkg, layer: 'added', direct: true, closure: new Set(), scope: added.scope, added, members: everywhere });
+        if (added.entry)
+            packages.push({ ...added.entry, layer: 'added', direct: true, closure: new Set(), scope: added.scope, added, entry: true, members: everywhere });
+    }
+    // Plugin names must be unique (spec 2.9). An entry shares its harness's name.
+    const byPlugin = new Map();
+    for (const pkg of packages) {
+        if (pkg.entry)
+            continue;
+        const other = byPlugin.get(pkg.plugin);
+        if (other !== undefined) {
+            throw new HarnessError(`${other} and ${pkg.name} both use the plugin name "${pkg.plugin}". Exclude one of them in ${CONFIG_FILE}.`);
+        }
+        byPlugin.set(pkg.plugin, pkg.name);
+    }
+    for (const pkg of packages)
+        for (const problem of pkg.problems)
+            warnings.push(`${pkg.name}: ${problem}`);
+    // Overrides, lowest first: upstream packages, then downstream ones, then the project's harness, then harnesspm.json.
+    const overrides = [];
+    const add = (by, scope, exclude, replace, patch, baseDir) => {
+        for (const target of exclude.filter(isUnitId))
+            overrides.push({ kind: 'exclude', target, by, order: overrides.length, scope });
+        for (const [target, file] of Object.entries(replace))
+            overrides.push({ kind: 'replace', target, file: path.resolve(baseDir, file), by, order: overrides.length, scope });
+        for (const [target, file] of Object.entries(patch))
+            overrides.push({ kind: 'patch', target, file: path.resolve(baseDir, file), by, order: overrides.length, scope });
+    };
+    for (const pkg of packages.filter((p) => p.layer !== 'added'))
+        add(pkg.name, pkg.closure, pkg.ext.exclude, pkg.ext.replace, pkg.ext.patch, pkg.harnessDir);
+    add(CONFIG_FILE, 'all', config.exclude, config.replace, config.patch, projectDir);
+    // Added harnesses sit above everything, so their changes reach every unit below them.
+    for (const pkg of packages.filter((p) => p.layer === 'added'))
+        add(pkg.name, 'all', pkg.ext.exclude, pkg.ext.replace, pkg.ext.patch, pkg.harnessDir);
+    const overrideFiles = new Set(overrides.flatMap((o) => (o.file !== undefined ? [o.file] : [])));
+    const inScope = (o, pkgName) => o.scope === 'all' || o.scope.has(pkgName);
+    const allRules = [];
+    const allSkills = [];
+    const allDocs = [];
+    const allScripts = [];
+    const allHooks = [];
+    const allMcp = [];
+    const allPermissions = [];
+    const allAgents = [];
+    for (const pkg of packages) {
+        const units = discoverUnits(pkg, overrideFiles);
+        for (const source of units.rules)
+            allRules.push({ source, pkg });
+        for (const skill of units.skills)
+            allSkills.push({ ...skill, pkg });
+        if (units.docs)
+            allDocs.push({ ...units.docs, pkg });
+        const problems = [];
+        const exec = discoverExecUnits(pkg, problems);
+        for (const problem of problems)
+            warnings.push(`${pkg.name}: ${problem}`);
+        allScripts.push(...exec.scripts.map((u) => ({ ...u, pkg })));
+        allHooks.push(...exec.hooks.map((u) => ({ ...u, pkg })));
+        allMcp.push(...exec.mcp.map((u) => ({ ...u, pkg })));
+        if (exec.permissions)
+            allPermissions.push({ ...exec.permissions, pkg });
+        allAgents.push(...exec.agents.map((u) => ({ ...u, pkg })));
+    }
+    const knownIds = new Map();
+    for (const { source, pkg } of allRules)
+        knownIds.set(source.id, pkg.name);
+    for (const skill of allSkills)
+        knownIds.set(skill.id, skill.pkg.name);
+    for (const docs of allDocs)
+        knownIds.set(docs.id, docs.pkg.name);
+    for (const unit of [...allScripts, ...allHooks, ...allMcp, ...allPermissions, ...allAgents])
+        knownIds.set(unit.id, unit.pkg.name);
+    const addedNames = new Set(packages.filter((p) => p.layer === 'added').map((p) => p.name));
+    for (const o of overrides) {
+        const owner = knownIds.get(o.target);
+        // Without the team layers, an added harness's change to a team unit has nothing to point at yet.
+        if (owner === undefined && !team && addedNames.has(o.by))
+            continue;
+        if (owner === undefined)
+            warnings.push(`${o.by}: ${o.kind} names ${o.target}, which does not exist. It may have been renamed upstream.`);
+        else if (!inScope(o, owner))
+            warnings.push(`${o.by}: ${o.kind} names ${o.target}, which ${o.by} does not pass on`);
+        else if (o.kind !== 'exclude' && !o.target.includes(':rules/'))
+            warnings.push(`${o.by}: ${o.kind} works on rules only: ${o.target}`);
+        if (o.file !== undefined && !isFile(o.file))
+            warnings.push(`${o.by}: ${o.kind} file not found: ${relPosix(projectDir, o.file)}`);
+    }
+    const excludedUnits = [];
+    const excludedBy = (id, pkgName) => overrides.find((o) => o.kind === 'exclude' && o.target === id && inScope(o, pkgName));
+    // An entry's unit wins over a unit with the same ID in its own harness (spec 7.2).
+    const entryIds = new Set(allRules.filter((r) => r.pkg.entry).map((r) => r.source.id));
+    const rules = [];
+    for (const { source, pkg } of allRules) {
+        if (!pkg.entry && pkg.layer === 'added' && entryIds.has(source.id))
+            continue;
+        const exclusion = excludedBy(source.id, pkg.name);
+        if (exclusion) {
+            excludedUnits.push({ id: source.id, by: exclusion.by });
+            continue;
+        }
+        const relevant = overrides.filter((o) => o.target === source.id && inScope(o, pkg.name) && (o.file === undefined || isFile(o.file)));
+        const replace = relevant.filter((o) => o.kind === 'replace').at(-1);
+        const from = replace?.file ?? source.file;
+        let text = readText(from);
+        const patches = [];
+        for (const p of relevant.filter((o) => o.kind === 'patch')) {
+            if (replace && p.order < replace.order) {
+                warnings.push(`${p.by}: the patch of ${source.id} is dropped, because ${replace.by} replaces the rule`);
+                continue;
+            }
+            const patchName = relPosix(projectDir, p.file);
+            const result = applyPatch(text, readText(p.file), patchName);
+            text = result.text;
+            warnings.push(...result.warnings);
+            patches.push({ patch: patchName, by: p.by, sections: result.touched });
+        }
+        rules.push({
+            ...ruleMeta(text, source.name, from),
+            id: source.id,
+            name: source.name,
+            pkg,
+            original: source.file,
+            source: from,
+            text,
+            ...(replace ? { replacedBy: replace } : {}),
+            patches,
+        });
+    }
+    // Skills: a later package wins on the same name, with a warning (spec 2.9).
+    const skillsByName = new Map();
+    for (const skill of allSkills) {
+        const exclusion = excludedBy(skill.id, skill.pkg.name);
+        if (exclusion) {
+            excludedUnits.push({ id: skill.id, by: exclusion.by });
+            continue;
+        }
+        const previous = skillsByName.get(skill.name);
+        if (previous && !(skill.pkg.entry && previous.pkg.plugin === skill.pkg.plugin))
+            warnings.push(`skill "${skill.name}" comes from ${previous.pkg.name} and ${skill.pkg.name}; using ${skill.pkg.name}`);
+        skillsByName.set(skill.name, skill);
+    }
+    const docs = [];
+    for (const unit of allDocs) {
+        const exclusion = excludedBy(unit.id, unit.pkg.name);
+        if (exclusion)
+            excludedUnits.push({ id: unit.id, by: exclusion.by });
+        else
+            docs.push(unit);
+    }
+    const keep = (units) => units.filter((unit) => {
+        const exclusion = excludedBy(unit.id, unit.pkg.name);
+        if (exclusion)
+            excludedUnits.push({ id: unit.id, by: exclusion.by });
+        return !exclusion;
+    });
+    const scripts = keep(allScripts);
+    const hooks = keep(allHooks).filter((hook) => {
+        const ok = scripts.some((s) => s.pkg === hook.pkg && s.name === hook.run);
+        if (!ok)
+            warnings.push(`${hook.id} is dropped: its script ${hook.pkg.plugin}:${hook.run} is excluded or missing`);
+        return ok;
+    });
+    const agentsByName = new Map();
+    for (const agent of keep(allAgents)) {
+        const previous = agentsByName.get(agent.name);
+        if (previous && !(agent.pkg.entry && previous.pkg.plugin === agent.pkg.plugin))
+            warnings.push(`sub-agent "${agent.name}" comes from ${previous.pkg.name} and ${agent.pkg.name}; using ${agent.pkg.name}`);
+        agentsByName.set(agent.name, agent);
+    }
+    return {
+        projectDir,
+        projectName,
+        workspaces,
+        config,
+        packages,
+        rules,
+        skills: [...skillsByName.values()],
+        docs,
+        scripts,
+        hooks,
+        mcp: keep(allMcp),
+        permissions: keep(allPermissions),
+        agents: [...agentsByName.values()],
+        overrides,
+        excludedUnits,
+        excludedPackages,
+        warnings,
+    };
+}

package/dist/run.js

@@ -0,0 +1,83 @@
+// harnesspm run and harnesspm mcp (spec 5.1, 5.3).
+import { spawnSync } from 'node:child_process';
+import * as path from 'node:path';
+import { harnesspmHome } from './added.js';
+import { trustOf } from './exec-outputs.js';
+import { readLock } from './lock.js';
+import { HarnessError, ensureDir, isFile } from './util.js';
+/** Thrown when the runner refuses a script. The CLI exits with code 2 (spec 10.4). */
+export class Refused extends HarnessError {
+}
+function parseRef(ref) {
+    const index = ref.indexOf(':');
+    if (index <= 0 || index === ref.length - 1)
+        throw new HarnessError(`Use <plugin>:<name>, not "${ref}"`);
+    return { plugin: ref.slice(0, index), name: ref.slice(index + 1) };
+}
+/** Checks trust and the installed version (spec 5.1, step 2). */
+function checkPackage(pkg, res, what) {
+    const lock = readLock(res.projectDir);
+    const trust = trustOf(pkg, res, lock);
+    if (!trust.trusted)
+        throw new Refused(`${what} of ${pkg.name} is refused: ${trust.reason}`);
+    if (pkg.layer === 'dependencies') {
+        const locked = lock?.packages[pkg.name]?.version;
+        if (locked !== pkg.version)
+            throw new Refused(`${what} is refused: ${pkg.name} ${pkg.version} is installed, but the lock has ${locked ?? 'no entry'}. Run \`npx harnesspm sync\`.`);
+    }
+}
+function environment(pkg, res, agent) {
+    const data = path.join(harnesspmHome(), 'data', pkg.plugin);
+    ensureDir(data);
+    return {
+        ...process.env,
+        PLUGIN_ROOT: pkg.harnessDir,
+        PLUGIN_DATA: data,
+        HARNESSPM_PROJECT_DIR: res.projectDir,
+        HARNESSPM_AGENT: agent ?? (process.env['AI_AGENT']?.startsWith('claude-code') ? 'claude' : ''),
+    };
+}
+function interpreter(file) {
+    if (/\.(m|c)?js$/.test(file))
+        return [process.execPath, [file]];
+    if (file.endsWith('.sh'))
+        return ['sh', [file]];
+    return [file, []];
+}
+export function runScript(res, ref, args, agent) {
+    const { plugin, name } = parseRef(ref);
+    const script = res.scripts.find((s) => s.pkg.plugin === plugin && s.name === name);
+    if (!script) {
+        const known = res.scripts.filter((s) => s.pkg.plugin === plugin).map((s) => `${plugin}:${s.name}`);
+        throw new HarnessError(`No script ${ref}.${known.length > 0 ? ` Scripts of ${plugin}: ${known.join(', ')}` : ''}`);
+    }
+    checkPackage(script.pkg, res, `Script ${ref}`);
+    if (!isFile(script.file))
+        throw new HarnessError(`Script ${ref}: ${script.file} does not exist`);
+    const [command, prefix] = interpreter(script.file);
+    const result = spawnSync(command, [...prefix, ...args], { stdio: 'inherit', cwd: process.cwd(), env: environment(script.pkg, res, agent) });
+    if (result.error)
+        throw new HarnessError(`Script ${ref} could not start: ${result.error.message}`);
+    return result.status ?? 1;
+}
+export function runMcp(res, ref, agent) {
+    const { plugin, name } = parseRef(ref);
+    const server = res.mcp.find((s) => s.pkg.plugin === plugin && s.name === name);
+    if (!server)
+        throw new HarnessError(`No MCP server ${ref}`);
+    checkPackage(server.pkg, res, `MCP server ${ref}`);
+    if (server.config['type'] !== 'stdio')
+        throw new HarnessError(`MCP server ${ref} is remote; agents connect to its URL directly`);
+    const env = environment(server.pkg, res, agent);
+    const expand = (value) => value.replaceAll('${PLUGIN_ROOT}', env['PLUGIN_ROOT']).replaceAll('${PLUGIN_DATA}', env['PLUGIN_DATA']);
+    const command = expand(String(server.config['command']));
+    const args = Array.isArray(server.config['args']) ? server.config['args'].map((a) => expand(String(a))) : [];
+    const extra = server.config['env'];
+    if (extra !== null && typeof extra === 'object')
+        for (const [k, v] of Object.entries(extra))
+            env[k] = expand(String(v));
+    const result = spawnSync(command, args, { stdio: 'inherit', env });
+    if (result.error)
+        throw new HarnessError(`MCP server ${ref} could not start: ${result.error.message}`);
+    return result.status ?? 1;
+}

package/dist/sections.js

@@ -0,0 +1,121 @@
+// Markdown sections and patches (spec 2.5).
+import { parseFrontmatter, stringList, withFrontmatter } from './frontmatter.js';
+import { hash } from './util.js';
+/** ATX headings outside fenced code blocks. */
+export function headings(lines) {
+    const result = [];
+    let fence;
+    lines.forEach((line, index) => {
+        const fenceMatch = /^\s*(```+|~~~+)/.exec(line);
+        if (fenceMatch) {
+            const marker = fenceMatch[1];
+            if (fence === undefined)
+                fence = marker[0];
+            else if (marker[0] === fence)
+                fence = undefined;
+            return;
+        }
+        if (fence !== undefined)
+            return;
+        const match = /^(#{1,6})[ \t]+(.*?)[ \t]*#*[ \t]*$/.exec(line);
+        if (match)
+            result.push({ line: index, level: match[1].length, text: match[2].trim() });
+    });
+    return result;
+}
+/** A section is a heading and everything up to the next heading of the same or a higher level. */
+function sectionEnd(lines, hs, index) {
+    const own = hs[index];
+    for (let i = index + 1; i < hs.length; i++) {
+        if (hs[i].level <= own.level)
+            return hs[i].line;
+    }
+    return lines.length;
+}
+export function parsePatch(text, file = 'patch') {
+    const { data, body } = parseFrontmatter(text, file);
+    const lines = body.split('\n');
+    const hs = headings(lines);
+    const first = hs[0]?.line ?? lines.length;
+    const sections = [];
+    let i = 0;
+    while (i < hs.length) {
+        const end = sectionEnd(lines, hs, i);
+        sections.push({ level: hs[i].level, text: hs[i].text, lines: trimBlank(lines.slice(hs[i].line, end)) });
+        // Skip headings nested in this section: they are part of it.
+        i++;
+        while (i < hs.length && hs[i].line < end)
+            i++;
+    }
+    return { remove: stringList(data['remove']) ?? [], preamble: trimBlank(lines.slice(0, first)), sections };
+}
+function trimBlank(lines) {
+    let start = 0;
+    let end = lines.length;
+    while (start < end && lines[start].trim() === '')
+        start++;
+    while (end > start && lines[end - 1].trim() === '')
+        end--;
+    return lines.slice(start, end);
+}
+/** Applies a patch to a rule. The rule's frontmatter is kept. */
+export function applyPatch(ruleText, patchText, patchFile = 'patch') {
+    const patch = parsePatch(patchText, patchFile);
+    const rule = parseFrontmatter(ruleText);
+    const lines = rule.body.split('\n');
+    const hs = headings(lines);
+    const warnings = [];
+    const touched = [];
+    const ops = [];
+    const additions = [];
+    const find = (predicate) => {
+        const index = hs.findIndex(predicate);
+        if (index < 0)
+            return undefined;
+        return { start: hs[index].line, end: sectionEnd(lines, hs, index) };
+    };
+    for (const section of patch.sections) {
+        const target = find((h) => h.level === section.level && h.text === section.text);
+        if (target)
+            ops.push({ ...target, replacement: [...section.lines, ''], heading: section.text });
+        else
+            additions.push(section.lines);
+    }
+    for (const heading of patch.remove) {
+        const target = find((h) => h.text === heading);
+        if (target)
+            ops.push({ ...target, replacement: [], heading });
+        else
+            warnings.push(`${patchFile}: the rule has no section "${heading}" to remove`);
+    }
+    ops.sort((a, b) => b.start - a.start);
+    let limit = Number.POSITIVE_INFINITY;
+    for (const op of ops) {
+        if (op.end > limit) {
+            warnings.push(`${patchFile}: section "${op.heading}" overlaps another change and was skipped`);
+            continue;
+        }
+        touched.push({ heading: op.heading, hash: hash(lines.slice(op.start, op.end).join('\n')) });
+        lines.splice(op.start, op.end - op.start, ...op.replacement);
+        limit = op.start;
+    }
+    const tail = [...additions, ...(patch.preamble.length > 0 ? [patch.preamble] : [])];
+    let body = trimBlank(lines).join('\n');
+    for (const block of tail)
+        body += `\n\n${block.join('\n')}`;
+    body += '\n';
+    return {
+        text: rule.hasFrontmatter ? withFrontmatter(rule.data, body) : body,
+        touched: touched.sort((a, b) => a.heading.localeCompare(b.heading)),
+        warnings,
+    };
+}
+/** Raises every heading level by `by`, outside code blocks, so a rule fits under a block heading. */
+export function demoteHeadings(text, by) {
+    const lines = text.split('\n');
+    for (const h of headings(lines)) {
+        const level = Math.min(6, h.level + by);
+        lines[h.line] = `${'#'.repeat(level)} ${h.text}`;
+    }
+    return lines.join('\n');
+}