@tenphi/harnesspm 0.0.0-snapshot.7984e7b

package/dist/lock.js

@@ -0,0 +1,102 @@
+// harnesspm.lock.json (spec 6.3). The lock holds no per-machine state.
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { hash, isFile, isRecord, readJsonIfExists, readText, relPosix } from './util.js';
+export const LOCK_FILE = 'harnesspm.lock.json';
+function hashDir(dir) {
+    const parts = [];
+    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 (entry.isFile())
+                parts.push(`${relPosix(dir, full)}\n${readText(full)}`);
+        }
+    };
+    walk(dir);
+    return hash(parts.join('\n\0\n'));
+}
+function packageLockEntry(projectDir, name) {
+    const lock = readJsonIfExists(path.join(projectDir, 'package-lock.json'));
+    if (!isRecord(lock) || !isRecord(lock['packages']))
+        return {};
+    const entry = lock['packages'][`node_modules/${name}`];
+    if (!isRecord(entry))
+        return {};
+    return {
+        ...(typeof entry['resolved'] === 'string' ? { resolved: entry['resolved'] } : {}),
+        ...(typeof entry['integrity'] === 'string' ? { integrity: entry['integrity'] } : {}),
+    };
+}
+export function buildLock(res, previous) {
+    const packages = {};
+    for (const pkg of res.packages) {
+        if (pkg.layer === 'project') {
+            packages[pkg.name] = { version: pkg.version, plugin: pkg.plugin, project: true };
+            continue;
+        }
+        const entry = { version: pkg.version, plugin: pkg.plugin, ...packageLockEntry(res.projectDir, pkg.name) };
+        if (res.config.trust[pkg.name] === 'pin') {
+            const approved = previous?.packages[pkg.name]?.approved;
+            entry.approved = approved ?? pkg.version;
+        }
+        packages[pkg.name] = entry;
+    }
+    const units = {};
+    for (const rule of res.rules)
+        units[rule.id] = { kind: 'rules', hash: hash(rule.text) };
+    for (const skill of res.skills)
+        units[skill.id] = { kind: 'skills', hash: hashDir(skill.dir) };
+    for (const docs of res.docs)
+        units[docs.id] = { kind: 'docs', hash: hashDir(docs.dir) };
+    for (const script of res.scripts)
+        units[script.id] = { kind: 'scripts', hash: isFile(script.file) ? hash(readText(script.file)) : 'missing' };
+    for (const hook of res.hooks)
+        units[hook.id] = { kind: 'hooks', hash: hash(JSON.stringify([hook.event, hook.matchers, hook.run, hook.timeout ?? null])) };
+    for (const server of res.mcp)
+        units[server.id] = { kind: 'mcp', hash: hash(JSON.stringify(server.config)) };
+    for (const perms of res.permissions)
+        units[perms.id] = { kind: 'permissions', hash: hash(JSON.stringify([perms.deny, perms.ask])) };
+    for (const agent of res.agents)
+        units[agent.id] = { kind: 'agents', hash: hash(readText(agent.file)) };
+    const patches = {};
+    for (const rule of res.rules) {
+        for (const applied of rule.patches) {
+            if (applied.sections.length === 0)
+                continue;
+            const byPatch = (patches[rule.id] ??= {});
+            byPatch[applied.patch] = Object.fromEntries(applied.sections.map((s) => [s.heading, s.hash]));
+        }
+    }
+    return { lockfileVersion: 1, packages: sortKeys(packages), units: sortKeys(units), patches: sortKeys(patches) };
+}
+function sortKeys(record) {
+    return Object.fromEntries(Object.entries(record).sort(([a], [b]) => a.localeCompare(b)));
+}
+export function serializeLock(lock) {
+    return `${JSON.stringify(lock, null, 2)}\n`;
+}
+export function readLock(projectDir) {
+    const raw = readJsonIfExists(path.join(projectDir, LOCK_FILE));
+    if (!isRecord(raw) || raw['lockfileVersion'] !== 1)
+        return undefined;
+    return raw;
+}
+/** Warnings for upstream changes to sections that a patch replaces or removes (spec 3.4). */
+export function patchDrift(previous, next) {
+    if (!previous)
+        return [];
+    const warnings = [];
+    for (const [ruleId, byPatch] of Object.entries(next.patches)) {
+        for (const [patch, sections] of Object.entries(byPatch)) {
+            for (const [heading, sectionHash] of Object.entries(sections)) {
+                const before = previous.patches[ruleId]?.[patch]?.[heading];
+                if (before !== undefined && before !== sectionHash) {
+                    warnings.push(`${ruleId}: upstream changed the section "${heading}" that ${patch} changes. Check that the patch is still right.`);
+                }
+            }
+        }
+    }
+    return warnings;
+}

package/dist/manifest.js

@@ -0,0 +1,154 @@
+// Reading one harness package (spec chapter 2).
+import * as path from 'node:path';
+import { parseFrontmatter, stringList } from './frontmatter.js';
+import { HarnessError, isDir, isFile, isRecord, listDir, readJson, readJsonIfExists, readText } from './util.js';
+export const NS = 'dev.harnesspm';
+export const PLUGIN_SCHEMA = 'https://agent-plugins.org/schemas/1.0.0/plugin.schema.json';
+const CORE_FIELDS = new Set(['$schema', 'name', 'version', 'description', 'author', 'homepage', 'repository', 'license', 'keywords', 'extensions']);
+const EXT_FIELDS = new Set(['extends', 'exclude', 'replace', 'patch', 'docs', 'scripts', 'projects']);
+const PLUGIN_NAME = /^[a-z0-9][a-z0-9.-]*$/;
+function stringMap(value, field, problems) {
+    if (value === undefined)
+        return {};
+    if (isRecord(value) && Object.values(value).every((v) => typeof v === 'string'))
+        return value;
+    problems.push(`"${field}" must map strings to strings`);
+    return {};
+}
+function repositoryUrl(value) {
+    if (typeof value === 'string')
+        return value;
+    if (isRecord(value) && typeof value['url'] === 'string')
+        return value['url'];
+    return undefined;
+}
+/** Reads `<dir>/harness/plugin.json`. Returns undefined when the folder has no harness. */
+export function loadHarnessPackage(dir, layer) {
+    const harnessDir = path.join(dir, 'harness');
+    const manifestFile = path.join(harnessDir, 'plugin.json');
+    if (!isFile(manifestFile))
+        return undefined;
+    const manifest = readJson(manifestFile);
+    if (!isRecord(manifest))
+        throw new HarnessError(`${manifestFile} must be a JSON object`);
+    const pkgJson = readJsonIfExists(path.join(dir, 'package.json'));
+    const pkg = isRecord(pkgJson) ? pkgJson : {};
+    const problems = [];
+    if (manifest['$schema'] !== PLUGIN_SCHEMA)
+        problems.push(`"$schema" must be "${PLUGIN_SCHEMA}"`);
+    for (const key of Object.keys(manifest))
+        if (!CORE_FIELDS.has(key))
+            problems.push(`unknown field "${key}" in plugin.json`);
+    const plugin = manifest['name'];
+    if (typeof plugin !== 'string' || !PLUGIN_NAME.test(plugin)) {
+        throw new HarnessError(`${manifestFile}: "name" must be lowercase letters, digits, "-" and "."`);
+    }
+    const ext = parseExtension(manifest, problems);
+    const version = typeof manifest['version'] === 'string' ? manifest['version'] : typeof pkg['version'] === 'string' ? pkg['version'] : '0.0.0';
+    const description = typeof manifest['description'] === 'string' ? manifest['description'] : undefined;
+    const repository = repositoryUrl(manifest['repository']) ?? repositoryUrl(pkg['repository']);
+    return {
+        name: typeof pkg['name'] === 'string' ? pkg['name'] : path.basename(dir),
+        version,
+        plugin,
+        ...(description !== undefined ? { description } : {}),
+        ...(repository !== undefined ? { repository } : {}),
+        dir,
+        harnessDir,
+        ext,
+        layer,
+        problems,
+    };
+}
+/** Reads `extensions["dev.harnesspm"]` of a manifest. Problems go into `problems`. */
+export function parseExtension(manifest, problems) {
+    const extensions = manifest['extensions'];
+    const rawExt = isRecord(extensions) && isRecord(extensions[NS]) ? extensions[NS] : {};
+    for (const key of Object.keys(rawExt))
+        if (!EXT_FIELDS.has(key))
+            problems.push(`unknown field "${key}" in extensions["${NS}"]`);
+    const list = (field) => {
+        const value = rawExt[field];
+        if (value === undefined)
+            return [];
+        const result = stringList(value);
+        if (!result || typeof value === 'string') {
+            problems.push(`"${field}" must be an array of strings`);
+            return [];
+        }
+        return result;
+    };
+    const scripts = {};
+    if (rawExt['scripts'] !== undefined) {
+        if (!isRecord(rawExt['scripts']))
+            problems.push('"scripts" must be an object');
+        else {
+            for (const [name, def] of Object.entries(rawExt['scripts'])) {
+                if (!isRecord(def) || typeof def['file'] !== 'string') {
+                    problems.push(`script "${name}" needs a "file"`);
+                    continue;
+                }
+                scripts[name] = {
+                    file: def['file'],
+                    ...(typeof def['description'] === 'string' ? { description: def['description'] } : {}),
+                    ...(def['allow'] === true ? { allow: true } : {}),
+                };
+            }
+        }
+    }
+    let docs;
+    if (rawExt['docs'] !== undefined) {
+        if (typeof rawExt['docs'] === 'string')
+            docs = rawExt['docs'];
+        else
+            problems.push('"docs" must be a path');
+    }
+    return {
+        extends: list('extends'),
+        exclude: list('exclude'),
+        replace: stringMap(rawExt['replace'], 'replace', problems),
+        patch: stringMap(rawExt['patch'], 'patch', problems),
+        ...(docs !== undefined ? { docs } : {}),
+        scripts,
+        projects: stringMap(rawExt['projects'], 'projects', problems),
+    };
+}
+/** Finds a package's units. Files in `skip` (replacements and patches) are not units. */
+export function discoverUnits(pkg, skip) {
+    const rulesDir = path.join(pkg.harnessDir, NS, 'rules');
+    const rules = listDir(rulesDir)
+        .filter((f) => f.endsWith('.md') && !skip.has(path.join(rulesDir, f)))
+        .map((f) => {
+        const name = f.slice(0, -3);
+        return { kind: 'rules', id: `${pkg.plugin}:rules/${name}`, name, pkg, file: path.join(rulesDir, f) };
+    });
+    const skillsDir = path.join(pkg.harnessDir, 'skills');
+    const skills = listDir(skillsDir)
+        .filter((f) => isFile(path.join(skillsDir, f, 'SKILL.md')))
+        .map((name) => ({ kind: 'skills', id: `${pkg.plugin}:skills/${name}`, name, pkg, dir: path.join(skillsDir, name) }));
+    const units = { rules, skills };
+    if (pkg.ext.docs !== undefined) {
+        const dir = path.resolve(pkg.harnessDir, pkg.ext.docs);
+        if (isDir(dir))
+            units.docs = { kind: 'docs', id: `${pkg.plugin}:docs`, pkg, dir };
+    }
+    return units;
+}
+/** Reads a rule's activation from its frontmatter (spec 2.5). */
+export function ruleMeta(text, fallbackTitle, file) {
+    const { data, body } = parseFrontmatter(text, file);
+    const description = typeof data['description'] === 'string' ? data['description'] : undefined;
+    const paths = stringList(data['paths']);
+    const activation = paths ? 'file' : description !== undefined ? 'demand' : 'always';
+    const titleMatch = /^#\s+(.+?)\s*$/m.exec(body);
+    return {
+        activation,
+        ...(description !== undefined ? { description } : {}),
+        ...(paths ? { paths } : {}),
+        title: titleMatch ? titleMatch[1] : fallbackTitle,
+        body,
+    };
+}
+export function readRule(file) {
+    return readText(file);
+}

package/dist/new.js

@@ -0,0 +1,223 @@
+// harnesspm new: units from templates, and patches (spec 10.2).
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { loadAdded, remoteKey } from './added.js';
+import { CONFIG_FILE } from './config.js';
+import { NS, PLUGIN_SCHEMA } from './manifest.js';
+import { headings } from './sections.js';
+import { parseFrontmatter } from './frontmatter.js';
+import { HarnessError, ensureDir, exists, isFile, isRecord, readJson, readJsonIfExists, relPosix } from './util.js';
+export const KINDS = ['rule', 'skill', 'agent', 'script', 'hook', 'mcp'];
+const MCP_TEMPLATE = `// A minimal MCP server over stdio. Replace the tool with your own.
+const send = (message) => process.stdout.write(JSON.stringify(message) + '\\n');
+let buffer = '';
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', (chunk) => {
+  buffer += chunk;
+  let index;
+  while ((index = buffer.indexOf('\\n')) >= 0) {
+    const line = buffer.slice(0, index).trim();
+    buffer = buffer.slice(index + 1);
+    if (!line) continue;
+    const message = JSON.parse(line);
+    if (message.method === 'initialize') {
+      send({ jsonrpc: '2.0', id: message.id, result: { protocolVersion: message.params?.protocolVersion ?? '2025-06-18', capabilities: { tools: {} }, serverInfo: { name: 'NAME', version: '0.1.0' } } });
+    } else if (message.method === 'tools/list') {
+      send({ jsonrpc: '2.0', id: message.id, result: { tools: [{ name: 'hello', description: 'Says hello', inputSchema: { type: 'object', properties: {} } }] } });
+    } else if (message.method === 'tools/call') {
+      send({ jsonrpc: '2.0', id: message.id, result: { content: [{ type: 'text', text: 'Hello from NAME' }] } });
+    } else if (message.id !== undefined) {
+      send({ jsonrpc: '2.0', id: message.id, error: { code: -32601, message: 'Method not found' } });
+    }
+  }
+});
+`;
+const title = (name) => name.replace(/[-_]+/g, ' ').replace(/^\w/, (c) => c.toUpperCase());
+function writeNew(file, content) {
+    if (exists(file))
+        throw new HarnessError(`${file} already exists`);
+    ensureDir(path.dirname(file));
+    fs.writeFileSync(file, content);
+}
+function editManifest(file, edit, plugin) {
+    const raw = readJsonIfExists(file);
+    const manifest = isRecord(raw) ? raw : { $schema: PLUGIN_SCHEMA, name: plugin };
+    const extensions = isRecord(manifest['extensions']) ? manifest['extensions'] : {};
+    const ext = isRecord(extensions[NS]) ? extensions[NS] : {};
+    edit(ext);
+    extensions[NS] = ext;
+    manifest['extensions'] = extensions;
+    ensureDir(path.dirname(file));
+    fs.writeFileSync(file, `${JSON.stringify(manifest, null, 2)}\n`);
+}
+function pluginNameFor(projectDir) {
+    const pkg = readJsonIfExists(path.join(projectDir, 'package.json'));
+    const name = isRecord(pkg) && typeof pkg['name'] === 'string' ? pkg['name'] : path.basename(projectDir);
+    return name.replace(/^@[^/]+\//, '').toLowerCase().replace(/[^a-z0-9.-]+/g, '-').replace(/^[^a-z0-9]+/, '') || 'project';
+}
+/** Where `new` writes: the project's harness/, an added harness (`--to`), or its entry (`--entry`). */
+export function resolveTarget(projectDir, options) {
+    if (options.to === undefined) {
+        if (options.entry)
+            throw new HarnessError('--entry needs --to <plugin>');
+        const dir = path.join(projectDir, 'harness');
+        const manifest = path.join(dir, 'plugin.json');
+        let plugin = pluginNameFor(projectDir);
+        if (isFile(manifest)) {
+            const raw = readJson(manifest);
+            if (isRecord(raw) && typeof raw['name'] === 'string')
+                plugin = raw['name'];
+        }
+        else {
+            writeNew(manifest, `${JSON.stringify({ $schema: PLUGIN_SCHEMA, name: plugin }, null, 2)}\n`);
+        }
+        return { dir, plugin, manifest, entry: false, label: `the project harness (${relPosix(projectDir, dir)})` };
+    }
+    const warnings = [];
+    const harness = loadAdded(projectDir, warnings).find((h) => h.pkg.plugin === options.to);
+    if (!harness)
+        throw new HarnessError(`No added harness with the plugin name "${options.to}". See \`npx harnesspm status\`.`);
+    if (!harness.source.editable)
+        throw new HarnessError(`${harness.source.spec} comes from npm and cannot be edited here. Change it in its own repository.`);
+    const manifest = path.join(harness.pkg.harnessDir, 'plugin.json');
+    if (!options.entry)
+        return { dir: harness.pkg.harnessDir, plugin: harness.pkg.plugin, manifest, entry: false, label: `${harness.pkg.plugin} (${harness.source.dir})` };
+    const key = remoteKey(projectDir);
+    if (key === undefined)
+        throw new HarnessError('--entry needs a repository with an "origin" remote');
+    let rel = harness.pkg.ext.projects[key];
+    if (rel === undefined) {
+        rel = `./projects/${key.split('/').pop()}`;
+        editManifest(manifest, (ext) => {
+            const projects = isRecord(ext['projects']) ? ext['projects'] : {};
+            projects[key] = rel;
+            ext['projects'] = projects;
+        }, harness.pkg.plugin);
+    }
+    const dir = path.resolve(harness.pkg.harnessDir, rel);
+    ensureDir(dir);
+    return { dir, plugin: harness.pkg.plugin, manifest: path.join(dir, 'plugin.json'), entry: true, label: `the entry of ${harness.pkg.plugin} for ${key} (${dir})` };
+}
+/** Creates a unit. Returns the files it wrote. */
+export function createUnit(target, kind, name) {
+    if (!/^[a-z0-9][a-z0-9-]*$/.test(name))
+        throw new HarnessError('Use lowercase letters, digits and "-" in names');
+    if (target.entry && (kind === 'script' || kind === 'hook' || kind === 'mcp')) {
+        throw new HarnessError(`A project entry holds rules, skills, sub-agents and docs. Add the ${kind} to the harness itself (without --entry).`);
+    }
+    const files = [];
+    const add = (file, content) => {
+        writeNew(file, content);
+        files.push(file);
+    };
+    const scriptFile = (script) => path.join(target.dir, NS, 'scripts', `${script}.mjs`);
+    const declareScript = (script, description) => {
+        editManifest(target.manifest, (ext) => {
+            const scripts = isRecord(ext['scripts']) ? ext['scripts'] : {};
+            if (scripts[script] !== undefined)
+                throw new HarnessError(`The script "${script}" already exists`);
+            scripts[script] = { file: `./${NS}/scripts/${script}.mjs`, ...(description !== undefined ? { description } : {}) };
+            ext['scripts'] = scripts;
+        }, target.plugin);
+        files.push(target.manifest);
+    };
+    switch (kind) {
+        case 'rule':
+            add(path.join(target.dir, NS, 'rules', `${name}.md`), `# ${title(name)}\n\n- Write the rule here. Keep an always-on rule short: it is in every session.\n`);
+            break;
+        case 'skill': {
+            const skill = name.startsWith(`${target.plugin}-`) ? name : `${target.plugin}-${name}`;
+            add(path.join(target.dir, 'skills', skill, 'SKILL.md'), `---\nname: ${skill}\ndescription: What the skill does. Use when the user asks to … or mentions ….\n---\n\n# ${title(name)}\n\n1. First step.\n2. Next step.\n`);
+            break;
+        }
+        case 'agent':
+            add(path.join(target.dir, NS, 'agents', `${name}.md`), `---\nname: ${name}\ndescription: What the sub-agent does. Use when ….\n---\n\nInstructions for the sub-agent.\n`);
+            break;
+        case 'script':
+            add(scriptFile(name), `// Run it with \`npx harnesspm run ${target.plugin}:${name} -- <args>\`.\n// PLUGIN_ROOT, PLUGIN_DATA, HARNESSPM_PROJECT_DIR and HARNESSPM_AGENT are set by the runner.\nconsole.log('${name}', process.argv.slice(2).join(' '));\n`);
+            declareScript(name, `What ${name} does`);
+            break;
+        case 'hook': {
+            add(scriptFile(name), `// A hook script: the agent's JSON event is on stdin. Exit 0 to continue, 2 to block (reason on stderr).\nimport { readFileSync } from 'node:fs';\nconst event = JSON.parse(readFileSync(0, 'utf8') || '{}');\nvoid event;\nprocess.exit(0);\n`);
+            declareScript(name);
+            const hooksFile = path.join(target.dir, NS, 'hooks.json');
+            const raw = readJsonIfExists(hooksFile);
+            const data = isRecord(raw) ? raw : {};
+            const hooks = isRecord(data['hooks']) ? data['hooks'] : {};
+            const list = Array.isArray(hooks['PostToolUse']) ? hooks['PostToolUse'] : [];
+            list.push({ id: name, matcher: { claude: 'Edit|Write', codex: 'apply_patch' }, run: name, timeout: 30 });
+            hooks['PostToolUse'] = list;
+            data['hooks'] = hooks;
+            fs.writeFileSync(hooksFile, `${JSON.stringify(data, null, 2)}\n`);
+            files.push(hooksFile);
+            break;
+        }
+        case 'mcp': {
+            const script = `${name}-mcp`;
+            add(scriptFile(script), MCP_TEMPLATE.replaceAll('NAME', `${target.plugin}-${name}`));
+            const mcpFile = path.join(target.dir, 'mcp.json');
+            const raw = readJsonIfExists(mcpFile);
+            const data = isRecord(raw) ? raw : { $schema: 'https://agent-plugins.org/schemas/1.0.0/mcp.schema.json' };
+            const servers = isRecord(data['mcpServers']) ? data['mcpServers'] : {};
+            if (servers[name] !== undefined)
+                throw new HarnessError(`The MCP server "${name}" already exists`);
+            servers[name] = { type: 'stdio', command: 'node', args: [`\${PLUGIN_ROOT}/${NS}/scripts/${script}.mjs`] };
+            data['mcpServers'] = servers;
+            fs.writeFileSync(mcpFile, `${JSON.stringify(data, null, 2)}\n`);
+            files.push(mcpFile);
+            break;
+        }
+    }
+    return files;
+}
+/** The sections of a rule below its title: what a patch can replace. */
+function patchTemplate(body) {
+    const lines = body.split('\n');
+    const hs = headings(lines);
+    const top = hs[0]?.level === 1 ? 1 : 0;
+    const first = hs.find((h) => h.level > top);
+    if (first)
+        return `${lines.slice(first.line).join('\n').trim()}\n`;
+    // Without sections below the title, the title's section is the whole rule: a patch of it replaces the rule.
+    return hs[0] ? `${lines.slice(hs[0].line).join('\n').trim()}\n` : '';
+}
+/**
+ * Writes a patch with a copy of the rule's sections and registers it (spec 10.2): in harness/plugin.json
+ * when the rule reaches the project through its own harness's `extends`, otherwise in harnesspm.json;
+ * with `--to`, in that added harness or its entry.
+ */
+export function createPatch(projectDir, res, ruleId, options) {
+    const rule = res.rules.find((r) => r.id === ruleId);
+    if (!rule)
+        throw new HarnessError(`No rule ${ruleId}. Find IDs in the AGENTS.md block or with \`npx harnesspm why <ID>\`.`);
+    const fileName = `${ruleId.replace(':rules/', '-').replace(/[^a-z0-9.-]+/gi, '-')}.patch.md`;
+    const body = parseFrontmatter(rule.text, rule.source).body;
+    const content = patchTemplate(body) || `Text to add at the end of ${ruleId}.\n`;
+    const register = (manifest, baseDir, file, plugin) => {
+        writeNew(file, content);
+        editManifest(manifest, (ext) => {
+            const patch = isRecord(ext['patch']) ? ext['patch'] : {};
+            patch[ruleId] = `./${relPosix(baseDir, file)}`;
+            ext['patch'] = patch;
+        }, plugin);
+        return { file, registeredIn: manifest };
+    };
+    if (options.to !== undefined) {
+        const target = resolveTarget(projectDir, options);
+        return register(target.manifest, target.dir, path.join(target.dir, NS, 'patches', fileName), target.plugin);
+    }
+    const own = res.packages.find((p) => p.layer === 'project');
+    if (own && own.closure.has(rule.pkg.name)) {
+        return register(path.join(own.harnessDir, 'plugin.json'), own.harnessDir, path.join(own.harnessDir, NS, 'patches', fileName), own.plugin);
+    }
+    const file = path.join(projectDir, 'harnesspm', 'patches', fileName);
+    writeNew(file, content);
+    const configFile = path.join(projectDir, CONFIG_FILE);
+    const raw = readJsonIfExists(configFile);
+    const config = isRecord(raw) ? raw : {};
+    const patch = isRecord(config['patch']) ? config['patch'] : {};
+    patch[ruleId] = `./${relPosix(projectDir, file)}`;
+    config['patch'] = patch;
+    fs.writeFileSync(configFile, `${JSON.stringify(config, null, 2)}\n`);
+    return { file, registeredIn: configFile };
+}