@stonepandastudio/cairn 0.2.0

package/lib/init.js

@@ -0,0 +1,186 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const { CONFIG_NAME, configPath, cairnDir } = require('./config');
+const {
+  emptyManifest,
+  readManifest,
+  record,
+  writeManifest,
+  manifestPath,
+} = require('./manifest');
+const { listProviders } = require('./tracker');
+const { makePaint } = require('./paint');
+
+// `cairn init` — make a repo cairn-managed.
+//
+// It writes exactly three things:
+//   cairn.config.json        hand-editable from here on; cairn never rewrites it
+//   _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.
+
+const SHIM_SOURCE = 'shims/jira.js';
+const SHIM_TARGET = '_cairn/scripts/jira.js';
+const LEGACY_SHIM_TARGET = 'ai/scripts/jira.js';
+
+const HELP = `cairn init — make a repo cairn-managed
+
+Usage: cairn init [options]
+
+  --repo <path>            repo to initialise (default: cwd)
+  --stack <name>           backend | frontend | cli | ...   (default: unknown)
+  --tracker <provider>     ${listProviders().join(' | ')}   (default: none)
+  --project-key <KEY>      tracker project key, e.g. PROOF
+  --story-type <name>      parent issue type  (default: Story)
+  --subtask-type <name>    child issue type   (default: Sub-task)
+  --no-shim                do not vendor the ai/scripts/jira.js compatibility shim
+  --force                  overwrite an existing cairn.config.json
+  --dry-run                print what would be written, write nothing
+`;
+
+function parseArgs(argv) {
+  const args = {
+    repo: process.cwd(),
+    stack: 'unknown',
+    tracker: 'none',
+    projectKey: null,
+    storyType: 'Story',
+    subtaskType: 'Sub-task',
+    shim: true,
+    force: false,
+    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 === '--stack') args.stack = argv[++i];
+    else if (a === '--tracker') args.tracker = argv[++i];
+    else if (a === '--project-key') args.projectKey = argv[++i];
+    else if (a === '--story-type') args.storyType = argv[++i];
+    else if (a === '--subtask-type') args.subtaskType = argv[++i];
+    else if (a === '--no-shim') args.shim = false;
+    else if (a === '--force') args.force = 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;
+    else {
+      console.error(`Unknown argument: ${a}`);
+      return { error: 2 };
+    }
+  }
+  return args;
+}
+
+function buildConfig(args) {
+  const cfg = {
+    $schema: `./node_modules/${require('../package.json').name}/schema.json`,
+    cairn: require('../package.json').version,
+    stack: args.stack,
+    tracker: { provider: args.tracker },
+  };
+  if (args.tracker !== 'none') {
+    cfg.tracker.projectKey = args.projectKey;
+    cfg.tracker.issueTypes = { story: args.storyType, subtask: args.subtaskType };
+    cfg.tracker.env = '.env';
+  }
+  cfg.agents = {};
+  return cfg;
+}
+
+function readTemplate(rel) {
+  return fs.readFileSync(path.join(__dirname, '..', 'templates', rel), 'utf8');
+}
+
+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 repoPath = path.resolve(args.repo);
+
+  if (!fs.existsSync(repoPath)) {
+    console.error(`Repo not found: ${repoPath}`);
+    return 2;
+  }
+  if (!listProviders().includes(args.tracker)) {
+    console.error(`Unknown tracker "${args.tracker}". Available: ${listProviders().join(', ')}`);
+    return 2;
+  }
+  if (args.tracker !== 'none' && !args.projectKey) {
+    console.error(`--tracker ${args.tracker} requires --project-key`);
+    return 2;
+  }
+
+  const cfgFile = configPath(repoPath);
+  if (fs.existsSync(cfgFile) && !args.force) {
+    console.error(`${cfgFile} already exists — pass --force to overwrite`);
+    return 2;
+  }
+
+  const planned = [];
+  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 the legacy path if a copied client is actually there. Creating
+    // it in a repo that never had one would invent a path nothing references.
+    if (fs.existsSync(path.join(repoPath, LEGACY_SHIM_TARGET))) {
+      planned.push([LEGACY_SHIM_TARGET, shim, SHIM_SOURCE]);
+    }
+  }
+
+  if (args.dryRun) {
+    console.log(paint.bold(`cairn init --dry-run  ${repoPath}`));
+    for (const [rel] of planned) console.log(`  would write  ${rel}`);
+    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 });
+    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);
+  }
+  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})`) : ''}`);
+  }
+  console.log(`  ${paint.green('wrote')}  ${path.relative(repoPath, manifestPath(repoPath)).replace(/\\/g, '/')}`);
+
+  const gitignore = path.join(repoPath, '.gitignore');
+  const hasIgnore = fs.existsSync(gitignore) && /^_cairn\b/m.test(fs.readFileSync(gitignore, 'utf8'));
+  if (hasIgnore) {
+    console.log(
+      paint.yellow(`  warning: _cairn/ is gitignored in this repo — generated files must be committed`),
+    );
+  }
+  if (args.tracker !== 'none') {
+    console.log(
+      paint.dim(`\n  Next: ensure .env has JIRA_BASE_URL, JIRA_USER, JIRA_PASSWORD, then run`),
+    );
+    console.log(paint.dim(`        npx cairn tracker list-statuses ${args.projectKey}`));
+  }
+  return 0;
+}
+
+module.exports = { main, buildConfig, HELP, SHIM_TARGET, LEGACY_SHIM_TARGET, cairnDir };

package/lib/manifest.js

@@ -0,0 +1,120 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+
+const { CAIRN_DIR, cairnDir } = require('./config');
+
+const MANIFEST_NAME = 'manifest.json';
+const MANIFEST_VERSION = 1;
+const GENERATOR = require('../package.json').name;
+
+// The manifest is what makes "generated" auditable. Without it, a vendored file
+// that someone hand-edited is indistinguishable from one cairn wrote — which is
+// exactly the failure mode that produced the drift this tool exists to report.
+//
+// Each entry records the template it came from and the hash of what cairn wrote.
+// Comparing that to the hash on disk gives three states instead of one:
+//
+//   MANAGED   on-disk hash === written hash            nothing to do
+//   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
+
+function manifestPath(repoPath) {
+  return path.join(cairnDir(repoPath), MANIFEST_NAME);
+}
+
+// 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) {
+  const normalized = String(text).replace(/^/, '').replace(/\r\n?/g, '\n');
+  return crypto.createHash('sha256').update(normalized, 'utf8').digest('hex').slice(0, 16);
+}
+
+function emptyManifest() {
+  return { version: MANIFEST_VERSION, generator: GENERATOR, files: {} };
+}
+
+function readManifest(repoPath) {
+  const file = manifestPath(repoPath);
+  if (!fs.existsSync(file)) return null;
+  try {
+    const parsed = JSON.parse(fs.readFileSync(file, 'utf8'));
+    if (!parsed.files) parsed.files = {};
+    return parsed;
+  } catch (err) {
+    throw new Error(`${file}: invalid JSON — ${err.message}`);
+  }
+}
+
+function writeManifest(repoPath, manifest) {
+  const dir = cairnDir(repoPath);
+  fs.mkdirSync(dir, { recursive: true });
+  const ordered = {
+    version: MANIFEST_VERSION,
+    generator: GENERATOR,
+    generatedAt: new Date().toISOString(),
+    files: Object.fromEntries(Object.entries(manifest.files).sort(([a], [b]) => a.localeCompare(b))),
+  };
+  fs.writeFileSync(manifestPath(repoPath), JSON.stringify(ordered, null, 2) + '\n', 'utf8');
+  return ordered;
+}
+
+// Record that cairn wrote `content` to `relPath` from template `source`.
+function record(manifest, relPath, source, content, extra = {}) {
+  manifest.files[relPath.replace(/\\/g, '/')] = {
+    source,
+    hash: hashContent(content),
+    ...extra,
+  };
+  return manifest;
+}
+
+// Compare every manifest entry against what is actually on disk. `templateHashes`
+// is an optional { source -> hash } map; supply it to detect OUTDATED as well.
+function statusFor(repoPath, manifest, templateHashes = null) {
+  const results = [];
+  for (const [rel, entry] of Object.entries(manifest.files)) {
+    const abs = path.join(repoPath, rel);
+    if (!fs.existsSync(abs)) {
+      results.push({ path: rel, source: entry.source, state: 'DELETED' });
+      continue;
+    }
+    const onDisk = hashContent(fs.readFileSync(abs, 'utf8'));
+    if (onDisk !== entry.hash) {
+      results.push({ path: rel, source: entry.source, state: 'MODIFIED' });
+      continue;
+    }
+    if (templateHashes && templateHashes[entry.source] && templateHashes[entry.source] !== entry.hash) {
+      results.push({ path: rel, source: entry.source, state: 'OUTDATED' });
+      continue;
+    }
+    results.push({ path: rel, source: entry.source, state: 'MANAGED' });
+  }
+  return results.sort((a, b) => a.path.localeCompare(b.path));
+}
+
+// Header stamped into every generated text file. `cairn doctor` reads the
+// manifest rather than this comment, but the comment is what a human sees first.
+function header(source, content, comment = 'html') {
+  const line = `cairn:generated source=${source} hash=${hashContent(content)} — edit cairn.config.json, not this file`;
+  if (comment === 'js') return `// ${line}\n`;
+  if (comment === 'hash') return `# ${line}\n`;
+  return `<!-- ${line} -->\n`;
+}
+
+module.exports = {
+  CAIRN_DIR,
+  MANIFEST_NAME,
+  MANIFEST_VERSION,
+  emptyManifest,
+  hashContent,
+  header,
+  manifestPath,
+  readManifest,
+  record,
+  statusFor,
+  writeManifest,
+};

package/lib/paint.js

@@ -0,0 +1,41 @@
+'use strict';
+
+// Tiny ANSI helper. Every command takes the same --color / --no-color pair, so
+// the enabled flag is decided once at the CLI boundary and threaded down.
+
+function makePaint(enabled) {
+  const wrap = (code) => (s) => (enabled ? `\x1b[${code}m${s}\x1b[0m` : String(s));
+  return {
+    enabled,
+    bold: wrap(1),
+    dim: wrap(2),
+    red: wrap(31),
+    green: wrap(32),
+    yellow: wrap(33),
+    blue: wrap(34),
+    magenta: wrap(35),
+    cyan: wrap(36),
+  };
+}
+
+function stripAnsi(s) {
+  return String(s).replace(/\x1b\[[0-9;]*m/g, '');
+}
+
+// Column-aligned table that measures visible width, not byte width, so coloured
+// cells don't blow up the alignment.
+function table(rows, headers, paint) {
+  const widths = headers.map((h, i) =>
+    Math.max(h.length, ...rows.map((r) => stripAnsi(r[i]).length)),
+  );
+  const line = (cells) =>
+    cells
+      .map((cell, i) => String(cell) + ' '.repeat(widths[i] - stripAnsi(cell).length))
+      .join('  ')
+      .trimEnd();
+  const out = [paint.bold(line(headers)), paint.dim(widths.map((w) => '─'.repeat(w)).join('  '))];
+  for (const row of rows) out.push(line(row));
+  return out.join('\n');
+}
+
+module.exports = { makePaint, stripAnsi, table };

package/lib/tracker/cli.js

@@ -0,0 +1,240 @@
+'use strict';
+
+const fs = require('fs');
+
+const { trackerForRepo, TrackerError, NoTransitionError } = require('./index');
+const { ConfigError } = require('../config');
+
+// Command-line surface for the tracker.
+//
+// Every command name from the four replaced `ai/scripts/jira.js` copies is kept,
+// including the ones that only existed in one repo (`create-story` in glossr,
+// `create-task` in snap, `close-story` in glossr-frontend). They are aliases onto
+// one implementation now, but the names stay because agent docs, command stubs
+// and WORKFLOW.md across five repos reference them by string. Renaming them is a
+// v2 concern, done in the same pass that regenerates those files.
+//
+// Output shapes are also preserved verbatim — `create-*` prints the bare key,
+// `get` prints JSON, `set-status` prints `KEY -> Status` — because the agents
+// read this output. Changing it would silently break prompts.
+
+const ALIASES = {
+  'create-task': 'create-issue',
+  'create-story': 'create-issue',
+  'create-subtask': 'create-subissue',
+  'close-story': 'close',
+  'close-task': 'close',
+};
+
+const USAGE = `cairn tracker <command> [...args]
+
+  list-projects
+  list-statuses [projectKey]
+  create-task | create-story <summary> [descriptionOrFile]
+  create-subtask <parentKey> <summary> [descriptionOrFile]
+  get <key>
+  set-fields <key> [--summary ..] [--description ..] [--description-file ..]
+  append-description <key> <textOrFile>
+  set-status <key> <statusName>
+  close-story <key> [statusName=Done]
+  set-assignee <key> <username>
+
+  --markup   convert markdown input to Jira wiki markup before sending
+  --json     print machine-readable output where the command supports it
+`;
+
+function parseFlags(args) {
+  const flags = {};
+  const rest = [];
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg.startsWith('--')) {
+      const key = arg.slice(2);
+      const next = args[i + 1];
+      if (next === undefined || next.startsWith('--')) {
+        flags[key] = true;
+      } else {
+        flags[key] = next;
+        i++;
+      }
+    } else {
+      rest.push(arg);
+    }
+  }
+  return { flags, rest };
+}
+
+// A value that names an existing file is read as one; otherwise it is the text.
+// Inherited behaviour — the workflow passes description files by path.
+function readMaybeFile(value) {
+  if (value === undefined || value === true) return undefined;
+  try {
+    if (fs.existsSync(value) && fs.statSync(value).isFile()) return fs.readFileSync(value, 'utf8');
+  } catch {
+    /* fall through to literal */
+  }
+  return value;
+}
+
+async function run(argv, { cwd = process.cwd(), out = console.log, err = console.error } = {}) {
+  const [rawCommand, ...args] = argv;
+  if (!rawCommand || rawCommand === '--help' || rawCommand === '-h') {
+    out(USAGE);
+    return 0;
+  }
+
+  const command = ALIASES[rawCommand] || rawCommand;
+  const { flags, rest } = parseFlags(args);
+
+  let tracker;
+  try {
+    ({ tracker } = trackerForRepo(cwd));
+  } catch (e) {
+    if (e instanceof ConfigError) {
+      err(e.message);
+      return 2;
+    }
+    throw e;
+  }
+
+  const markup = (text) => (flags.markup && text !== undefined ? tracker.toMarkup(text) : text);
+
+  try {
+    switch (command) {
+      case 'list-projects': {
+        const projects = await tracker.listProjects();
+        if (flags.json) out(JSON.stringify(projects, null, 2));
+        else for (const p of projects) out(`${p.key} - ${p.name}`);
+        return 0;
+      }
+
+      case 'list-statuses': {
+        const groups = await tracker.listStatuses(rest[0]);
+        if (flags.json) out(JSON.stringify(groups, null, 2));
+        else for (const g of groups) out(`${g.type}: ${g.statuses.join(', ')}`);
+        return 0;
+      }
+
+      case 'create-issue': {
+        const key = await tracker.createIssue({
+          summary: rest[0],
+          description: markup(readMaybeFile(rest[1])) || '',
+          type: flags.type,
+        });
+        if (key === null) {
+          err('tracker.provider is "none" — no issue created');
+          return 0;
+        }
+        out(key);
+        return 0;
+      }
+
+      case 'create-subissue': {
+        const key = await tracker.createSubIssue({
+          parentKey: rest[0],
+          summary: rest[1],
+          description: markup(readMaybeFile(rest[2])) || '',
+          type: flags.type,
+        });
+        if (key === null) {
+          err('tracker.provider is "none" — no sub-issue created');
+          return 0;
+        }
+        out(key);
+        return 0;
+      }
+
+      case 'get': {
+        const issue = await tracker.get(rest[0]);
+        out(JSON.stringify(issue, null, 2));
+        return 0;
+      }
+
+      case 'set-fields': {
+        const descArg = flags['description-file'] !== undefined ? flags['description-file'] : flags.description;
+        const fields = {};
+        if (flags.summary !== undefined && flags.summary !== true) fields.summary = flags.summary;
+        if (descArg !== undefined) fields.description = markup(readMaybeFile(descArg));
+        await tracker.setFields(rest[0], fields);
+        out(`${rest[0]} updated`);
+        return 0;
+      }
+
+      case 'append-description': {
+        await tracker.appendDescription(rest[0], markup(readMaybeFile(rest[1])));
+        out(`${rest[0]} description appended`);
+        return 0;
+      }
+
+      case 'set-status': {
+        const result = await tracker.setStatus(rest[0], rest[1]);
+        // Never print `KEY -> Status` for something that did not happen — the
+        // agents read this line as confirmation the board was actually moved.
+        if (result.skipped) err(`${result.key}: ${result.reason} — status not changed`);
+        else if (result.changed === false) out(`${result.key} already ${result.to}`);
+        else out(`${result.key} -> ${result.to}`);
+        return 0;
+      }
+
+      case 'close': {
+        const status = rest[1] || 'Done';
+        const result = await tracker.closeIssue(rest[0], status);
+        if (result.skipped) {
+          err(`${result.key}: ${result.reason} — nothing closed`);
+          return 0;
+        }
+        for (const r of result.results) {
+          if (r.ok) out(`${r.key} -> ${r.to}`);
+          else err(`${r.key}: ${r.reason}`);
+        }
+        if (result.failed) {
+          err(`${result.failed} issue(s) could not be moved to "${status}".`);
+          return 1;
+        }
+        out(`${result.key} and all subtasks are now "${status}".`);
+        return 0;
+      }
+
+      case 'set-assignee': {
+        const result = await tracker.setAssignee(rest[0], rest[1]);
+        out(`${result.key} assigned to ${result.assignee}`);
+        return 0;
+      }
+
+      default:
+        err(`Unknown command: ${rawCommand}`);
+        err(USAGE);
+        return 2;
+    }
+  } catch (e) {
+    // A missing transition means the issue is already at or past the target
+    // status on a re-run. Report it, but don't fail the workflow step.
+    if (e instanceof NoTransitionError) {
+      err(e.message);
+      if (e.available.length) err(`  available: ${e.available.join(', ')}`);
+      return 0;
+    }
+    if (e instanceof TrackerError || e instanceof ConfigError) {
+      err(e.message);
+      return 1;
+    }
+    throw e;
+  }
+}
+
+// Entry point used by the vendored shim: `require('@stonepandastudio/cairn/tracker/cli')(args)`.
+function main(argv = process.argv.slice(2)) {
+  run(argv)
+    .then((code) => {
+      if (code) process.exitCode = code;
+    })
+    .catch((e) => {
+      console.error(e);
+      process.exitCode = 1;
+    });
+}
+
+module.exports = main;
+module.exports.run = run;
+module.exports.parseFlags = parseFlags;
+module.exports.USAGE = USAGE;

package/lib/tracker/index.js

@@ -0,0 +1,51 @@
+'use strict';
+
+const { loadEnv, loadRepoConfig, findRepoRoot, ConfigError } = require('../config');
+const { createJiraServer, TrackerError, NoTransitionError } = require('./jira-server');
+const { createNone } = require('./none');
+
+// Provider registry. Adding Linear or GitHub Issues later means adding one entry
+// here and one file next to jira-server.js — the workflow layer above only ever
+// sees the shared interface.
+const PROVIDERS = {
+  'jira-server': createJiraServer,
+  none: createNone,
+};
+
+function listProviders() {
+  return Object.keys(PROVIDERS);
+}
+
+// Build a tracker straight from a tracker config block plus an env bag.
+function createTracker(trackerConfig = {}, env = process.env) {
+  const name = trackerConfig.provider || 'none';
+  const factory = PROVIDERS[name];
+  if (!factory) {
+    throw new ConfigError(
+      `Unknown tracker provider "${name}". Available: ${listProviders().join(', ')}`,
+    );
+  }
+  return factory(trackerConfig, env);
+}
+
+// Build a tracker for a repo: find the repo root, read cairn.config.json, load
+// its .env, then construct. This is the entry point the CLI and the shim use.
+function trackerForRepo(startDir = process.cwd()) {
+  const repoPath = findRepoRoot(startDir);
+  if (!repoPath) {
+    throw new ConfigError(
+      `No cairn.config.json found in ${startDir} or any parent — run \`cairn init\` in the repo root`,
+    );
+  }
+  const config = loadRepoConfig(repoPath, { required: true });
+  loadEnv(repoPath, config.tracker.env);
+  return { tracker: createTracker(config.tracker), config, repoPath };
+}
+
+module.exports = {
+  createTracker,
+  trackerForRepo,
+  listProviders,
+  TrackerError,
+  NoTransitionError,
+};