@stonepandastudio/cairn 0.4.2 → 0.6.0

package/lib/render/index.js

@@ -0,0 +1,220 @@
+'use strict';
+
+// cairn render — turn the bundled `presets/` into a repo's `ai/` scaffolding.
+//
+// Greenfield only: it writes files that do not exist, records them in the
+// manifest, and leaves anything already on disk alone (reporting it). The
+// three-way merge that would let it re-render over local edits is `cairn sync`,
+// which is not built yet — for a fresh repo there is nothing to merge.
+
+const fs = require('fs');
+const path = require('path');
+
+const { render, stripHeaderComment } = require('./engine');
+const { hashContent } = require('../manifest');
+
+const PRIMARY_ONLY_SLOTS = new Set(['plan-step-ordering', 'architect-references']);
+
+const DEFAULT_WORKFLOW = {
+  steps: [
+    { id: 'brief', fn: 'create_brief', command: 'create-brief', role: 'architect', oneLine: 'creates the task brief scaffold' },
+    { id: 'describe', fn: 'enrich_description', command: 'enrich-description', role: 'architect', oneLine: 'iterative discussion, then writes the enriched description' },
+    { id: 'plan', fn: 'plan_task', command: 'plan-task', role: 'architect', oneLine: 'produces the implementation plan and context-doc updates' },
+    { id: 'execute', fn: 'execute_plan', command: 'execute-plan', role: 'developer', oneLine: 'implements the plan' },
+    { id: 'review', fn: 'code_review', command: 'code-review', role: 'reviewer', oneLine: 'checks the result against the plan and the guidelines' },
+  ],
+};
+
+const ROLE_MODEL = { architect: 'Sonnet', developer: 'Haiku', reviewer: 'Sonnet' };
+
+function cap(s) {
+  return s ? s[0].toUpperCase() + s.slice(1) : s;
+}
+
+function trackerContext(t = {}) {
+  const provider = t.provider || 'none';
+  const remote = provider === 'jira-server' || provider === 'youtrack';
+  return {
+    provider,
+    remote,
+    providerLabel: { 'jira-server': 'Jira', youtrack: 'YouTrack', none: 'no tracker' }[provider] || provider,
+    exampleKey: t.projectKey || (remote ? 'PROJ' : 'TASK'),
+    slug: provider === 'jira-server' ? 'jira' : provider === 'youtrack' ? 'youtrack' : 'tracker',
+    subtaskMarker: provider === 'youtrack' ? 'youtrack-subtask' : 'jira-subtask',
+    reviewStage: (t.statuses && t.statuses.done) || 'Review',
+    parentTerm: remote ? 'parent issue' : 'task',
+    childTerm: remote ? 'child issue' : 'step',
+  };
+}
+
+function loadWorkflow(config, presetsDir) {
+  if (config.workflow && Array.isArray(config.workflow.steps)) return config.workflow;
+  const file = path.join(presetsDir, 'core', 'workflow.json');
+  if (fs.existsSync(file)) {
+    try {
+      return JSON.parse(fs.readFileSync(file, 'utf8'));
+    } catch {
+      /* fall through to the built-in default */
+    }
+  }
+  return DEFAULT_WORKFLOW;
+}
+
+function buildContext(config, presetsDir) {
+  const stack = config.stack && config.stack.length ? config.stack : ['unknown'];
+  const tracker = trackerContext(config.tracker);
+  const workflow = loadWorkflow(config, presetsDir);
+
+  const agents = config.agents || {};
+  const roleName = (role) =>
+    (agents[role] && agents[role].name) || `${cap(stack[0])}${cap(role)}Agent`;
+  const roleDoc = (role) => (agents[role] && agents[role].doc) || `ai/agents/${role}.md`;
+
+  workflow.steps.forEach((s) => {
+    s.agentName = roleName(s.role);
+    s.agentDoc = roleDoc(s.role);
+    s.model = ROLE_MODEL[s.role] || null;
+    s.trackerAction = tracker.remote ? s.trackerAction || 'sync — see the rows below' : 'n/a';
+    s.tracker = tracker.remote && s.role === 'architect' ? true : null;
+  });
+
+  return {
+    stack,
+    tracker,
+    workflow,
+    model: config.model || 'claude-sonnet-5',
+    architectAgent: roleName('architect'),
+    developerAgent: roleName('developer'),
+    reviewerAgent: roleName('reviewer'),
+    project: {
+      assistantName:
+        (config.vars && config.vars.assistantName) || `${cap(stack[0])} Dev Assistant`,
+    },
+    agents: ['architect', 'developer', 'reviewer'].map((r) => ({ name: roleName(r), doc: roleDoc(r) })),
+    ...(config.vars || {}),
+  };
+}
+
+function makeResolvePartial(stack, presetsDir) {
+  return (name) => {
+    const m = name.match(/^stack\/(.+)$/);
+    if (!m) return null;
+    const slot = m[1];
+    const entries = PRIMARY_ONLY_SLOTS.has(slot) ? stack.slice(0, 1) : stack;
+    const parts = [];
+    for (const entry of entries) {
+      const file = path.join(presetsDir, entry, 'slots', `${slot}.md`);
+      if (fs.existsSync(file)) parts.push(stripHeaderComment(fs.readFileSync(file, 'utf8')).trim());
+    }
+    if (!parts.length) return null;
+    // Table-row slots (every part starts with `|`) concatenate line-to-line;
+    // prose slots need a blank line between them.
+    const sep = parts.every((p) => p.startsWith('|')) ? '\n' : '\n\n';
+    return parts.join(sep);
+  };
+}
+
+function readPreset(presetsDir, rel) {
+  const file = path.join(presetsDir, rel);
+  return fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : null;
+}
+
+// Concatenate `<entry>/code-guidelines.md` for every stack entry that ships one.
+function codeGuidelines(stack, presetsDir, ctx, resolvePartial) {
+  const blocks = [];
+  for (const entry of stack) {
+    const raw = readPreset(presetsDir, `${entry}/code-guidelines.md`);
+    if (raw) blocks.push(render(raw, ctx, resolvePartial).trim());
+  }
+  return blocks.length ? blocks.join('\n\n---\n\n') + '\n' : null;
+}
+
+// Every file the presets would produce for this config, as
+// [[rel, content, source, note?]] — before any greenfield or manifest guard.
+// `planRender` filters this for `cairn render`; `cairn sync` diffs each entry
+// against the repo's manifest + `_cairn/base/`.
+function renderTargets({ config, presetsDir }) {
+  const ctx = buildContext(config, presetsDir);
+  const resolvePartial = makeResolvePartial(ctx.stack, presetsDir);
+
+  const targets = [];
+
+  const stub = readPreset(presetsDir, 'core/commands/_stub.md');
+  if (stub) {
+    for (const step of ctx.workflow.steps) {
+      targets.push([
+        `.claude/commands/${step.command}.md`,
+        render(stub, { ...ctx, step }, resolvePartial),
+        'core/commands/_stub.md',
+      ]);
+    }
+  }
+
+  const stepFor = (role) => ctx.workflow.steps.find((s) => s.role === role) || {};
+  for (const role of ['architect', 'developer', 'reviewer']) {
+    const raw = readPreset(presetsDir, `core/agents/${role}.md`);
+    if (raw) {
+      targets.push([
+        `ai/agents/${role}.md`,
+        render(raw, { ...ctx, step: stepFor(role) }, resolvePartial),
+        `core/agents/${role}.md`,
+      ]);
+    }
+  }
+
+  for (const [rel, src] of [
+    ['ai/AGENTS.md', 'core/AGENTS.md'],
+    ['ai/WORKFLOW.md', 'core/WORKFLOW.md'],
+  ]) {
+    const raw = readPreset(presetsDir, src);
+    if (raw) targets.push([rel, render(raw, ctx, resolvePartial), src]);
+  }
+
+  const guidelines = codeGuidelines(ctx.stack, presetsDir, ctx, resolvePartial);
+  if (guidelines) {
+    targets.push([
+      'ai/infrastructure/code-guidelines.md',
+      guidelines,
+      'presets:<stack>/code-guidelines.md',
+      'seed — fork it; `cairn sync` will three-way merge later changes',
+    ]);
+  }
+
+  return { targets, context: ctx };
+}
+
+// Returns { planned: [[rel, content, source, note?]], kept: [{ rel, reason }] }.
+// `manifest` + `repoPath` drive the greenfield guard: a file cairn has not
+// written is never touched, and one it wrote but a human has since edited is
+// kept and reported (the re-render that respects local edits is `cairn sync`).
+function planRender({ config, presetsDir, manifest = { files: {} }, repoPath = null }) {
+  const { targets, context: ctx } = renderTargets({ config, presetsDir });
+
+  const planned = [];
+  const kept = [];
+  for (const [rel, content, source, note] of targets) {
+    const entry = manifest.files[rel];
+    const abs = repoPath ? path.join(repoPath, rel) : null;
+    const onDisk = abs && fs.existsSync(abs) ? fs.readFileSync(abs, 'utf8') : null;
+
+    if (entry && onDisk !== null && hashContent(onDisk) !== entry.hash) {
+      kept.push({ rel, reason: 'hand-edited since cairn wrote it' });
+      continue;
+    }
+    if (entry && onDisk !== null && hashContent(content) === entry.hash) continue; // current, on disk
+    if (entry && onDisk !== null) {
+      kept.push({ rel, reason: 'the template changed — `cairn sync` will merge it' });
+      continue;
+    }
+    if (!entry && onDisk !== null) {
+      kept.push({ rel, reason: 'already on disk, not written by cairn' });
+      continue;
+    }
+    // Not on disk: brand new, or a manifested file that was deleted — (re)write it.
+    planned.push([rel, content, source, entry ? 'restoring' : note]);
+  }
+
+  return { planned, kept, context: ctx };
+}
+
+module.exports = { planRender, renderTargets, buildContext, trackerContext, DEFAULT_WORKFLOW };

package/lib/sync/cli.js

@@ -0,0 +1,197 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const { loadRepoConfig, findRepoRoot, ConfigError } = require('../config');
+const {
+  readManifest,
+  record,
+  writeManifest,
+  writeBase,
+  manifestPath,
+} = require('../manifest');
+const { makePaint } = require('../paint');
+const { planSync, OUTCOME } = require('./index');
+
+const PRESETS_DIR = path.join(__dirname, '..', '..', 'presets');
+
+const HELP = `cairn sync — propagate preset changes into an already-rendered repo
+
+Usage: cairn sync [options]
+
+  --repo <path>    repo to sync (default: the repo cairn.config.json is in)
+  --dry-run        print the 2x2 outcome per file, write nothing
+  --adopt-base     for files rendered before cairn tracked a merge base and
+                   hand-edited since: accept the current file as the base
+                   (you lose the ability to merge upstream changes to it)
+  --no-color       disable ANSI colour
+
+Runs a three-way merge per managed file: base (what the template rendered last
+time, in _cairn/base/), ours (what is on disk), theirs (what the current presets
+render). Clean results are written; a conflict is written with git markers and
+exits non-zero. Nothing is ever silently overwritten.
+`;
+
+const COLOR = {
+  [OUTCOME.UNCHANGED]: 'dim',
+  [OUTCOME.MODIFIED]: 'yellow',
+  [OUTCOME.CREATED]: 'green',
+  [OUTCOME.FAST_FORWARD]: 'green',
+  [OUTCOME.MERGED]: 'green',
+  [OUTCOME.RESTORED]: 'green',
+  [OUTCOME.CONFLICT]: 'red',
+  [OUTCOME.ORPHANED]: 'magenta',
+  [OUTCOME.NO_BASE]: 'red',
+};
+
+function parseArgs(argv) {
+  const args = { repo: null, dryRun: false, adoptBase: false, color: process.stdout.isTTY };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--repo') args.repo = argv[++i];
+    else if (a === '--dry-run') args.dryRun = true;
+    else if (a === '--adopt-base') args.adoptBase = true;
+    else if (a === '--no-color') args.color = false;
+    else if (a === '-h' || a === '--help') args.help = true;
+    else {
+      console.error(`Unknown argument: ${a}`);
+      return { error: 2 };
+    }
+  }
+  return args;
+}
+
+// Apply a plan to disk. Returns the count of files left in conflict.
+function applyPlan(repoPath, manifest, actions, paint) {
+  let conflicts = 0;
+  let changed = false;
+  for (const act of actions) {
+    if (act.write !== undefined) {
+      const abs = path.join(repoPath, act.rel);
+      fs.mkdirSync(path.dirname(abs), { recursive: true });
+      fs.writeFileSync(abs, act.write, 'utf8');
+    }
+    // record() rebuilds the entry, so it drops any stale `conflict` flag; set the
+    // fresh one back afterwards.
+    if (act.write !== undefined && act.source !== undefined) {
+      record(manifest, act.rel, act.source, act.write);
+      changed = true;
+    }
+    if (act.base !== undefined) writeBase(repoPath, act.rel, act.base);
+    if (act.conflict) {
+      manifest.files[act.rel].conflict = true;
+      conflicts++;
+      changed = true;
+    } else if (act.clearConflict && manifest.files[act.rel] && manifest.files[act.rel].conflict) {
+      delete manifest.files[act.rel].conflict;
+      changed = true;
+    }
+    printAction(act, paint);
+  }
+  return { conflicts, changed };
+}
+
+function printAction(act, paint) {
+  const tag = paint[COLOR[act.outcome] || 'dim'](act.outcome.padEnd(12));
+  const detail = act.detail ? paint.dim(`  ${act.detail}`) : '';
+  console.log(`  ${tag}  ${act.rel}${detail}`);
+}
+
+function main(argv = process.argv.slice(2)) {
+  const args = parseArgs(argv);
+  if (args.error) return args.error;
+  if (args.help) {
+    process.stdout.write(HELP);
+    return 0;
+  }
+
+  const paint = makePaint(args.color);
+  const start = args.repo ? path.resolve(args.repo) : process.cwd();
+  const repoPath = args.repo ? start : findRepoRoot(start);
+  if (!repoPath || !fs.existsSync(path.join(repoPath, 'cairn.config.json'))) {
+    console.error('No cairn.config.json found — run `cairn init` first');
+    return 2;
+  }
+
+  const manifest = readManifest(repoPath);
+  if (!manifest || !Object.keys(manifest.files).length) {
+    console.error('Nothing to sync — this repo has no cairn manifest. Run `cairn render` first.');
+    return 2;
+  }
+
+  let plan;
+  try {
+    const config = loadRepoConfig(repoPath, { required: true });
+    plan = planSync({ config, presetsDir: PRESETS_DIR, manifest, repoPath, adoptBase: args.adoptBase });
+  } catch (e) {
+    if (e instanceof ConfigError) {
+      console.error(e.message);
+      return 2;
+    }
+    throw e;
+  }
+
+  if (args.dryRun) {
+    console.log(paint.bold(`cairn sync --dry-run  ${repoPath}`));
+    for (const act of plan.actions) printAction(act, paint);
+    const conflicts = plan.actions.filter((a) => a.outcome === OUTCOME.CONFLICT).length;
+    const noBase = plan.actions.filter((a) => a.outcome === OUTCOME.NO_BASE).length;
+    console.log('');
+    console.log(summary(plan.actions, paint));
+    return conflicts || noBase ? 3 : 0;
+  }
+
+  console.log(paint.bold(`cairn sync  ${repoPath}`));
+  const { conflicts, changed } = applyPlan(repoPath, manifest, plan.actions, paint);
+  const noBase = plan.actions.filter((a) => a.outcome === OUTCOME.NO_BASE).length;
+
+  if (changed) {
+    writeManifest(repoPath, manifest);
+    console.log(
+      `  ${paint.green('wrote')}  ${path
+        .relative(repoPath, manifestPath(repoPath))
+        .replace(/\\/g, '/')}`,
+    );
+  }
+
+  console.log('');
+  console.log(summary(plan.actions, paint));
+
+  if (conflicts) {
+    console.log('');
+    console.log(
+      paint.red(`  ${conflicts} file(s) left with conflict markers`) +
+        paint.dim(' — resolve them, then run `cairn sync` again'),
+    );
+  }
+  if (noBase) {
+    console.log(
+      paint.red(`  ${noBase} file(s) have no merge base`) +
+        paint.dim(' — re-run with --adopt-base once you have reviewed them'),
+    );
+  }
+  return conflicts || noBase ? 3 : 0;
+}
+
+function summary(actions, paint) {
+  const counts = {};
+  for (const a of actions) counts[a.outcome] = (counts[a.outcome] || 0) + 1;
+  const order = [
+    OUTCOME.CREATED,
+    OUTCOME.FAST_FORWARD,
+    OUTCOME.MERGED,
+    OUTCOME.RESTORED,
+    OUTCOME.MODIFIED,
+    OUTCOME.UNCHANGED,
+    OUTCOME.ORPHANED,
+    OUTCOME.NO_BASE,
+    OUTCOME.CONFLICT,
+  ];
+  const parts = order
+    .filter((k) => counts[k])
+    .map((k) => paint[COLOR[k] || 'dim'](`${k} ${counts[k]}`));
+  return paint.bold('Summary') + '\n  ' + (parts.join('   ') || paint.dim('nothing managed'));
+}
+
+module.exports = { main, applyPlan, HELP, PRESETS_DIR };

package/lib/sync/index.js

@@ -0,0 +1,249 @@
+'use strict';
+
+// cairn sync — propagate preset changes into a repo that has already rendered.
+//
+// `cairn render` is greenfield: it writes files that do not exist and never
+// touches one again. `cairn sync` is the upgrade path. For every managed file it
+// holds three versions —
+//
+//   base    what the template rendered last time      (_cairn/base/<rel>)
+//   ours    what is on disk now                        (the repo's edits)
+//   theirs  what the current presets render
+//
+// — and runs a 2x2:
+//
+//                  template unchanged     template changed
+//   local unchanged   no-op                fast-forward (write theirs)
+//   local changed     keep local (MODIFIED)  three-way merge
+//
+// Three cells are automatic. The bottom-right shells out to `git merge-file`;
+// a clean merge is applied, a conflicted one is written with markers and stops
+// the command with a non-zero exit. Nothing is ever silently overwritten.
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+const { hashContent, readBase } = require('../manifest');
+const render = require('../render');
+
+const SHIM_SOURCE = 'shims/jira.js';
+
+// Outcomes, most-benign first. CONFLICT and NO_BASE are the non-zero exits.
+const OUTCOME = {
+  UNCHANGED: 'unchanged',
+  MODIFIED: 'modified',
+  CREATED: 'created',
+  FAST_FORWARD: 'fast-forward',
+  MERGED: 'merged',
+  RESTORED: 'restored',
+  CONFLICT: 'CONFLICT',
+  ORPHANED: 'orphaned',
+  NO_BASE: 'no base',
+};
+
+function templatesDir() {
+  return path.join(__dirname, '..', '..', 'templates');
+}
+
+// `theirs` for a manifest entry: the preset-rendered file when the presets still
+// emit that path, the vendored template for a tracker shim, or null when neither
+// applies any more (the stack changed and this preset dropped out).
+function resolveTheirs(entry, rel, targetsByRel) {
+  const hit = targetsByRel.get(rel);
+  if (hit) return { content: hit.content, source: hit.source };
+  if (entry.source === SHIM_SOURCE) {
+    const file = path.join(templatesDir(), SHIM_SOURCE);
+    if (fs.existsSync(file)) return { content: fs.readFileSync(file, 'utf8'), source: SHIM_SOURCE };
+  }
+  return null;
+}
+
+// git merge-file --diff3, ours/base/theirs on disk, merged text on stdout. Exit
+// code is the conflict count (0 = clean); a negative code means git failed.
+function gitMergeFile(ours, base, theirs) {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'cairn-merge-'));
+  const write = (name, body) => {
+    const p = path.join(dir, name);
+    fs.writeFileSync(p, body, 'utf8');
+    return p;
+  };
+  try {
+    const res = spawnSync(
+      'git',
+      [
+        'merge-file',
+        '-p',
+        '--diff3',
+        '-L',
+        'ours (your edits)',
+        '-L',
+        'base (cairn wrote this)',
+        '-L',
+        'theirs (new template)',
+        write('ours', ours),
+        write('base', base),
+        write('theirs', theirs),
+      ],
+      { encoding: 'utf8' },
+    );
+    if (res.error && res.error.code === 'ENOENT') {
+      return { ok: false, reason: 'git is not on PATH — cairn sync needs it for the merge step' };
+    }
+    if (typeof res.status !== 'number' || res.status < 0) {
+      return { ok: false, reason: (res.stderr || 'git merge-file failed').trim() };
+    }
+    return { ok: true, merged: res.stdout, conflicts: res.status };
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+// One decision per managed file. Returns an action describing what the caller
+// should write; it performs no IO of its own beyond reading ours/base.
+function planFile(rel, entry, repoPath, targetsByRel, { adoptBase }) {
+  const theirs = resolveTheirs(entry, rel, targetsByRel);
+  const absOurs = path.join(repoPath, rel);
+  const ours = fs.existsSync(absOurs) ? fs.readFileSync(absOurs, 'utf8') : null;
+
+  if (!theirs) {
+    return { rel, outcome: OUTCOME.ORPHANED, detail: 'the presets no longer emit this path' };
+  }
+
+  if (ours === null) {
+    // Deleted locally — nothing to preserve, put the current render back.
+    return {
+      rel,
+      outcome: OUTCOME.RESTORED,
+      detail: 'was deleted',
+      write: theirs.content,
+      base: theirs.content,
+      source: theirs.source,
+    };
+  }
+
+  let base = readBase(repoPath, rel);
+  let seededBase = false;
+  if (base === null) {
+    if (hashContent(ours) === entry.hash) {
+      // Untouched since cairn wrote it — the on-disk bytes are a faithful base.
+      base = ours;
+      seededBase = true;
+    } else if (adoptBase) {
+      base = ours;
+      seededBase = true;
+    } else {
+      return {
+        rel,
+        outcome: OUTCOME.NO_BASE,
+        detail: 'rendered before base tracking and edited since — pass --adopt-base or reconcile by hand',
+      };
+    }
+  }
+
+  const hOurs = hashContent(ours);
+  const hBase = hashContent(base);
+  const hTheirs = hashContent(theirs.content);
+  const localChanged = hOurs !== hBase;
+  const templateChanged = hTheirs !== hBase;
+  const hasMarkers = /^<{7} /m.test(ours) && /^>{7} /m.test(ours);
+
+  if (!templateChanged) {
+    // The template has already been folded into the base — anything left is a
+    // local edit. Clear a stale conflict flag once the markers are gone.
+    const unresolved = entry.conflict && hasMarkers;
+    return {
+      rel,
+      outcome: localChanged ? OUTCOME.MODIFIED : OUTCOME.UNCHANGED,
+      detail: unresolved
+        ? 'conflict markers still in the file — resolve them'
+        : localChanged
+          ? 'local edits, template steady — kept'
+          : null,
+      // Persist a base we only inferred this run, so the next sync is cheap.
+      base: seededBase ? base : undefined,
+      clearConflict: entry.conflict && !unresolved,
+    };
+  }
+
+  if (!localChanged) {
+    return {
+      rel,
+      outcome: OUTCOME.FAST_FORWARD,
+      detail: `template moved ${diffMagnitude(base, theirs.content)}`,
+      write: theirs.content,
+      base: theirs.content,
+      source: theirs.source,
+      clearConflict: true,
+    };
+  }
+
+  const merge = gitMergeFile(ours, base, theirs.content);
+  if (!merge.ok) {
+    return { rel, outcome: OUTCOME.CONFLICT, detail: merge.reason };
+  }
+  if (merge.conflicts === 0) {
+    return {
+      rel,
+      outcome: OUTCOME.MERGED,
+      detail: 'local edits + template changes combined cleanly',
+      write: merge.merged,
+      base: theirs.content,
+      source: theirs.source,
+      clearConflict: true,
+    };
+  }
+  // Write the markers, and advance the base to `theirs` so the next run treats
+  // whatever the human leaves behind as a plain local edit rather than merging
+  // the same template change a second time.
+  return {
+    rel,
+    outcome: OUTCOME.CONFLICT,
+    detail: `${merge.conflicts} conflict${merge.conflicts === 1 ? '' : 's'} — markers written, resolve then re-run`,
+    write: merge.merged,
+    base: theirs.content,
+    source: theirs.source,
+    conflict: true,
+  };
+}
+
+function diffMagnitude(a, b) {
+  const la = a.split('\n').length;
+  const lb = b.split('\n').length;
+  const d = lb - la;
+  if (d === 0) return '(same length)';
+  return d > 0 ? `(+${d} lines)` : `(${d} lines)`;
+}
+
+// Plan a sync for the whole repo. Pure except for reading ours/base and invoking
+// `git merge-file`; the caller writes the files and the manifest.
+function planSync({ config, presetsDir, manifest, repoPath, adoptBase = false }) {
+  const { targets } = render.renderTargets({ config, presetsDir });
+  const targetsByRel = new Map(targets.map(([rel, content, source]) => [rel, { content, source }]));
+
+  const actions = [];
+  for (const [rel, entry] of Object.entries(manifest.files)) {
+    actions.push(planFile(rel, entry, repoPath, targetsByRel, { adoptBase }));
+  }
+
+  // Brand-new preset files: a manifested repo that predates a preset addition.
+  // Same greenfield guard as `cairn render` — write it only if nothing is there.
+  for (const [rel, content, source] of targets) {
+    if (manifest.files[rel]) continue;
+    if (fs.existsSync(path.join(repoPath, rel))) continue;
+    actions.push({
+      rel,
+      outcome: OUTCOME.CREATED,
+      detail: 'new preset file',
+      write: content,
+      base: content,
+      source,
+    });
+  }
+
+  actions.sort((a, b) => a.rel.localeCompare(b.rel));
+  return { actions };
+}
+
+module.exports = { planSync, planFile, gitMergeFile, OUTCOME };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stonepandastudio/cairn",
-  "version": "0.4.2",
+  "version": "0.6.0",
   "description": "Shared AI workflow scaffolding for Stone Panda repos — issue tracker client and drift doctor.",
   "license": "UNLICENSED",
   "repository": {
@@ -24,6 +24,7 @@
     "bin/",
     "lib/",
     "templates/",
+    "presets/",
     "schema.json",
     "README.md"
   ],