agents-md-kit 0.0.0-stage → 0.1.0

package/src/blocks.js

@@ -0,0 +1,132 @@
+// Managed blocks: regions between BEGIN/END markers that the installer owns.
+//
+//   style=html: <!-- BEGIN agent-kit:<id> -->  ...  <!-- END agent-kit:<id> -->
+//   style=hash: # BEGIN agent-kit:<id>         ...  # END agent-kit:<id>
+//
+// Content outside the markers is preserved byte for byte. When updating an
+// existing file, the inserted block uses that file's line ending (LF or CRLF).
+
+const MARKER_RE = /^(?:<!--\s*(BEGIN|END) agent-kit:([a-z0-9][a-z0-9-]*)\s*-->|#\s*(BEGIN|END) agent-kit:([a-z0-9][a-z0-9-]*))$/;
+// Anything that looks like it is trying to be a marker.
+const MARKERISH_RE = /\b(BEGIN|END)\s+agent-kit:/;
+
+export function markers(/** @type {string} */ id, style = 'html') {
+  if (style === 'hash') return { begin: `# BEGIN agent-kit:${id}`, end: `# END agent-kit:${id}` };
+  return { begin: `<!-- BEGIN agent-kit:${id} -->`, end: `<!-- END agent-kit:${id} -->` };
+}
+
+/** "\r\n" if the first line break in the text is CRLF, else "\n". */
+export function detectEol(/** @type {string} */ text) {
+  const i = text.indexOf('\n');
+  return i > 0 && text[i - 1] === '\r' ? '\r\n' : '\n';
+}
+
+/** Split into lines, remembering each line's start/end offsets (end excludes the line break). */
+function splitLines(/** @type {string} */ text) {
+  const lines = [];
+  let start = 0;
+  while (start <= text.length) {
+    let nl = text.indexOf('\n', start);
+    const last = nl === -1;
+    if (last) nl = text.length;
+    const end = nl > start && text[nl - 1] === '\r' ? nl - 1 : nl;
+    lines.push({ text: text.slice(start, end), start, end, index: lines.length });
+    if (last) break;
+    start = nl + 1;
+  }
+  return lines;
+}
+
+/**
+ * Find managed blocks in text.
+ * Returns { blocks: [{ id, style, start, end }], errors: [string] }.
+ * `start` is the offset of the BEGIN line, `end` the offset just after the END
+ * marker text (before its line break). Any error means the file must not be edited.
+ */
+export function findBlocks(/** @type {string} */ text) {
+  const blocks = [];
+  const errors = [];
+  const seen = new Set();
+  let open = null;
+  for (const line of splitLines(text)) {
+    const trimmed = line.text.trim();
+    const m = MARKER_RE.exec(trimmed);
+    if (!m) {
+      if (MARKERISH_RE.test(line.text)) errors.push(`line ${line.index + 1}: unrecognized agent-kit marker`);
+      continue;
+    }
+    const kind = m[1] ?? m[3];
+    const id = m[2] ?? m[4];
+    const style = m[1] ? 'html' : 'hash';
+    if (kind === 'BEGIN') {
+      if (open) {
+        errors.push(`line ${line.index + 1}: BEGIN ${id} inside open block ${open.id} (nested)`);
+        continue;
+      }
+      if (seen.has(id)) errors.push(`line ${line.index + 1}: duplicate block ${id}`);
+      seen.add(id);
+      open = { id, style, start: line.start, line: line.index + 1 };
+    } else {
+      if (!open) {
+        errors.push(`line ${line.index + 1}: END ${id} without BEGIN`);
+        continue;
+      }
+      if (open.id !== id || open.style !== style) {
+        errors.push(`line ${line.index + 1}: END ${id} does not match BEGIN ${open.id} on line ${open.line}`);
+        open = null;
+        continue;
+      }
+      blocks.push({ id, style, start: open.start, end: line.end });
+      open = null;
+    }
+  }
+  if (open) errors.push(`line ${open.line}: BEGIN ${open.id} is never closed`);
+  return { blocks, errors };
+}
+
+/** Render a block (markers + content) with the given line ending, without a trailing break. */
+export function renderBlock(/** @type {string} */ id, /** @type {string} */ style, /** @type {string} */ content, eol = '\n') {
+  const { begin, end } = markers(id, style);
+  const body = content.replace(/\r\n/g, '\n').replace(/\n+$/, '');
+  const lines = [begin, ...(body ? body.split('\n') : []), end];
+  return lines.join(eol);
+}
+
+/** Throws if fragment content itself contains marker-like lines. */
+export function assertFragmentClean(/** @type {string} */ content, /** @type {string} */ label) {
+  if (MARKERISH_RE.test(content)) throw new Error(`${label}: fragment contains an agent-kit marker`);
+}
+
+/**
+ * Compute the new text for a file after inserting/updating one block.
+ * existing: current file text, or null if the file does not exist.
+ * Returns { status: 'block-create'|'block-update'|'block-unchanged'|'conflict', text?, reason? }.
+ */
+export function applyBlock(
+  /** @type {string | null} */ existing,
+  /** @type {{ id: string, style?: string, content: string, title?: string | null }} */ { id, style = 'html', content, title = null },
+) {
+  if (existing === null) {
+    const block = renderBlock(id, style, content, '\n');
+    return { status: 'block-create', text: (title ? `${title}\n\n` : '') + block + '\n' };
+  }
+  const { blocks, errors } = findBlocks(existing);
+  if (errors.length) return { status: 'conflict', reason: `malformed markers: ${errors.join('; ')}` };
+  const eol = detectEol(existing);
+  const block = renderBlock(id, style, content, eol);
+  const current = blocks.find((b) => b.id === id);
+  if (current) {
+    if (current.style !== style) {
+      return { status: 'conflict', reason: `block ${id} uses ${current.style} markers, expected ${style}` };
+    }
+    const text = existing.slice(0, current.start) + block + existing.slice(current.end);
+    return text === existing ? { status: 'block-unchanged', text } : { status: 'block-update', text };
+  }
+  let text = existing;
+  if (text.length > 0) {
+    if (!text.endsWith('\n')) text += eol;
+    text += eol;
+  }
+  text += block + eol;
+  return { status: 'block-create', text };
+}

package/src/cli.js

@@ -0,0 +1,159 @@
+// agents-md-kit CLI logic. Exit codes: 0 success, 1 error, 2 install finished with conflicts.
+
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { install, UsageError } from './install.js';
+import { validateRepo, validateTemplate } from './validate.js';
+import { loadUnits } from './manifest.js';
+
+const KIT_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+
+const USAGE = `Usage:
+  agents-md-kit install [--preset <name>]... [--pack <name>]... [--target <dir>] [--apply]
+  agents-md-kit validate [--target <dir>] [--template]
+  agents-md-kit list
+
+install is a dry run unless --apply is given. core is always installed.`;
+
+export function parseArgs(/** @type {string[]} */ argv) {
+  const [command, ...rest] = argv;
+  /** @type {{ command: string, presets: string[], packs: string[], target: string, apply: boolean, template: boolean, help: boolean }} */
+  const opts = { command, presets: [], packs: [], target: '.', apply: false, template: false, help: false };
+  /** @type {Record<string, string[]>} */
+  const allowed = {
+    install: ['--preset', '--pack', '--target', '--apply'],
+    validate: ['--target', '--template'],
+    list: [],
+  };
+  if (!command || command === '--help' || command === '-h' || command === 'help') {
+    opts.help = true;
+    return opts;
+  }
+  if (!(command in allowed)) throw new UsageError(`unknown command "${command}"\n\n${USAGE}`);
+  for (let i = 0; i < rest.length; i++) {
+    let arg = rest[i];
+    let value;
+    const eq = arg.indexOf('=');
+    if (arg.startsWith('--') && eq > 0) {
+      value = arg.slice(eq + 1);
+      arg = arg.slice(0, eq);
+    }
+    if (arg === '--help' || arg === '-h') {
+      opts.help = true;
+      continue;
+    }
+    if (!allowed[command].includes(arg)) throw new UsageError(`unknown option "${arg}" for ${command}\n\n${USAGE}`);
+    const needsValue = ['--preset', '--pack', '--target'].includes(arg);
+    if (needsValue) {
+      if (value === undefined) {
+        value = rest[++i];
+        if (value === undefined || value.startsWith('--')) throw new UsageError(`${arg} needs a value`);
+      }
+      if (arg === '--preset') opts.presets.push(value);
+      else if (arg === '--pack') opts.packs.push(value);
+      else opts.target = value;
+    } else {
+      if (value !== undefined) throw new UsageError(`${arg} takes no value`);
+      if (arg === '--apply') opts.apply = true;
+      if (arg === '--template') opts.template = true;
+    }
+  }
+  return opts;
+}
+
+/** @typedef {(line: string) => void} Print */
+
+function printReport(
+  /** @type {{ errors: string[], warnings: string[], notes: string[] }} */ { errors, warnings, notes },
+  /** @type {Print} */ out,
+) {
+  for (const e of errors) out(`error    ${e}`);
+  for (const w of warnings) out(`warning  ${w}`);
+  for (const n of notes) out(`note     ${n}`);
+}
+
+export function main(/** @type {string[]} */ argv, { out = console.log, err = console.error, cwd = process.cwd(), kitRoot = KIT_ROOT } = {}) {
+  let opts;
+  try {
+    opts = parseArgs(argv);
+  } catch (e) {
+    err(/** @type {Error} */ (e).message);
+    return 1;
+  }
+  if (opts.help) {
+    out(USAGE);
+    return 0;
+  }
+  const target = path.resolve(cwd, opts.target);
+  try {
+    if (opts.command === 'list') {
+      const units = loadUnits(kitRoot);
+      out(`core (always installed)\n  ${units.core.description}`);
+      for (const [label, map] of /** @type {const} */ ([
+        ['packs (--pack)', units.packs],
+        ['presets (--preset)', units.presets],
+      ])) {
+        out(`\n${label}:`);
+        if (map.size === 0) out('  (none)');
+        for (const u of map.values()) {
+          const inc = u.implies.length ? ` (also installs pack ${u.implies.join(', ')})` : '';
+          out(`  ${u.name.padEnd(18)} ${u.description}${inc}`);
+        }
+      }
+      return 0;
+    }
+    if (opts.command === 'validate') {
+      const report = opts.template ? validateTemplate({ kitRoot }) : validateRepo({ target, kitRoot });
+      printReport(report, out);
+      const what = opts.template ? `template ${kitRoot}` : target;
+      out(
+        report.errors.length
+          ? `\nvalidate: FAILED with ${report.errors.length} error(s) in ${what}`
+          : `\nvalidate: OK (${report.warnings.length} warning(s)) in ${what}`,
+      );
+      return report.errors.length ? 1 : 0;
+    }
+    // install
+    const res = install({ kitRoot, target, presets: opts.presets, packs: opts.packs, apply: opts.apply });
+    const width = Math.max(...res.actions.map((a) => a.op.length), 6);
+    for (const a of res.actions) out(`${a.op.padEnd(width)}  ${a.path}${a.detail ? `  (${a.detail})` : ''}`);
+    /** @type {Record<string, number>} */
+    const counts = {};
+    for (const a of res.actions) {
+      const key = a.op.startsWith('conflict') ? 'conflict' : a.op.startsWith('skip (needs') ? 'skip (needs pack)' : a.op;
+      counts[key] = (counts[key] ?? 0) + 1;
+    }
+    out('');
+    out(`Summary: ${Object.entries(counts).map(([k, v]) => `${v} ${k}`).join(', ')}`);
+    for (const n of res.notes) out(`note: ${n}`);
+    if (res.conflicts) out(`${res.conflicts} conflict(s): review each <path>.new, merge by hand, then delete the .new file.`);
+    if (!res.applied) {
+      out(`Dry run: nothing was written to ${res.root}. Re-run with --apply to write ${res.writes} file(s).`);
+    } else {
+      out(`Applied: wrote ${res.writes} file(s) to ${res.root}.`);
+      const binAbs = path.join(kitRoot, 'bin', 'agent-kit.js');
+      const binRel = path.relative(cwd, binAbs);
+      const bin = binRel.startsWith('..') || path.isAbsolute(binRel) ? binAbs : binRel;
+      const q = (/** @type {string} */ s) => (/\s/.test(s) ? `"${s}"` : s);
+      // Installed from npm (npx or a dependency): the path into node_modules is no use to the reader.
+      const viaNpm = kitRoot.split(path.sep).includes('node_modules');
+      out(`Next: ${viaNpm ? 'npx agents-md-kit' : `node ${q(bin)}`} validate --target ${q(opts.target)}`);
+    }
+    for (const doc of res.nextSteps) out(`Next steps for this preset: ${path.join(res.root, ...doc.split('/'))}`);
+    if (res.commands.length) {
+      out('');
+      out(
+        `Run these yourself in ${res.root}${res.applied ? '' : ' (after --apply)'}; ` +
+          'agents-md-kit never edits package.json, pyproject.toml, README.md or lockfiles:',
+      );
+      for (const c of res.commands) out(`  ${c}`);
+    } else {
+      out('The installer never touches package.json, pyproject.toml, README.md or lockfiles.');
+    }
+    return res.conflicts ? 2 : 0;
+  } catch (e) {
+    err(`error: ${/** @type {Error} */ (e).message}`);
+    return 1;
+  }
+}
+

package/src/fsutil.js

@@ -0,0 +1,123 @@
+// Filesystem helpers that keep every write inside the target and never follow symlinks.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { checkRelPath } from './manifest.js';
+
+export class SafetyError extends Error {}
+
+/** Resolve a manifest-relative path inside root, or throw. */
+export function resolveInside(/** @type {string} */ root, /** @type {string} */ rel) {
+  const err = checkRelPath(rel);
+  if (err) throw new SafetyError(`unsafe path "${rel}": ${err}`);
+  const abs = path.resolve(root, ...rel.split('/'));
+  const back = path.relative(root, abs);
+  if (back === '' || back.startsWith('..') || path.isAbsolute(back)) {
+    throw new SafetyError(`path "${rel}" resolves outside ${root}`);
+  }
+  return abs;
+}
+
+function lstatOrNull(/** @type {string} */ p) {
+  try {
+    return fs.lstatSync(p);
+  } catch (e) {
+    if (/** @type {NodeJS.ErrnoException} */ (e).code === 'ENOENT' || /** @type {NodeJS.ErrnoException} */ (e).code === 'ENOTDIR') return null;
+    throw e;
+  }
+}
+
+/**
+ * Throw if any existing component of root/rel (below root) is a symlink or
+ * junction, or if an intermediate component exists and is not a directory.
+ * Returns the lstat of the leaf (or null when it does not exist).
+ */
+export function assertNoSymlinks(/** @type {string} */ root, /** @type {string} */ rel) {
+  resolveInside(root, rel);
+  const parts = rel.split('/');
+  let cur = root;
+  for (let i = 0; i < parts.length; i++) {
+    cur = path.join(cur, parts[i]);
+    const st = lstatOrNull(cur);
+    if (!st) return null;
+    if (st.isSymbolicLink()) {
+      throw new SafetyError(`refusing to follow symlink: ${parts.slice(0, i + 1).join('/')}`);
+    }
+    const isLeaf = i === parts.length - 1;
+    if (!isLeaf && !st.isDirectory()) {
+      throw new SafetyError(`not a directory: ${parts.slice(0, i + 1).join('/')}`);
+    }
+    if (isLeaf) {
+      if (!st.isFile()) throw new SafetyError(`not a regular file: ${rel}`);
+      return st;
+    }
+  }
+  return null;
+}
+
+/** Read root/rel as a Buffer after symlink checks; null if missing. */
+export function readTargetFile(/** @type {string} */ root, /** @type {string} */ rel) {
+  const st = assertNoSymlinks(root, rel);
+  if (!st) return null;
+  return fs.readFileSync(resolveInside(root, rel));
+}
+
+/** Create parent directories one level at a time, refusing symlinks along the way. */
+function mkdirsSafe(/** @type {string} */ root, /** @type {string} */ rel) {
+  const parts = rel.split('/').slice(0, -1);
+  let cur = root;
+  for (let i = 0; i < parts.length; i++) {
+    cur = path.join(cur, parts[i]);
+    const st = lstatOrNull(cur);
+    if (st && st.isSymbolicLink()) {
+      throw new SafetyError(`refusing to follow symlink: ${parts.slice(0, i + 1).join('/')}`);
+    }
+    if (st && !st.isDirectory()) throw new SafetyError(`not a directory: ${parts.slice(0, i + 1).join('/')}`);
+    if (!st) fs.mkdirSync(cur);
+  }
+}
+
+/** Write root/rel (creating parents) after re-checking that nothing on the path is a symlink. */
+export function writeTargetFile(
+  /** @type {string} */ root,
+  /** @type {string} */ rel,
+  /** @type {Buffer} */ data,
+  /** @type {{ mode?: number }} */ { mode } = {},
+) {
+  assertNoSymlinks(root, rel);
+  mkdirsSafe(root, rel);
+  const abs = resolveInside(root, rel);
+  fs.writeFileSync(abs, data);
+  if (mode !== undefined) fs.chmodSync(abs, mode);
+}
+
+/** Text equality that ignores LF vs CRLF differences. */
+export function sameText(/** @type {Buffer} */ a, /** @type {Buffer} */ b) {
+  if (a.equals(b)) return true;
+  const norm = (/** @type {Buffer} */ buf) => buf.toString('utf8').replace(/\r\n/g, '\n');
+  return norm(a) === norm(b);
+}
+
+/**
+ * Recursively list files (relative, forward slashes) under dir. Skips symlinks.
+ * @returns {string[]}
+ */
+export function walkFiles(/** @type {string} */ dir, base = dir, /** @type {Set<string>} */ skip = new Set()) {
+  /** @type {string[]} */
+  let out = [];
+  let entries;
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch (e) {
+    if (/** @type {NodeJS.ErrnoException} */ (e).code === 'ENOENT') return out;
+    throw e;
+  }
+  for (const d of entries) {
+    if (skip.has(d.name)) continue;
+    const abs = path.join(dir, d.name);
+    if (d.isSymbolicLink()) continue;
+    if (d.isDirectory()) out = out.concat(walkFiles(abs, base, skip));
+    else if (d.isFile()) out.push(path.relative(base, abs).split(path.sep).join('/'));
+  }
+  return out.sort();
+}

package/src/install.js

@@ -0,0 +1,223 @@
+// Installer: plan every change in memory first, then (only with apply) write.
+// Any error during planning aborts before a single byte is written.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { loadUnits } from './manifest.js';
+import { applyBlock, assertFragmentClean, renderBlock } from './blocks.js';
+import { assertNoSymlinks, readTargetFile, resolveInside, sameText, writeTargetFile } from './fsutil.js';
+
+export class UsageError extends Error {}
+
+/**
+ * @typedef {import('./manifest.js').Unit} Unit
+ * @typedef {import('./manifest.js').Units} Units
+ * @typedef {{ op: string, path: string, unit: string, detail?: string }} Action
+ * @typedef {{ rel: string, data: Buffer, mode?: number }} Write
+ */
+
+const isHook = (/** @type {string} */ rel) => /^\.husky\/[^/]+$/.test(rel);
+
+/** Pick units in a stable order: core, selected packs, selected presets (kit order). */
+export function selectUnits(
+  /** @type {Units} */ units,
+  /** @type {{ presets?: string[], packs?: string[] }} */ { presets = [], packs = [] } = {},
+) {
+  const check = (/** @type {string[]} */ names, /** @type {Map<string, Unit>} */ map, /** @type {string} */ kind) => {
+    for (const n of names) {
+      if (!map.has(n)) {
+        const valid = [...map.keys()];
+        throw new UsageError(
+          `unknown ${kind} "${n}". Valid ${kind}s: ${valid.length ? valid.join(', ') : '(none)'}`,
+        );
+      }
+    }
+  };
+  check(packs, units.packs, 'pack');
+  check(presets, units.presets, 'preset');
+  const packSet = new Set(packs);
+  const presetSet = new Set(presets);
+  // Expand `implies <pack>` transitively (presets and packs may imply packs).
+  /** @type {{ pack: string, by: string }[]} */
+  const implied = [];
+  // Names were checked above, so every lookup finds its unit.
+  const queue = /** @type {Unit[]} */ ([
+    ...[...presetSet].map((n) => units.presets.get(n)),
+    ...[...packSet].map((n) => units.packs.get(n)),
+  ]);
+  for (let u = queue.shift(); u; u = queue.shift()) {
+    for (const p of u.implies) {
+      if (!units.packs.has(p)) throw new Error(`${u.type} ${u.name} implies unknown pack "${p}"`);
+      if (packSet.has(p)) continue;
+      packSet.add(p);
+      implied.push({ pack: p, by: `${u.type} ${u.name}` });
+      queue.push(/** @type {Unit} */ (units.packs.get(p)));
+    }
+  }
+  return {
+    selected: [
+      units.core,
+      ...[...units.packs.values()].filter((u) => packSet.has(u.name)),
+      ...[...units.presets.values()].filter((u) => presetSet.has(u.name)),
+    ],
+    packs: packSet,
+    implied,
+  };
+}
+
+function readSource(/** @type {Unit} */ unit, /** @type {string} */ rel) {
+  const abs = resolveInside(unit.dir, rel);
+  try {
+    return fs.readFileSync(abs);
+  } catch (e) {
+    if (/** @type {NodeJS.ErrnoException} */ (e).code === 'ENOENT') throw new Error(`${unit.type} ${unit.name}: missing source ${rel}`);
+    throw e;
+  }
+}
+
+/**
+ * Plan (and optionally apply) an install.
+ * Returns { actions: [{ op, path, unit, detail? }], conflicts, notes, nextSteps, applied }.
+ */
+export function install(
+  /** @type {{ kitRoot: string, target: string, presets?: string[], packs?: string[], apply?: boolean, platform?: string }} */
+  { kitRoot, target, presets = [], packs = [], apply = false, platform = process.platform },
+) {
+  const units = loadUnits(kitRoot);
+  const { selected, packs: selectedPacks, implied } = selectUnits(units, { presets, packs });
+
+  /** @type {string} */
+  let root;
+  try {
+    root = fs.realpathSync(target);
+  } catch {
+    throw new UsageError(`target directory does not exist: ${target}`);
+  }
+  if (!fs.statSync(root).isDirectory()) throw new UsageError(`target is not a directory: ${target}`);
+
+  /** @type {Map<string, Buffer>} planned content by destination */
+  const overlay = new Map();
+  /** @type {Write[]} */
+  const writes = [];
+  /** @type {Action[]} */
+  const actions = [];
+  const notes = implied.map(({ pack, by }) => `pack ${pack} added because ${by} implies it`);
+
+  const current = (/** @type {string} */ rel) => {
+    const planned = overlay.get(rel);
+    if (planned !== undefined) return planned;
+    return readTargetFile(root, rel); // also refuses symlinks on the path
+  };
+  const plan = (/** @type {string} */ rel, /** @type {Buffer} */ data, /** @type {{ mode?: number }} */ extra = {}) => {
+    overlay.set(rel, data);
+    const existing = writes.findIndex((w) => w.rel === rel);
+    if (existing >= 0) writes.splice(existing, 1);
+    writes.push({ rel, data, ...extra });
+  };
+  const conflict = (/** @type {Unit} */ unit, /** @type {string} */ rel, /** @type {Buffer} */ data, /** @type {string} */ reason) => {
+    const newRel = `${rel}.new`;
+    assertNoSymlinks(root, newRel);
+    const prev = current(newRel);
+    if (!prev || !prev.equals(data)) plan(newRel, data);
+    actions.push({ op: `conflict -> ${newRel}`, path: rel, unit: unit.name, detail: reason });
+  };
+  // Block conflicts for the same dest are collected, then written as ONE .new
+  // holding every rendered block for that dest (in unit order).
+  /** @type {Map<string, string[]>} rendered blocks by destination */
+  const blockConflicts = new Map();
+  /** @type {Map<string, { unit: string, src: Buffer }>} copy/copy-once entries by destination */
+  const claimed = new Map();
+
+  for (const unit of selected) {
+    for (const e of unit.entries) {
+      if (e.requires && !units.packs.has(e.requires)) {
+        throw new Error(`${unit.name}:${e.line}: requires unknown pack "${e.requires}"`);
+      }
+      if (e.requires && !selectedPacks.has(e.requires)) {
+        actions.push({ op: `skip (needs --pack ${e.requires})`, path: e.dest, unit: unit.name });
+        continue;
+      }
+      assertNoSymlinks(root, e.dest);
+      if (e.kind === 'copy' || e.kind === 'copy-once') {
+        const src = readSource(unit, e.source);
+        const prevClaim = claimed.get(e.dest);
+        if (prevClaim && !prevClaim.src.equals(src)) {
+          throw new UsageError(
+            `${prevClaim.unit} and ${unit.name} both install ${e.dest} with different content. ` +
+              'Install one preset per repository (for monorepos see docs/monorepo.md in the kit).',
+          );
+        }
+        claimed.set(e.dest, { unit: unit.name, src });
+        const have = current(e.dest);
+        const mode = isHook(e.dest) && platform !== 'win32' ? 0o755 : undefined;
+        if (have === null) {
+          plan(e.dest, src, { mode });
+          actions.push({ op: 'create', path: e.dest, unit: unit.name });
+        } else if (e.kind === 'copy-once') {
+          actions.push({ op: 'skip (exists)', path: e.dest, unit: unit.name });
+        } else if (sameText(have, src)) {
+          actions.push({ op: 'unchanged', path: e.dest, unit: unit.name });
+        } else {
+          conflict(unit, e.dest, src, 'existing file differs');
+        }
+        if (isHook(e.dest) && platform === 'win32') {
+          notes.push(`${e.dest}: exec bit not set on Windows; run "git update-index --chmod=+x ${e.dest}" after adding it`);
+        }
+      } else if (e.kind === 'block') {
+        const content = readSource(unit, e.source).toString('utf8');
+        assertFragmentClean(content, `${unit.name}/${e.source}`);
+        const have = current(e.dest);
+        const title = e.dest.endsWith('.md') && e.style === 'html' ? `# ${path.posix.basename(e.dest)}` : null;
+        const res = applyBlock(have === null ? null : have.toString('utf8'), {
+          id: e.id,
+          style: e.style,
+          content,
+          title,
+        });
+        if (res.status === 'conflict') {
+          const newRel = `${e.dest}.new`;
+          assertNoSymlinks(root, newRel);
+          const pending = blockConflicts.get(e.dest) ?? [];
+          blockConflicts.set(e.dest, pending);
+          pending.push(renderBlock(e.id, e.style, content));
+          actions.push({ op: `conflict -> ${newRel}`, path: e.dest, unit: unit.name, detail: `block ${e.id}: ${res.reason}` });
+        } else {
+          if (res.status !== 'block-unchanged') plan(e.dest, Buffer.from(/** @type {string} */ (res.text), 'utf8'));
+          actions.push({ op: res.status, path: e.dest, unit: unit.name, detail: `block ${e.id}` });
+        }
+      }
+    }
+  }
+
+  for (const [dest, rendered] of blockConflicts) {
+    const newRel = `${dest}.new`;
+    const data = Buffer.from(rendered.join('\n\n') + '\n', 'utf8');
+    const prev = current(newRel);
+    if (!prev || !prev.equals(data)) plan(newRel, data);
+  }
+
+  const commands = selected.flatMap((u) => u.runs);
+  /** @type {string[]} */
+  const nextSteps = [];
+  for (const unit of selected.filter((u) => u.type === 'preset')) {
+    const doc = `docs/agent-kit/${unit.name}.md`;
+    if (unit.entries.some((e) => e.dest === doc)) nextSteps.push(doc);
+  }
+
+  if (apply) {
+    for (const w of writes) writeTargetFile(root, w.rel, w.data, { mode: w.mode });
+  }
+
+  const conflicts = actions.filter((a) => a.op.startsWith('conflict')).length;
+  return {
+    root,
+    actions,
+    conflicts,
+    notes: [...new Set(notes)],
+    nextSteps,
+    commands,
+    applied: apply,
+    writes: writes.length,
+    packs: [...selectedPacks],
+  };
+}