@stonepandastudio/cairn 0.4.2 → 0.6.0

package/README.md

@@ -3,8 +3,9 @@
 Shared AI workflow scaffolding, kept in sync across several repos.
 
 Each repo carries an `ai/` folder and a `.claude/commands/` folder holding the same
-workflow — brief → description → plan → execute → review → QA, with the steps
-mirrored into an issue tracker. Copied between repos by hand, they drift.
+workflow — brief → description → plan → execute → review, with the steps optionally
+mirrored into an issue tracker. Hand-copied between repos, they drift. cairn renders
+them from one set of presets and reports where existing copies disagree.
 
 A cairn is a stack of stones left to mark a trail. That is what this does: it leaves
 markers — a manifest of what it generated, and a report of where the copies stopped
@@ -15,33 +16,63 @@ npm i -D @stonepandastudio/cairn
 npx cairn init --stack nestjs,typeorm --tracker jira-server --project-key MYPROJ --story-type Task
 ```
 
-## What v1 does
+## What it does
 
 | Command | |
 |---|---|
 | `cairn tracker <cmd>` | Issue tracker client (`jira-server` / `youtrack` / `none`). Replaces the copied `ai/scripts/*.js` clients |
 | `cairn doctor` | Cross-repo drift report, plus per-repo generated-file state |
 | `cairn init` | Makes a repo cairn-managed: writes `cairn.config.json`, `_cairn/`, and the shim |
+| `cairn render` | Scaffolds `ai/` + `.claude/commands/` from the bundled presets, from the repo's stack + workflow |
+| `cairn sync` | Re-renders and three-way merges preset changes into a repo that has already rendered |
 
-Template rendering — generating the command stubs, `WORKFLOW.md` and the agent role
-contracts from one workflow declaration — is v2, and deliberately not in this release.
-v1 swaps the tracker client under the consuming repos; bundling prompt changes into
-the same release would make any regression impossible to attribute.
+`cairn render` is **greenfield only**: it writes files that do not exist, records them
+in the manifest, stores the render in `_cairn/base/`, and leaves anything already on
+disk alone (reporting it).
+
+`cairn sync` is the upgrade path. For each managed file it holds three versions —
+`base` (the last render, in `_cairn/base/`), `ours` (what is on disk), `theirs` (what
+the current presets render) — and runs a 2×2:
+
+| | template unchanged | template changed |
+|---|---|---|
+| **local unchanged** | no-op | fast-forward — write the new render |
+| **local changed** | keep local (`MODIFIED`) | three-way merge |
+
+Three cells are automatic. The merge shells out to `git merge-file`; a clean result
+is written, a conflicted one is written **with markers** and the command exits
+non-zero (`CONFLICT`, a fifth manifest state). Nothing is ever silently overwritten.
+Resolve the markers and run `cairn sync` again — the base has already advanced, so
+the second run is a quiet `MODIFIED`.
+
+```bash
+cairn sync --dry-run          # show the outcome per file, write nothing
+cairn sync                    # apply; exit 3 if any file is left in conflict
+cairn sync --adopt-base       # for files rendered before _cairn/base/ existed
+```
 
 ## The two folders
 
 ```
 repo/
-  cairn.config.json      you edit this. cairn only ever reads it.
-  _cairn/                cairn writes this. nobody hand-edits it.
-    manifest.json        what was generated, from which template, at which hash
-    scripts/jira.js      vendored shim
-  ai/                    project-owned. cairn never touches it.
-    contexts/  progress/  tasks/  infrastructure/
+  cairn.config.json     you edit this. cairn only ever reads it.
+  _cairn/               cairn writes this. nobody hand-edits it.
+    manifest.json       what was generated, from which template, at which hash
+    base/               the last render of every managed file — `cairn sync`'s merge base
+    scripts/jira.js     vendored tracker shim
+  .claude/commands/     rendered from the workflow — one stub per step
+  ai/
+    agents/             rendered from presets/core + your stack's slots
+    AGENTS.md  WORKFLOW.md   rendered
+    infrastructure/code-guidelines.md   rendered once as a seed — then it is yours
+    contexts/  tasks/   yours, never written by cairn
 ```
 
-The boundary is the whole design. Hand-edited config living inside a generated
-directory is how generated directories acquire state nobody dares regenerate.
+`cairn render` seeds the rendered files once and records them in the manifest; it
+never rewrites a file you have edited. `cairn sync` is what re-renders later preset
+changes over your edits, three-way merging where both moved. The boundary is the
+whole design: hand-edited config living inside a generated directory is how
+generated directories acquire state nobody dares regenerate.
 
 Generated files are **committed**, not gitignored. Claude Code discovers
 `.claude/commands/` and agent docs from disk, and a prompt change should show up in
@@ -88,7 +119,7 @@ environment wins over the file. If the repo's own app reads those same names, se
 `create-task`, `create-story`, `close-story` and friends are all still accepted, and
 output formats are byte-for-byte what the old scripts printed. Existing prose
 references name these strings and the agents parse the output, so they are kept
-until the v2 pass regenerates those documents.
+until a render pass regenerates those documents from the presets.
 
 ## Doctor
 
@@ -124,11 +155,13 @@ match what is on disk?
 |---|---|
 | `MANAGED` | on-disk hash matches what cairn wrote |
 | `MODIFIED` | someone hand-edited a generated file |
-| `OUTDATED` | cairn has newer content for it — needs template hashes, wired in v2 |
-| `DELETED` | it is gone; a future `cairn sync` will restore it |
+| `OUTDATED` | cairn has newer content for it — needs template hashes threaded through |
+| `DELETED` | it is gone; `cairn sync` restores it from the current render |
+| `CONFLICT` | `cairn sync` left git merge markers in it — resolve, then sync again |
 
-v1 reports `MANAGED`, `MODIFIED` and `DELETED`. `OUTDATED` and the `sync` that acts
-on these states arrive with the v2 renderer.
+Today the doctor reports `MANAGED`, `MODIFIED`, `DELETED` and `CONFLICT`. `OUTDATED`
+(needs the template hashes threaded through) is still to come. Acting on drift
+between the render and the working tree is `cairn sync`.
 
 A file can be perfectly in sync across repos while being hand-edited away from its
 template, and vice versa. `MODIFIED` outranks `OUTDATED` in the report because
@@ -152,8 +185,8 @@ overwriting a hand edit is the destructive outcome.
   `ai/INITIAL_PROMPT.md` is explicitly excluded: variants at ~0% shared content make
   it a per-project document, not a drifted template.
 
-v2 splits this flat file into a per-project `workspace.json` plus an opt-in hub that
-references the projects for cross-project comparison. See `DESIGN.md`.
+A later release splits this flat file into a per-project `workspace.json` plus an
+opt-in hub that references the projects for cross-project comparison. See `DESIGN.md`.
 
 ## Layout
 
@@ -164,10 +197,14 @@ lib/manifest.js        generated-file hashing and state
 lib/paint.js           ANSI + table rendering
 lib/tracker/           index (registry), cli, jira-server, youtrack, none
 lib/doctor/            index (analysis + report), scan, normalize, diff
+lib/render/            engine (a small template engine), index (driver), cli
+lib/sync/              index (the 2x2 + git merge-file), cli
 lib/init.js            cairn init
 templates/shims/       vendored shim source
+presets/               core/ + framework/ORM/styling presets rendered by `cairn render`
 schema.json            JSON Schema for cairn.config.json
 test/run.js            dependency-free test runner
 ```
 
-No runtime dependencies. Node >= 18. `npm test` runs 56 tests.
+No runtime dependencies (`cairn sync` shells out to `git`). Node >= 18. `npm test`
+runs 74 tests.

package/bin/cairn.js

@@ -3,14 +3,12 @@
 
 // cairn — shared AI workflow scaffolding for Stone Panda repos.
 //
-// v1 surface:
+// Surface:
 //   cairn tracker <cmd>   issue tracker client (replaces the copied ai/scripts/jira.js)
 //   cairn doctor          cross-repo drift report
 //   cairn init            make a repo cairn-managed
-//
-// Template rendering (command stubs, WORKFLOW.md, agent role contracts) is v2 and
-// deliberately absent: this release swaps the Jira client under five repos, and
-// mixing that with prompt changes would make any regression unattributable.
+//   cairn render          scaffold ai/ from the bundled presets (greenfield)
+//   cairn sync            three-way merge of preset changes into a rendered repo
 
 const HELP = `cairn — shared AI workflow scaffolding
 
@@ -19,6 +17,8 @@ Usage: cairn <command> [options]
   tracker <cmd> [...]   issue tracker client   (cairn tracker --help)
   doctor [options]      cross-repo drift report (cairn doctor --help)
   init [options]        make a repo cairn-managed (cairn init --help)
+  render [options]      scaffold ai/ from the bundled presets (cairn render --help)
+  sync [options]        merge preset changes into an already-rendered repo (cairn sync --help)
   version               print version
 
 Run \`cairn <command> --help\` for command options.
@@ -40,6 +40,14 @@ function main() {
       process.exitCode = require('../lib/init').main(rest);
       return;
 
+    case 'render':
+      process.exitCode = require('../lib/render/cli').main(rest);
+      return;
+
+    case 'sync':
+      process.exitCode = require('../lib/sync/cli').main(rest);
+      return;
+
     case 'version':
     case '--version':
     case '-v':

package/lib/doctor/index.js

@@ -40,6 +40,7 @@ const MANAGED_COLOR = {
   OUTDATED: 'yellow',
   MODIFIED: 'red',
   DELETED: 'magenta',
+  CONFLICT: 'red',
 };
 
 // ------------------------------------------------------------------ workspace
@@ -510,7 +511,11 @@ function main(argv = process.argv.slice(2)) {
       .flatMap((s) => s.files)
       .some((f) => f.status === 'DRIFT' || f.status === 'MISSING' || f.status === 'STRANDED');
     const broken = managed.some(
-      (m) => m.error || m.files.some((f) => f.state === 'MODIFIED' || f.state === 'DELETED'),
+      (m) =>
+        m.error ||
+        m.files.some(
+          (f) => f.state === 'MODIFIED' || f.state === 'DELETED' || f.state === 'CONFLICT',
+        ),
     );
     if (drifted || broken) return 1;
   }

package/lib/init.js

@@ -9,6 +9,7 @@ const {
   readManifest,
   record,
   writeManifest,
+  writeBase,
   manifestPath,
   hashContent,
 } = require('./manifest');
@@ -58,6 +59,7 @@ Usage: cairn init [options]
                            (only when the repo's app reads JIRA_*/YOUTRACK_* itself)
   --no-shim                do not vendor or replace the ai/scripts/*.js client shims
   --force                  overwrite an existing cairn.config.json
+  --render                 also scaffold ai/ from the presets after init
   --force-shims            also replace an ai/scripts/*.js shim that was hand-edited
                            since cairn wrote it (kept untouched otherwise)
   --dry-run                print what would be written, write nothing
@@ -75,6 +77,7 @@ function parseArgs(argv) {
     shim: true,
     force: false,
     forceShims: false,
+    render: false,
     dryRun: false,
     color: process.stdout.isTTY,
   };
@@ -90,6 +93,7 @@ function parseArgs(argv) {
     else if (a === '--no-shim') args.shim = false;
     else if (a === '--force') args.force = true;
     else if (a === '--force-shims') args.forceShims = args.force = true;
+    else if (a === '--render') args.render = true;
     else if (a === '--dry-run') args.dryRun = true;
     else if (a === '--no-color') args.color = false;
     else if (a === '-h' || a === '--help') args.help = true;
@@ -207,7 +211,10 @@ function main(argv = process.argv.slice(2)) {
     fs.writeFileSync(abs, content, 'utf8');
     // cairn.config.json is hand-editable, so it is deliberately not manifested —
     // tracking it would report every legitimate edit as MODIFIED.
-    if (source) record(manifest, rel, source, content);
+    if (source) {
+      record(manifest, rel, source, content);
+      writeBase(repoPath, rel, content);
+    }
   }
   writeManifest(repoPath, manifest);
 
@@ -233,6 +240,13 @@ function main(argv = process.argv.slice(2)) {
     console.log(paint.dim(`\n  Next: ensure .env has ${envVars.join(', ')}, then run`));
     console.log(paint.dim(`        npx cairn tracker list-statuses ${args.projectKey}`));
   }
+
+  if (args.render) {
+    console.log('');
+    require('./render/cli').renderInto(repoPath, { paint });
+  } else {
+    console.log(paint.dim(`\n  Next: \`cairn render\` to scaffold ai/ from the presets`));
+  }
   return 0;
 }
 

package/lib/manifest.js

@@ -21,11 +21,37 @@ const GENERATOR = require('../package.json').name;
 //   MODIFIED  on-disk hash !== written hash            someone edited it by hand
 //   OUTDATED  written hash !== current template hash   cairn has newer content
 //   DELETED   file is gone                             sync will restore it
+//   CONFLICT  entry.conflict is set                    `cairn sync` left merge markers
+//
+// `_cairn/base/<relPath>` holds the bytes of the last clean template render for
+// each managed file — the merge base `cairn sync` diffs against. The manifest
+// hash is "what is on disk after the last cairn write"; the base file is "what
+// the template produced". They diverge once a merge folds local edits back in.
 
 function manifestPath(repoPath) {
   return path.join(cairnDir(repoPath), MANIFEST_NAME);
 }
 
+const BASE_DIR = 'base';
+
+function basePath(repoPath, relPath) {
+  return path.join(cairnDir(repoPath), BASE_DIR, relPath.replace(/\\/g, '/'));
+}
+
+// The last clean template render for `relPath`. `cairn render` and `cairn init`
+// write it alongside the real file; `cairn sync` reads it as the merge base and
+// rewrites it on every fast-forward or clean merge.
+function readBase(repoPath, relPath) {
+  const file = basePath(repoPath, relPath);
+  return fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : null;
+}
+
+function writeBase(repoPath, relPath, content) {
+  const file = basePath(repoPath, relPath);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, content, 'utf8');
+}
+
 // Normalize before hashing so a CRLF checkout doesn't read as a hand edit. This
 // matters here specifically: these repos are Windows-side with mixed .gitattributes.
 function hashContent(text) {
@@ -83,6 +109,10 @@ function statusFor(repoPath, manifest, templateHashes = null) {
       continue;
     }
     const onDisk = hashContent(fs.readFileSync(abs, 'utf8'));
+    if (entry.conflict) {
+      results.push({ path: rel, source: entry.source, state: 'CONFLICT' });
+      continue;
+    }
     if (onDisk !== entry.hash) {
       results.push({ path: rel, source: entry.source, state: 'MODIFIED' });
       continue;
@@ -109,12 +139,15 @@ module.exports = {
   CAIRN_DIR,
   MANIFEST_NAME,
   MANIFEST_VERSION,
+  basePath,
   emptyManifest,
   hashContent,
   header,
   manifestPath,
+  readBase,
   readManifest,
   record,
   statusFor,
+  writeBase,
   writeManifest,
 };

package/lib/render/cli.js

@@ -0,0 +1,116 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const { loadRepoConfig, findRepoRoot, ConfigError } = require('../config');
+const {
+  readManifest,
+  emptyManifest,
+  record,
+  writeManifest,
+  writeBase,
+  manifestPath,
+} = require('../manifest');
+const { makePaint } = require('../paint');
+const { planRender } = require('./index');
+
+const PRESETS_DIR = path.join(__dirname, '..', '..', 'presets');
+
+const HELP = `cairn render — scaffold a repo's ai/ from the bundled presets
+
+Usage: cairn render [options]
+
+  --repo <path>    repo to render into (default: the repo cairn.config.json is in)
+  --dry-run        print what would be written, write nothing
+  --no-color       disable ANSI colour
+
+Reads the repo's cairn.config.json (run \`cairn init\` first) — the stack list,
+tracker, and any agent overrides. Greenfield only: it writes files that do not
+exist and records them in the manifest; anything already on disk is left alone.
+`;
+
+function parseArgs(argv) {
+  const args = { repo: null, dryRun: 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 === '--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;
+}
+
+// Shared by `cairn render` and `cairn init --render`.
+function renderInto(repoPath, { dryRun = false, paint } = {}) {
+  const config = loadRepoConfig(repoPath, { required: true });
+  const manifest = readManifest(repoPath) || emptyManifest();
+  paint = paint || makePaint(false);
+
+  const { planned, kept } = planRender({ config, presetsDir: PRESETS_DIR, manifest, repoPath });
+
+  if (dryRun) {
+    console.log(paint.bold(`cairn render --dry-run  ${repoPath}`));
+    for (const [rel, , , note] of planned) {
+      console.log(`  ${paint.green('would write')}  ${rel}${note ? paint.dim(`  (${note})`) : ''}`);
+    }
+    for (const k of kept) console.log(paint.yellow(`  would keep    ${k.rel}  (${k.reason})`));
+    if (!planned.length && !kept.length) console.log(paint.dim('  nothing to render'));
+    return 0;
+  }
+
+  let wrote = 0;
+  for (const [rel, content, source] of planned) {
+    const abs = path.join(repoPath, rel);
+    fs.mkdirSync(path.dirname(abs), { recursive: true });
+    fs.writeFileSync(abs, content, 'utf8');
+    record(manifest, rel, source, content);
+    // The merge base `cairn sync` will diff against: what the template produced,
+    // verbatim, this run.
+    writeBase(repoPath, rel, content);
+    console.log(`  ${paint.green('wrote')}  ${rel}`);
+    wrote++;
+  }
+  if (wrote) {
+    writeManifest(repoPath, manifest);
+    console.log(`  ${paint.green('wrote')}  ${path.relative(repoPath, manifestPath(repoPath)).replace(/\\/g, '/')}`);
+  }
+  for (const k of kept) console.log(paint.yellow(`  kept   ${k.rel}  (${k.reason})`));
+  if (!wrote && !kept.length) console.log(paint.dim('  nothing to render — all current'));
+  return 0;
+}
+
+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 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 paint = makePaint(args.color);
+  try {
+    if (!args.dryRun) console.log(paint.bold(`cairn render  ${repoPath}`));
+    return renderInto(repoPath, { dryRun: args.dryRun, paint });
+  } catch (e) {
+    if (e instanceof ConfigError) {
+      console.error(e.message);
+      return 2;
+    }
+    throw e;
+  }
+}
+
+module.exports = { main, renderInto, HELP, PRESETS_DIR };

package/lib/render/engine.js

@@ -0,0 +1,148 @@
+'use strict';
+
+// A very small template engine — the subset of Handlebars the preset files use
+// and nothing more. Pure: no fs, no cairn knowledge. The driver in ./index.js
+// supplies the context and the `{{> stack/… }}` partial resolver.
+//
+// Supported:
+//   {{ path }}            substitution, not HTML-escaped (output is markdown)
+//   {{ this.x }}          `this` and dotted paths, plus @index / @index_1 / @first / @last inside #each
+//   {{#if path}}…{{/if}}  with optional {{else}}
+//   {{#each path}}…{{/each}}
+//   {{> stack/name }}     resolved by the caller-supplied resolvePartial(name, ctx)
+//   {{! comment }}        dropped
+//   a leading <!-- cairn preset: … --> or <!-- cairn:… --> block is dropped
+
+const TOKEN = /(\{\{!(?:(?!\}\})[\s\S])*\}\}|\{\{\{[^}]*\}\}\}|\{\{[#/>]?\s*[^}]*?\}\})/;
+
+// Drop cairn's own editorial comments — `<!-- cairn preset: … -->` /
+// `{{! … }}` — wherever they sit in a template. They document the preset for a
+// human reading `presets/` and must not reach the rendered output. Then tidy the
+// whitespace a block tag on its own line would otherwise leave behind (Mustache's
+// "standalone" rule), and collapse the runs of blank lines that removing a
+// comment block opens up.
+function stripHeaderComment(src) {
+  return String(src)
+    .replace(/^/, '')
+    .replace(/[ \t]*<!--\s*cairn[:\s][\s\S]*?-->[ \t]*\n?/g, '')
+    .replace(/^[ \t]*\{\{!(?:(?!\}\})[\s\S])*\}\}[ \t]*\r?\n/gm, '')
+    .replace(/\{\{!(?:(?!\}\})[\s\S])*\}\}/g, '')
+    .replace(/^[ \t]*(\{\{[#/][^}]*\}\}|\{\{\s*else\s*\}\})[ \t]*\r?\n/gm, '$1')
+    .replace(/\n{3,}/g, '\n\n')
+    .replace(/^\n+/, '');
+}
+
+function tokenize(src) {
+  return src
+    .split(TOKEN)
+    .filter((s) => s !== '' && s !== undefined)
+    .map((s) => {
+      const m = s.match(/^\{\{([#/>!]?)\s*([\s\S]*?)\s*\}\}$/);
+      if (!m) return { t: 'text', v: s };
+      const [, sigil, body] = m;
+      if (sigil === '!') return { t: 'comment' };
+      if (sigil === '>') return { t: 'partial', v: body.trim() };
+      if (sigil === '#') {
+        const [kw, arg] = body.split(/\s+/, 2);
+        return { t: 'open', kw, arg };
+      }
+      if (sigil === '/') return { t: 'close', kw: body.trim() };
+      if (body === 'else') return { t: 'else' };
+      return { t: 'var', v: body.trim() };
+    });
+}
+
+// Build a nested node tree from the flat token list.
+function parse(tokens) {
+  const root = { kw: 'root', body: [], else: null };
+  const stack = [root];
+  let target = 'body';
+
+  for (const tok of tokens) {
+    const top = stack[stack.length - 1];
+    const sink = target === 'else' ? top.else : top.body;
+
+    if (tok.t === 'comment') continue;
+    if (tok.t === 'text') sink.push({ t: 'text', v: tok.v });
+    else if (tok.t === 'var') sink.push({ t: 'var', v: tok.v });
+    else if (tok.t === 'partial') sink.push({ t: 'partial', v: tok.v });
+    else if (tok.t === 'open') {
+      const node = { t: 'block', kw: tok.kw, arg: tok.arg, body: [], else: [] };
+      sink.push(node);
+      stack.push(node);
+      target = 'body';
+    } else if (tok.t === 'else') {
+      target = 'else';
+    } else if (tok.t === 'close') {
+      if (stack.length < 2 || top.kw !== tok.kw) {
+        throw new Error(`template: unbalanced {{/${tok.kw}}}`);
+      }
+      stack.pop();
+      target = 'body';
+    }
+  }
+  if (stack.length !== 1) throw new Error(`template: unclosed {{#${stack[stack.length - 1].kw}}}`);
+  return root.body;
+}
+
+function lookup(ctx, path) {
+  if (path === 'this') return ctx.this;
+  if (path.startsWith('@')) return ctx['@'] ? ctx['@'][path] : undefined;
+  let cur = path.startsWith('this.') ? ctx.this : ctx;
+  for (const key of path.replace(/^this\./, '').split('.')) {
+    if (cur == null) return undefined;
+    cur = cur[key];
+  }
+  return cur;
+}
+
+function truthy(v) {
+  return Array.isArray(v) ? v.length > 0 : v !== undefined && v !== null && v !== false && v !== '';
+}
+
+function renderNodes(nodes, ctx, resolvePartial) {
+  let out = '';
+  for (const node of nodes) {
+    if (node.t === 'text') {
+      out += node.v;
+    } else if (node.t === 'var') {
+      const v = lookup(ctx, node.v);
+      out += v === undefined || v === null ? '' : String(v);
+    } else if (node.t === 'partial') {
+      const resolved = resolvePartial(node.v, ctx);
+      out += resolved == null ? '' : renderNodes(parse(tokenize(stripHeaderComment(resolved))), ctx, resolvePartial);
+    } else if (node.t === 'block' && node.kw === 'if') {
+      const branch = truthy(lookup(ctx, node.arg)) ? node.body : node.else;
+      out += renderNodes(branch, ctx, resolvePartial);
+    } else if (node.t === 'block' && node.kw === 'each') {
+      const list = lookup(ctx, node.arg);
+      if (Array.isArray(list)) {
+        list.forEach((item, i) => {
+          const child = {
+            ...ctx,
+            this: item,
+            '@': {
+              '@index': i,
+              '@index_1': i + 1,
+              '@first': i === 0,
+              '@last': i === list.length - 1,
+            },
+          };
+          out += renderNodes(node.body, child, resolvePartial);
+        });
+      } else if (node.else.length) {
+        out += renderNodes(node.else, ctx, resolvePartial);
+      }
+    }
+  }
+  return out;
+}
+
+// Render `src` against `ctx`. `resolvePartial(name, ctx)` returns the raw text for
+// a `{{> name }}` include, or null to emit nothing.
+function render(src, ctx = {}, resolvePartial = () => null) {
+  const clean = stripHeaderComment(String(src));
+  return renderNodes(parse(tokenize(clean)), ctx, resolvePartial);
+}
+
+module.exports = { render, stripHeaderComment };