@stonepandastudio/cairn 0.4.1 → 0.5.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,40 @@ 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 |
 
-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, and leaves anything already on disk alone (reporting it). The
+three-way merge that would re-render over local edits — `cairn sync` — is not built
+yet; for a fresh repo there is nothing to merge.
 
 ## 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
+    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 (that is `cairn sync`, not built yet). 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 +96,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 +132,12 @@ 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 |
+| `OUTDATED` | cairn has newer content for it — needs template hashes; comes with `cairn sync` |
 | `DELETED` | it is gone; a future `cairn sync` will restore it |
 
-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` and `DELETED`. `OUTDATED` (needs the
+template hashes threaded through) and `cairn sync` (the three-way merge that acts on
+these states) are still to come — `cairn render` is greenfield-only for now.
 
 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 +161,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 +173,12 @@ 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/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 54 tests.
+No runtime dependencies. Node >= 18. `npm test` runs 61 tests.

package/bin/cairn.js

@@ -19,6 +19,7 @@ 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)
   version               print version
 
 Run \`cairn <command> --help\` for command options.
@@ -40,6 +41,10 @@ function main() {
       process.exitCode = require('../lib/init').main(rest);
       return;
 
+    case 'render':
+      process.exitCode = require('../lib/render/cli').main(rest);
+      return;
+
     case 'version':
     case '--version':
     case '-v':

package/lib/init.js

@@ -10,22 +10,25 @@ const {
   record,
   writeManifest,
   manifestPath,
+  hashContent,
 } = require('./manifest');
 const { listProviders } = require('./tracker');
 const { makePaint } = require('./paint');
 
 // `cairn init` — make a repo cairn-managed.
 //
-// It writes exactly three things:
+// It writes:
 //   cairn.config.json        hand-editable from here on; cairn never rewrites it
+//                            except with --force
 //   _cairn/scripts/jira.js   vendored shim, tracked in the manifest
 //   _cairn/manifest.json     the record of what was written
 //
-// Plus, when the repo still carries a copied ai/scripts/jira.js, that file is
-// replaced by a shim too. Replacing rather than deleting is deliberate: the five
-// repos have roughly forty prose references to that path, and breaking them all
-// in the same release that swaps the Jira client would make any failure
-// impossible to attribute.
+// Plus, for every copied client the repo still carries (jira.js / youtrack.js /
+// task-tracker.js under ai/scripts/), that file is replaced by the same shim —
+// replacing rather than deleting because dozens of prose references name the path
+// and the shim reads the same argv. A file already holding the shim is skipped; a
+// file hand-edited away from what cairn wrote is kept and reported unless
+// --force-shims. cairn never invents one of these paths in a repo that lacked it.
 
 const SHIM_SOURCE = 'shims/jira.js';
 const SHIM_TARGET = '_cairn/scripts/jira.js';
@@ -55,6 +58,9 @@ 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
 `;
 
@@ -69,6 +75,8 @@ function parseArgs(argv) {
     envPrefix: '',
     shim: true,
     force: false,
+    forceShims: false,
+    render: false,
     dryRun: false,
     color: process.stdout.isTTY,
   };
@@ -83,6 +91,8 @@ function parseArgs(argv) {
     else if (a === '--env-prefix') args.envPrefix = argv[++i];
     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;
@@ -148,29 +158,52 @@ function main(argv = process.argv.slice(2)) {
     return 2;
   }
 
+  const manifest = readManifest(repoPath) || emptyManifest();
+
   const planned = [];
+  const kept = [];
   const config = buildConfig(args);
   planned.push([CONFIG_NAME, JSON.stringify(config, null, 2) + '\n', null]);
 
   const shim = readTemplate(SHIM_SOURCE);
   if (args.shim) {
     planned.push([SHIM_TARGET, shim, SHIM_SOURCE]);
-    // Only replace a legacy path if a copied client is actually there — creating
-    // one in a repo that never had it would invent a path nothing references.
+    // Replace a legacy client only where one is actually present. A file already
+    // holding the shim is left alone; one hand-edited away from what cairn wrote
+    // is kept unless --force — never silently overwrite an edit.
     for (const target of LEGACY_SHIM_TARGETS) {
-      if (fs.existsSync(path.join(repoPath, target))) {
-        planned.push([target, shim, SHIM_SOURCE]);
+      const abs = path.join(repoPath, target);
+      if (!fs.existsSync(abs)) continue;
+      const current = fs.readFileSync(abs, 'utf8');
+      const entry = manifest.files[target];
+
+      // Already the shim and already tracked — nothing to do. If it holds the
+      // shim but isn't in the manifest (someone copied it by hand), fall through
+      // so this run records it.
+      if (current === shim && entry) continue;
+
+      const modified = entry && hashContent(current) !== entry.hash;
+      if (modified && !args.forceShims) {
+        kept.push(target);
+        continue;
       }
+      const note =
+        current === shim ? 'recording existing shim' : entry ? null : `replacing ${current.split('\n').length} lines`;
+      planned.push([target, shim, SHIM_SOURCE, note]);
     }
   }
 
   if (args.dryRun) {
     console.log(paint.bold(`cairn init --dry-run  ${repoPath}`));
-    for (const [rel] of planned) console.log(`  would write  ${rel}`);
+    for (const [rel, , , note] of planned) {
+      console.log(`  would write  ${rel}${note ? paint.dim(`  (${note})`) : ''}`);
+    }
+    for (const rel of kept) {
+      console.log(paint.yellow(`  would keep   ${rel}  (hand-edited — pass --force-shims to replace)`));
+    }
     return 0;
   }
 
-  const manifest = readManifest(repoPath) || emptyManifest();
   for (const [rel, content, source] of planned) {
     const abs = path.join(repoPath, rel);
     fs.mkdirSync(path.dirname(abs), { recursive: true });
@@ -182,10 +215,14 @@ function main(argv = process.argv.slice(2)) {
   writeManifest(repoPath, manifest);
 
   console.log(paint.bold(`cairn init  ${repoPath}`));
-  for (const [rel, , source] of planned) {
-    console.log(`  ${paint.green('wrote')}  ${rel}${source ? paint.dim(`  (${source})`) : ''}`);
+  for (const [rel, , source, note] of planned) {
+    const tag = note || source;
+    console.log(`  ${paint.green('wrote')}  ${rel}${tag ? paint.dim(`  (${tag})`) : ''}`);
   }
   console.log(`  ${paint.green('wrote')}  ${path.relative(repoPath, manifestPath(repoPath)).replace(/\\/g, '/')}`);
+  for (const rel of kept) {
+    console.log(paint.yellow(`  kept   ${rel}  (hand-edited since cairn wrote it — pass --force-shims to replace)`));
+  }
 
   const gitignore = path.join(repoPath, '.gitignore');
   const hasIgnore = fs.existsSync(gitignore) && /^_cairn\b/m.test(fs.readFileSync(gitignore, 'utf8'));
@@ -199,6 +236,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/render/cli.js

@@ -0,0 +1,106 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const { loadRepoConfig, findRepoRoot, ConfigError } = require('../config');
+const { readManifest, emptyManifest, record, writeManifest, 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);
+    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 };