@stonepandastudio/cairn 0.2.0

package/README.md

@@ -0,0 +1,158 @@
+# @stonepandastudio/cairn
+
+Shared AI workflow scaffolding for Stone Panda repos.
+
+Five repos — `glossr-api`, `glossr-cli`, `glossr-frontend`, `snap-proof/backend`,
+`snap-proof/frontend` — each carry an `ai/` folder and a `.claude/commands/` folder
+holding the same workflow: brief → description → plan → execute → review → QA, with
+the steps mirrored into Jira. They were copied between repos by hand and drifted.
+
+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
+agreeing.
+
+```bash
+npm i -D @stonepandastudio/cairn
+npx cairn init --stack backend --tracker jira-server --project-key PROOF --story-type Task
+```
+
+## What v1 does
+
+| Command | |
+|---|---|
+| `cairn tracker <cmd>` | Issue tracker client. Replaces the four copied `ai/scripts/jira.js` files |
+| `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 |
+
+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 Jira client under five repos; bundling prompt changes into the same
+release would make any regression impossible to attribute.
+
+## 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 seeds it at init and never touches it again.
+    contexts/  progress/  tasks/  infrastructure/
+```
+
+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
+`git diff` like any other change.
+
+## Tracker
+
+```bash
+cairn tracker list-statuses PROOF
+cairn tracker create-task "Protected image fetch API"
+cairn tracker create-subtask PROOF-217 "Step 1: signed URL issuing"
+cairn tracker set-status PROOF-218 "In Progress"
+cairn tracker append-description PROOF-217 ./ai/tasks/PROOF-217/brief-step-1.md --markup
+cairn tracker close-story GLO-42          # cascades through subtasks first
+```
+
+Providers are `jira-server` and `none`. `none` is a real provider, not an error case:
+`glossr-cli` has no tracker, and the workflow steps become no-ops rather than every
+command stub needing an "if this repo has Jira" branch written in prose.
+
+Three things the four copied scripts did that this does not:
+
+- **`process.exit` from library code.** Failures throw `TrackerError`; the CLI layer
+  chooses the exit code. That is what makes the client callable from a workflow runner.
+- **Fail on a re-run.** Transitioning to a status the issue already holds is a
+  successful no-op. `NoTransitionError` exits 0 — re-running a step must be safe.
+- **Ask an agent to convert markup by hand.** `ai/JIRA_MARKUP.md` was a prose document
+  in three variants explaining markdown → Jira wiki conversion. It is `toMarkup()` now,
+  under test, reachable via `--markup`.
+
+Credentials come from the repo's `.env` (`JIRA_BASE_URL`, `JIRA_USER`, `JIRA_PASSWORD`).
+Jira Server 8.5.1 predates PAT support, so auth is Basic. Anything already in the
+environment wins over the file.
+
+### Legacy command names
+
+`create-task`, `create-story`, `close-story` and friends are all still accepted, and
+output formats are byte-for-byte what the old scripts printed. Roughly forty prose
+references across five repos name these strings, and the agents parse the output.
+They get renamed in the v2 pass that regenerates those documents.
+
+## Doctor
+
+```bash
+cairn doctor                                     # full table
+cairn doctor --diff ai/WORKFLOW.md               # hunks for one file across repos
+cairn doctor --json
+cairn doctor --strict                            # exit 1 on drift or a hand-edited generated file
+```
+
+It reports two independent axes, and keeping them apart is the point:
+
+**Drift** — cross-repo. Do the copies still agree? Raw comparison is noise, so each
+file is normalized first: BOM and CRLF stripped, repo paths and names folded,
+`GLO-18`/`PROOF-210` folded to `{{ISSUE}}`, and declared vars folded to
+`{{placeholder}}`. What survives is drift no template variable explains. Files are
+then clustered by normalized content; the largest cluster becomes the reference.
+
+| Status | Meaning |
+|---|---|
+| `IDENTICAL` | byte-identical everywhere |
+| `COSMETIC` | differs only in declared vars — extract as a template, zero merge cost |
+| `DRIFT` | two or more genuinely different variants, with a similarity score |
+| `MISSING` | some repos in the cohort lack it |
+| `STRANDED` | exactly one repo has it — promotion candidate |
+
+**Managed** — per-repo, read from `_cairn/manifest.json`. Does what cairn wrote still
+match what is on disk?
+
+| State | Meaning |
+|---|---|
+| `MANAGED` | on-disk hash matches what cairn wrote |
+| `MODIFIED` | someone hand-edited a generated file |
+| `OUTDATED` | cairn has newer content for it |
+| `DELETED` | it is gone; `sync` will restore it |
+
+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
+overwriting a hand edit is the destructive outcome.
+
+### Workspace config (`repos.json`)
+
+- `repos[]` — name, path, stack. Per-repo settings live in each repo's own
+  `cairn.config.json`; the inline `vars` blocks are a fallback used only until a repo
+  has been through `cairn init`, so migration can happen one repo at a time.
+- `pathAliases` — local → canonical. `glossr-cli` calls its stubs `execute-tests.md`
+  and `review-code.md`; aliasing folds them onto the cohort's names instead of
+  reporting one `MISSING` and one `STRANDED` for what is the same file.
+- `shared[]` — glob rules. `cohort: "all"` compares every repo; `cohort: "stack"`
+  compares backend-with-backend. `requires: { tracker: true }` skips repos with no
+  tracker. A repo with no config has an *unknown* tracker, not an absent one, and is
+  never skipped on that basis.
+- Anything not matched by a rule — `ai/contexts/`, `ai/progress/`, `ai/tasks/`,
+  `DATABASE_SCHEMA.md` — is per-project by design and never inspected.
+  `ai/INITIAL_PROMPT.md` is explicitly excluded: four variants at 0% shared content
+  make it a per-project document, not a drifted template.
+
+## Layout
+
+```
+bin/cairn.js           subcommand router
+lib/config.js          cairn.config.json + .env loading
+lib/manifest.js        generated-file hashing and state
+lib/paint.js           ANSI + table rendering
+lib/tracker/           index (registry), cli, jira-server, none
+lib/doctor/            index (analysis + report), scan, normalize, diff
+lib/init.js            cairn init
+templates/shims/       vendored shim source
+schema.json            JSON Schema for cairn.config.json
+test/run.js            dependency-free test runner
+```
+
+No runtime dependencies. Node >= 18. `npm test` runs 34 tests.

package/bin/cairn.js

@@ -0,0 +1,63 @@
+#!/usr/bin/env node
+'use strict';
+
+// cairn — shared AI workflow scaffolding for Stone Panda repos.
+//
+// v1 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.
+
+const HELP = `cairn — shared AI workflow scaffolding
+
+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)
+  version               print version
+
+Run \`cairn <command> --help\` for command options.
+`;
+
+function main() {
+  const [command, ...rest] = process.argv.slice(2);
+
+  switch (command) {
+    case 'tracker':
+      require('../lib/tracker/cli')(rest);
+      return;
+
+    case 'doctor':
+      process.exitCode = require('../lib/doctor').main(rest);
+      return;
+
+    case 'init':
+      process.exitCode = require('../lib/init').main(rest);
+      return;
+
+    case 'version':
+    case '--version':
+    case '-v':
+      console.log(require('../package.json').version);
+      return;
+
+    case undefined:
+    case 'help':
+    case '--help':
+    case '-h':
+      process.stdout.write(HELP);
+      return;
+
+    default:
+      console.error(`Unknown command: ${command}`);
+      process.stderr.write(HELP);
+      process.exitCode = 2;
+  }
+}
+
+main();

package/lib/config.js

@@ -0,0 +1,146 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const CONFIG_NAME = 'cairn.config.json';
+const CAIRN_DIR = '_cairn';
+
+// Boundary rule for the whole framework:
+//   cairn.config.json  — hand-edited, lives at the repo root, cairn only reads it
+//   _cairn/            — cairn writes it, nobody hand-edits it
+// Keeping the editable file out of the generated directory is what stops the
+// generated directory from slowly acquiring hand-maintained state.
+
+const DEFAULTS = {
+  stack: 'unknown',
+  tracker: { provider: 'none' },
+  agents: {},
+  vars: {},
+};
+
+class ConfigError extends Error {}
+
+function configPath(repoPath) {
+  return path.join(repoPath, CONFIG_NAME);
+}
+
+function cairnDir(repoPath) {
+  return path.join(repoPath, CAIRN_DIR);
+}
+
+// Parse a dotenv-ish file. Deliberately minimal — no export keyword, no
+// interpolation, no multiline values. The four repos' .env files are flat.
+function parseEnv(text) {
+  const out = {};
+  for (const line of text.split('\n')) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith('#')) continue;
+    const eq = trimmed.indexOf('=');
+    if (eq === -1) continue;
+    const key = trimmed.slice(0, eq).trim();
+    let value = trimmed.slice(eq + 1).trim();
+    if (
+      (value.startsWith('"') && value.endsWith('"')) ||
+      (value.startsWith("'") && value.endsWith("'"))
+    ) {
+      value = value.slice(1, -1);
+    }
+    out[key] = value;
+  }
+  return out;
+}
+
+// Load .env into process.env without clobbering anything already set, so CI
+// secrets and shell exports always win over the committed-adjacent file.
+function loadEnv(repoPath, relEnv = '.env') {
+  const envPath = path.resolve(repoPath, relEnv);
+  if (!fs.existsSync(envPath)) return {};
+  const parsed = parseEnv(fs.readFileSync(envPath, 'utf8'));
+  for (const [key, value] of Object.entries(parsed)) {
+    if (process.env[key] === undefined) process.env[key] = value;
+  }
+  return parsed;
+}
+
+function normalizeTracker(tracker) {
+  const t = { ...(tracker || {}) };
+  t.provider = t.provider || 'none';
+  t.issueTypes = { story: 'Story', subtask: 'Sub-task', ...(t.issueTypes || {}) };
+  t.statuses = { todo: 'To Do', inProgress: 'In Progress', done: 'Done', ...(t.statuses || {}) };
+  t.env = t.env || '.env';
+  return t;
+}
+
+function validate(cfg, source) {
+  if (cfg.tracker.provider !== 'none' && !cfg.tracker.projectKey) {
+    throw new ConfigError(`${source}: tracker.provider is "${cfg.tracker.provider}" but tracker.projectKey is missing`);
+  }
+  if (cfg.aiKit) {
+    throw new ConfigError(`${source}: "aiKit" is the pre-rename key — rename it to "cairn"`);
+  }
+  return cfg;
+}
+
+// Read a repo's config. `fallbackVars` lets the doctor keep working against
+// repos that have not been migrated yet: repos.json can still carry an inline
+// `vars` block, and it is used only when the repo has no cairn.config.json.
+function loadRepoConfig(repoPath, { fallbackVars = null, required = false } = {}) {
+  const file = configPath(repoPath);
+  if (!fs.existsSync(file)) {
+    if (required) {
+      throw new ConfigError(`No ${CONFIG_NAME} in ${repoPath} — run \`cairn init\` there first`);
+    }
+    return {
+      ...DEFAULTS,
+      tracker: normalizeTracker(null),
+      vars: fallbackVars || {},
+      unmanaged: true,
+      path: repoPath,
+    };
+  }
+
+  let raw;
+  try {
+    raw = JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch (err) {
+    throw new ConfigError(`${file}: invalid JSON — ${err.message}`);
+  }
+
+  const cfg = {
+    ...DEFAULTS,
+    ...raw,
+    tracker: normalizeTracker(raw.tracker),
+    agents: raw.agents || {},
+    vars: raw.vars || fallbackVars || {},
+    unmanaged: false,
+    path: repoPath,
+    configFile: file,
+  };
+  return validate(cfg, file);
+}
+
+// Walk up from cwd looking for cairn.config.json. Lets `cairn tracker …` be run
+// from anywhere inside a repo, which matters because the agents invoke it from
+// wherever their session happens to be.
+function findRepoRoot(start = process.cwd()) {
+  let dir = path.resolve(start);
+  for (;;) {
+    if (fs.existsSync(path.join(dir, CONFIG_NAME))) return dir;
+    const parent = path.dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+module.exports = {
+  CONFIG_NAME,
+  CAIRN_DIR,
+  ConfigError,
+  cairnDir,
+  configPath,
+  findRepoRoot,
+  loadEnv,
+  loadRepoConfig,
+  parseEnv,
+};

package/lib/doctor/diff.js

@@ -0,0 +1,127 @@
+'use strict';
+
+// Line diff utilities with no external dependencies.
+//
+// Full LCS backtracking is O(n*m) in both time and memory, which is fine for the
+// agent/command markdown files this tool compares (a few hundred lines each) but
+// not for anything pathological. Past MAX_CELLS we fall back to a multiset
+// estimate that gets the counts right without producing usable hunks.
+
+const MAX_CELLS = 4_000_000;
+
+function splitLines(text) {
+  const lines = text.split('\n');
+  // A trailing newline yields a final empty element that is not a real line.
+  if (lines.length > 0 && lines[lines.length - 1] === '') lines.pop();
+  return lines;
+}
+
+// Returns an array of ['=' | '-' | '+', line] ops turning `a` into `b`,
+// or null when the input is too large for the LCS table.
+function diffOps(a, b) {
+  const n = a.length;
+  const m = b.length;
+  if ((n + 1) * (m + 1) > MAX_CELLS) return null;
+
+  const w = m + 1;
+  const dp = new Int32Array((n + 1) * w);
+  for (let i = n - 1; i >= 0; i--) {
+    for (let j = m - 1; j >= 0; j--) {
+      dp[i * w + j] =
+        a[i] === b[j]
+          ? dp[(i + 1) * w + (j + 1)] + 1
+          : Math.max(dp[(i + 1) * w + j], dp[i * w + (j + 1)]);
+    }
+  }
+
+  const ops = [];
+  let i = 0;
+  let j = 0;
+  while (i < n && j < m) {
+    if (a[i] === b[j]) {
+      ops.push(['=', a[i]]);
+      i++;
+      j++;
+    } else if (dp[(i + 1) * w + j] >= dp[i * w + (j + 1)]) {
+      ops.push(['-', a[i]]);
+      i++;
+    } else {
+      ops.push(['+', b[j]]);
+      j++;
+    }
+  }
+  while (i < n) ops.push(['-', a[i++]]);
+  while (j < m) ops.push(['+', b[j++]]);
+  return ops;
+}
+
+// Multiset fallback: how many lines of each side have no partner on the other.
+// Ignores ordering, so it under-reports pure moves — acceptable for a size guard.
+function approxStats(a, b) {
+  const pool = new Map();
+  for (const line of a) pool.set(line, (pool.get(line) || 0) + 1);
+  let common = 0;
+  for (const line of b) {
+    const left = pool.get(line) || 0;
+    if (left > 0) {
+      pool.set(line, left - 1);
+      common++;
+    }
+  }
+  return {
+    common,
+    removed: a.length - common,
+    added: b.length - common,
+    approx: true,
+  };
+}
+
+function diffStats(a, b) {
+  const ops = diffOps(a, b);
+  if (!ops) return approxStats(a, b);
+  let common = 0;
+  let added = 0;
+  let removed = 0;
+  for (const [kind] of ops) {
+    if (kind === '=') common++;
+    else if (kind === '+') added++;
+    else removed++;
+  }
+  return { common, added, removed, approx: false };
+}
+
+// 1.0 means identical, 0.0 means nothing in common. Two empty files are identical.
+function similarity(stats, aLen, bLen) {
+  const span = Math.max(aLen, bLen);
+  return span === 0 ? 1 : stats.common / span;
+}
+
+// Groups ops into unified-diff-style hunks with `context` unchanged lines around
+// each run of changes. Returns [] when there is nothing to show.
+function hunks(ops, context = 2) {
+  const changed = ops.map(([kind]) => kind !== '=');
+  const keep = new Array(ops.length).fill(false);
+  for (let i = 0; i < ops.length; i++) {
+    if (!changed[i]) continue;
+    for (let j = Math.max(0, i - context); j <= Math.min(ops.length - 1, i + context); j++) {
+      keep[j] = true;
+    }
+  }
+
+  const out = [];
+  let current = null;
+  for (let i = 0; i < ops.length; i++) {
+    if (keep[i]) {
+      if (!current) {
+        current = [];
+        out.push(current);
+      }
+      current.push(ops[i]);
+    } else {
+      current = null;
+    }
+  }
+  return out;
+}
+
+module.exports = { splitLines, diffOps, diffStats, similarity, hunks };