@stonepandastudio/cairn 0.2.0

package/lib/tracker/jira-server.js

@@ -0,0 +1,291 @@
+'use strict';
+
+// Jira Server (on-prem) REST v2 client.
+//
+// Merged from the four hand-copied `ai/scripts/jira.js` files. The only real
+// differences between those copies were the project key, the issue-type name
+// (`Task` on the PROOF board, `Story` on GLO), and whether close-story existed —
+// all three are configuration, so this is one implementation with three knobs.
+//
+// Auth is Basic (username/password): the deployment at jira.stonepandastudio.com
+// runs Jira Server 8.5.1, which predates personal access tokens.
+//
+// Unlike the scripts it replaces, nothing here calls process.exit — failures
+// throw TrackerError and the CLI layer decides the exit code. That is what makes
+// the client usable from a workflow runner and not only from a shell.
+
+class TrackerError extends Error {
+  constructor(message, { status = null, body = null } = {}) {
+    super(message);
+    this.name = 'TrackerError';
+    this.status = status;
+    this.body = body;
+  }
+}
+
+// Thrown when a transition to the requested status does not exist. Separate type
+// because re-running a workflow step is expected to hit this and it is a no-op,
+// not a failure — the old scripts exited 1 here and every caller had to special-case it.
+class NoTransitionError extends TrackerError {
+  constructor(message, { from = null, available = [] } = {}) {
+    super(message);
+    this.name = 'NoTransitionError';
+    this.from = from;
+    this.available = available;
+  }
+}
+
+const REQUIRED_ENV = ['JIRA_BASE_URL', 'JIRA_USER', 'JIRA_PASSWORD'];
+
+function createJiraServer(config = {}, env = process.env) {
+  const baseUrl = (config.baseUrl || env.JIRA_BASE_URL || '').replace(/\/+$/, '');
+  const user = config.user || env.JIRA_USER;
+  const password = config.password || env.JIRA_PASSWORD;
+  const projectKey = config.projectKey;
+  const issueTypes = { story: 'Story', subtask: 'Sub-task', ...(config.issueTypes || {}) };
+
+  function assertConfig() {
+    const missing = REQUIRED_ENV.filter((k, i) => ![baseUrl, user, password][i]);
+    if (missing.length) {
+      throw new TrackerError(
+        `Missing Jira credentials: ${missing.join(', ')}. Set them in the repo's .env or the environment.`,
+      );
+    }
+    if (!projectKey) {
+      throw new TrackerError('tracker.projectKey is not set in cairn.config.json');
+    }
+  }
+
+  async function api(pathname, options = {}) {
+    assertConfig();
+    const auth = Buffer.from(`${user}:${password}`).toString('base64');
+    let res;
+    try {
+      res = await fetch(`${baseUrl}${pathname}`, {
+        ...options,
+        headers: {
+          Authorization: `Basic ${auth}`,
+          'Content-Type': 'application/json',
+          Accept: 'application/json',
+          ...(options.headers || {}),
+        },
+      });
+    } catch (err) {
+      throw new TrackerError(`Cannot reach Jira at ${baseUrl}: ${err.message}`);
+    }
+    const text = await res.text();
+    let body = null;
+    if (text) {
+      try {
+        body = JSON.parse(text);
+      } catch {
+        body = text;
+      }
+    }
+    if (!res.ok) {
+      const detail =
+        body && body.errorMessages && body.errorMessages.length
+          ? body.errorMessages.join('; ')
+          : typeof body === 'string'
+            ? body.slice(0, 400)
+            : JSON.stringify(body);
+      throw new TrackerError(`Jira ${res.status} on ${pathname}: ${detail}`, {
+        status: res.status,
+        body,
+      });
+    }
+    return body;
+  }
+
+  async function listProjects() {
+    const projects = await api('/rest/api/2/project');
+    return projects.map((p) => ({ key: p.key, name: p.name }));
+  }
+
+  async function listStatuses(key = projectKey) {
+    const data = await api(`/rest/api/2/project/${key}/statuses`);
+    return data.map((it) => ({ type: it.name, statuses: it.statuses.map((s) => s.name) }));
+  }
+
+  async function createIssue({ summary, description = '', type } = {}) {
+    if (!summary) throw new TrackerError('createIssue requires a summary');
+    const body = await api('/rest/api/2/issue', {
+      method: 'POST',
+      body: JSON.stringify({
+        fields: {
+          project: { key: projectKey },
+          summary,
+          description,
+          issuetype: { name: type || issueTypes.story },
+        },
+      }),
+    });
+    return body.key;
+  }
+
+  async function createSubIssue({ parentKey, summary, description = '', type } = {}) {
+    if (!parentKey) throw new TrackerError('createSubIssue requires a parentKey');
+    if (!summary) throw new TrackerError('createSubIssue requires a summary');
+    const body = await api('/rest/api/2/issue', {
+      method: 'POST',
+      body: JSON.stringify({
+        fields: {
+          project: { key: projectKey },
+          parent: { key: parentKey },
+          summary,
+          description,
+          issuetype: { name: type || issueTypes.subtask },
+        },
+      }),
+    });
+    return body.key;
+  }
+
+  async function get(key) {
+    const data = await api(`/rest/api/2/issue/${key}?fields=summary,description,status,assignee,parent,subtasks`);
+    return {
+      key: data.key,
+      summary: data.fields.summary,
+      description: data.fields.description,
+      status: data.fields.status ? data.fields.status.name : null,
+      assignee: data.fields.assignee ? data.fields.assignee.name : null,
+      parent: data.fields.parent ? data.fields.parent.key : null,
+      subtasks: (data.fields.subtasks || []).map((s) => s.key),
+    };
+  }
+
+  async function setFields(key, fields = {}) {
+    const payload = {};
+    if (fields.summary !== undefined) payload.summary = fields.summary;
+    if (fields.description !== undefined) payload.description = fields.description;
+    if (Object.keys(payload).length === 0) {
+      throw new TrackerError('setFields requires at least one of: summary, description');
+    }
+    await api(`/rest/api/2/issue/${key}`, { method: 'PUT', body: JSON.stringify({ fields: payload }) });
+    return key;
+  }
+
+  // Append rather than overwrite: the workflow adds one short summary per step to
+  // the parent issue, and earlier steps' text has to survive.
+  async function appendDescription(key, text) {
+    if (!text) throw new TrackerError('appendDescription requires text');
+    const current = await api(`/rest/api/2/issue/${key}?fields=description`);
+    const existing = current.fields.description || '';
+    const updated = existing ? `${existing}\n\n${text}` : text;
+    await api(`/rest/api/2/issue/${key}`, {
+      method: 'PUT',
+      body: JSON.stringify({ fields: { description: updated } }),
+    });
+    return updated;
+  }
+
+  // Returns { key, from, to, changed }. Already being in the target status is a
+  // success with changed:false, not an error — re-running a step must be safe.
+  async function setStatus(key, statusName) {
+    if (!statusName) throw new TrackerError('setStatus requires a status name');
+    const wanted = statusName.toLowerCase();
+    const data = await api(`/rest/api/2/issue/${key}/transitions`);
+    const match = data.transitions.find(
+      (t) => t.name.toLowerCase() === wanted || (t.to && t.to.name.toLowerCase() === wanted),
+    );
+    if (!match) {
+      const current = await api(`/rest/api/2/issue/${key}?fields=status`);
+      const from = current.fields.status ? current.fields.status.name : null;
+      if (from && from.toLowerCase() === wanted) {
+        return { key, from, to: from, changed: false };
+      }
+      throw new NoTransitionError(
+        `No transition to "${statusName}" from "${from}" for ${key}`,
+        { from, available: data.transitions.map((t) => `${t.name} -> ${t.to ? t.to.name : '?'}`) },
+      );
+    }
+    await api(`/rest/api/2/issue/${key}/transitions`, {
+      method: 'POST',
+      body: JSON.stringify({ transition: { id: match.id } }),
+    });
+    return { key, to: match.to ? match.to.name : statusName, changed: true };
+  }
+
+  // Move an issue and all of its subtasks. Subtasks go first: most workflows
+  // refuse to close a parent while children are open. Subtask failures are
+  // collected rather than thrown so one stuck child doesn't strand the rest.
+  async function closeIssue(key, statusName = 'Done') {
+    const issue = await get(key);
+    const results = [];
+    for (const subKey of issue.subtasks) {
+      try {
+        results.push({ ...(await setStatus(subKey, statusName)), ok: true });
+      } catch (err) {
+        if (!(err instanceof NoTransitionError)) throw err;
+        results.push({ key: subKey, ok: false, reason: err.message });
+      }
+    }
+    try {
+      results.push({ ...(await setStatus(key, statusName)), ok: true });
+    } catch (err) {
+      if (!(err instanceof NoTransitionError)) throw err;
+      results.push({ key, ok: false, reason: err.message });
+    }
+    return { key, status: statusName, results, failed: results.filter((r) => !r.ok).length };
+  }
+
+  async function setAssignee(key, username) {
+    if (!username) throw new TrackerError('setAssignee requires a username');
+    await api(`/rest/api/2/issue/${key}`, {
+      method: 'PUT',
+      body: JSON.stringify({ fields: { assignee: { name: username } } }),
+    });
+    return { key, assignee: username };
+  }
+
+  // Markdown -> Jira wiki markup. This used to be a per-repo prose document
+  // (`ai/JIRA_MARKUP.md`, three variants) telling agents to convert by hand.
+  // Conversion is deterministic, so it belongs in code where it can't drift.
+  function toMarkup(markdown) {
+    const lines = String(markdown).replace(/\r\n?/g, '\n').split('\n');
+    const out = [];
+    let inFence = false;
+    for (const line of lines) {
+      const fence = line.match(/^```(\w*)\s*$/);
+      if (fence) {
+        out.push(inFence ? '{code}' : fence[1] ? `{code:${fence[1]}}` : '{code}');
+        inFence = !inFence;
+        continue;
+      }
+      if (inFence) {
+        out.push(line);
+        continue;
+      }
+      let s = line;
+      s = s.replace(/^(#{1,6})\s+(.*)$/, (_, h, rest) => `h${h.length}. ${rest}`);
+      s = s.replace(/^(\s*)[-*]\s+/, (_, indent) => '*'.repeat(Math.floor(indent.length / 2) + 1) + ' ');
+      s = s.replace(/^(\s*)\d+\.\s+/, (_, indent) => '#'.repeat(Math.floor(indent.length / 2) + 1) + ' ');
+      s = s.replace(/\*\*([^*]+)\*\*/g, '*$1*');
+      s = s.replace(/(^|[^*\w])_([^_]+)_(?=[^*\w]|$)/g, '$1_$2_');
+      s = s.replace(/`([^`]+)`/g, '{{$1}}');
+      s = s.replace(/\[([^\]]+)\]\(([^)]+)\)/g, '[$1|$2]');
+      s = s.replace(/^---+$/, '----');
+      out.push(s);
+    }
+    return out.join('\n');
+  }
+
+  return {
+    name: 'jira-server',
+    projectKey,
+    issueTypes,
+    listProjects,
+    listStatuses,
+    createIssue,
+    createSubIssue,
+    get,
+    setFields,
+    appendDescription,
+    setStatus,
+    closeIssue,
+    setAssignee,
+    toMarkup,
+  };
+}
+
+module.exports = { createJiraServer, TrackerError, NoTransitionError };

package/lib/tracker/none.js

@@ -0,0 +1,55 @@
+'use strict';
+
+const { TrackerError } = require('./jira-server');
+
+// The null tracker. Repos with no issue tracker (glossr-cli today) still run the
+// same workflow commands; the sync points simply become no-ops instead of every
+// command stub needing an "if this repo has Jira" branch in prose.
+//
+// Reads return null, writes report that they were skipped. Nothing throws — a
+// no-op tracker that threw would just push the branching back into the callers.
+
+function createNone() {
+  const skip = (action) => ({ skipped: true, reason: `tracker.provider is "none"`, action });
+
+  return {
+    name: 'none',
+    projectKey: null,
+    issueTypes: {},
+    async listProjects() {
+      return [];
+    },
+    async listStatuses() {
+      return [];
+    },
+    async createIssue() {
+      return null;
+    },
+    async createSubIssue() {
+      return null;
+    },
+    async get() {
+      return null;
+    },
+    async setFields(key) {
+      return skip(`setFields ${key}`);
+    },
+    async appendDescription(key) {
+      return skip(`appendDescription ${key}`);
+    },
+    async setStatus(key, status) {
+      return { key, to: status, changed: false, ...skip('setStatus') };
+    },
+    async closeIssue(key) {
+      return { key, results: [], failed: 0, ...skip('closeIssue') };
+    },
+    async setAssignee(key) {
+      return skip(`setAssignee ${key}`);
+    },
+    toMarkup(markdown) {
+      return markdown;
+    },
+  };
+}
+
+module.exports = { createNone, TrackerError };

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@stonepandastudio/cairn",
+  "version": "0.2.0",
+  "description": "Shared AI workflow scaffolding for Stone Panda repos — issue tracker client and drift doctor.",
+  "license": "UNLICENSED",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/StonePandaStudio/cairn.git"
+  },
+  "bugs": {
+    "url": "https://github.com/StonePandaStudio/cairn/issues"
+  },
+  "homepage": "https://github.com/StonePandaStudio/cairn#readme",
+  "bin": {
+    "cairn": "bin/cairn.js"
+  },
+  "main": "lib/index.js",
+  "exports": {
+    ".": "./lib/index.js",
+    "./tracker": "./lib/tracker/index.js",
+    "./tracker/cli": "./lib/tracker/cli.js"
+  },
+  "files": [
+    "bin/",
+    "lib/",
+    "templates/",
+    "schema.json",
+    "README.md"
+  ],
+  "scripts": {
+    "doctor": "node bin/cairn.js doctor",
+    "doctor:json": "node bin/cairn.js doctor --json",
+    "doctor:strict": "node bin/cairn.js doctor --strict",
+    "test": "node test/run.js",
+    "prepublishOnly": "npm test"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/schema.json

@@ -0,0 +1,71 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://stonepandastudio.com/schema/cairn.config.json",
+  "title": "cairn.config.json",
+  "description": "Per-repo cairn configuration. Hand-edited. Lives at the repo root, never inside _cairn/.",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "$schema": { "type": "string" },
+    "cairn": {
+      "type": "string",
+      "description": "Version of @stonepandastudio/cairn this repo is pinned to."
+    },
+    "stack": {
+      "type": "string",
+      "description": "Comparison cohort for the doctor and, from v2, the preset to render from.",
+      "examples": ["backend", "frontend", "cli"]
+    },
+    "tracker": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "provider": {
+          "type": "string",
+          "enum": ["jira-server", "none"],
+          "default": "none"
+        },
+        "projectKey": {
+          "type": "string",
+          "description": "Required unless provider is \"none\".",
+          "examples": ["PROOF", "GLO"]
+        },
+        "issueTypes": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "story": { "type": "string", "default": "Story" },
+            "subtask": { "type": "string", "default": "Sub-task" }
+          }
+        },
+        "statuses": {
+          "type": "object",
+          "description": "Board status names the workflow transitions to. Verify with `cairn tracker list-statuses`.",
+          "additionalProperties": { "type": "string" }
+        },
+        "env": {
+          "type": "string",
+          "default": ".env",
+          "description": "Path, relative to the repo root, of the file holding tracker credentials."
+        }
+      }
+    },
+    "agents": {
+      "type": "object",
+      "description": "Role -> agent mapping. Read by the doctor's normalizer today; rendered into command stubs in v2.",
+      "additionalProperties": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "name": { "type": "string" },
+          "doc": { "type": "string" }
+        }
+      }
+    },
+    "vars": {
+      "type": "object",
+      "description": "Free-form template variables.",
+      "additionalProperties": { "type": "string" }
+    }
+  }
+}

package/templates/shims/jira.js

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+'use strict';
+
+// Shim. The Jira client itself lives in @stonepandastudio/cairn — this file exists so
+// that the ~40 references to `node ai/scripts/jira.js <command>` scattered across
+// agent docs, command stubs and WORKFLOW.md keep working unchanged.
+//
+// Every command name and every output format is preserved by the CLI it calls.
+// When those documents are regenerated (v2), they will point at `cairn tracker`
+// directly and this shim goes away.
+
+require('@stonepandastudio/cairn/tracker/cli')(process.argv.slice(2));