@stonepandastudio/cairn 0.2.1 → 0.3.1

package/README.md

@@ -19,7 +19,7 @@ npx cairn init --stack backend --tracker jira-server --project-key MYPROJ --stor
 
 | Command | |
 |---|---|
-| `cairn tracker <cmd>` | Issue tracker client. Replaces the copied `ai/scripts/jira.js` files |
+| `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 |
 
@@ -58,9 +58,12 @@ cairn tracker append-description MYPROJ-101 ./ai/tasks/MYPROJ-101/brief-step-1.m
 cairn tracker close-story MYPROJ-42          # cascades through subtasks first
 ```
 
-Providers are `jira-server` and `none`. `none` is a real provider, not an error
-case: a repo with no tracker makes the workflow steps no-ops rather than every
-command stub needing an "if this repo has a tracker" branch written in prose.
+Providers are `jira-server`, `youtrack` and `none`, chosen per repo via
+`tracker.provider`. `none` is a real provider, not an error case: a repo with no
+tracker makes the workflow steps no-ops rather than every command stub needing an
+"if this repo has a tracker" branch written in prose. YouTrack has no Task/Sub-task
+type split (a `Subtask` link instead), a `Stage` state field rather than a
+transition graph, and markdown-native descriptions.
 
 Three things the copied scripts did that this does not:
 
@@ -72,8 +75,10 @@ Three things the copied scripts did that this does not:
   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
+Credentials come from the repo's `.env` — `JIRA_BASE_URL` / `JIRA_USER` /
+`JIRA_PASSWORD` for `jira-server` (Basic auth: Jira Server 8.5.1 predates PATs), or
+`YOUTRACK_URL` / `YOUTRACK_TOKEN` / `YOUTRACK_PROJECT` for `youtrack` (Bearer token,
+admin-read scope for the project and stage-bundle lookups). Anything already in the
 environment wins over the file.
 
 ### Legacy command names
@@ -154,7 +159,7 @@ 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/tracker/           index (registry), cli, jira-server, youtrack, none
 lib/doctor/            index (analysis + report), scan, normalize, diff
 lib/init.js            cairn init
 templates/shims/       vendored shim source
@@ -162,4 +167,4 @@ schema.json            JSON Schema for cairn.config.json
 test/run.js            dependency-free test runner
 ```
 
-No runtime dependencies. Node >= 18. `npm test` runs 35 tests.
+No runtime dependencies. Node >= 18. `npm test` runs 47 tests.

package/lib/init.js

@@ -29,7 +29,17 @@ const { makePaint } = require('./paint');
 
 const SHIM_SOURCE = 'shims/jira.js';
 const SHIM_TARGET = '_cairn/scripts/jira.js';
-const LEGACY_SHIM_TARGET = 'ai/scripts/jira.js';
+
+// Copied tracker-client filenames seen across the repos. `cairn init` replaces
+// every one that exists with the shim — the snap-proof repos carry all three
+// (`task-tracker.js` dispatching to `jira.js` / `youtrack.js`), and the docs
+// that reference them by path keep working because the shim reads the same
+// argv. A repo that never had one is left alone; the shim is never invented.
+const LEGACY_SHIM_TARGETS = [
+  'ai/scripts/jira.js',
+  'ai/scripts/youtrack.js',
+  'ai/scripts/task-tracker.js',
+];
 
 const HELP = `cairn init — make a repo cairn-managed
 
@@ -41,7 +51,7 @@ Usage: cairn init [options]
   --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
+  --no-shim                do not vendor or replace the ai/scripts/*.js client shims
   --force                  overwrite an existing cairn.config.json
   --dry-run                print what would be written, write nothing
 `;
@@ -89,8 +99,11 @@ function buildConfig(args) {
   };
   if (args.tracker !== 'none') {
     cfg.tracker.projectKey = args.projectKey;
-    cfg.tracker.issueTypes = { story: args.storyType, subtask: args.subtaskType };
     cfg.tracker.env = '.env';
+    // issueTypes is a Jira concept — YouTrack has no Task/Sub-task split.
+    if (args.tracker === 'jira-server') {
+      cfg.tracker.issueTypes = { story: args.storyType, subtask: args.subtaskType };
+    }
   }
   cfg.agents = {};
   return cfg;
@@ -137,10 +150,12 @@ function main(argv = process.argv.slice(2)) {
   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]);
+    // 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.
+    for (const target of LEGACY_SHIM_TARGETS) {
+      if (fs.existsSync(path.join(repoPath, target))) {
+        planned.push([target, shim, SHIM_SOURCE]);
+      }
     }
   }
 
@@ -183,4 +198,4 @@ function main(argv = process.argv.slice(2)) {
   return 0;
 }
 
-module.exports = { main, buildConfig, HELP, SHIM_TARGET, LEGACY_SHIM_TARGET, cairnDir };
+module.exports = { main, buildConfig, HELP, SHIM_TARGET, LEGACY_SHIM_TARGETS, cairnDir };

package/lib/tracker/index.js

@@ -2,6 +2,7 @@
 
 const { loadEnv, loadRepoConfig, findRepoRoot, ConfigError } = require('../config');
 const { createJiraServer, TrackerError, NoTransitionError } = require('./jira-server');
+const { createYouTrack } = require('./youtrack');
 const { createNone } = require('./none');
 
 // Provider registry. Adding Linear or GitHub Issues later means adding one entry
@@ -9,6 +10,7 @@ const { createNone } = require('./none');
 // sees the shared interface.
 const PROVIDERS = {
   'jira-server': createJiraServer,
+  youtrack: createYouTrack,
   none: createNone,
 };
 

package/lib/tracker/jira-server.js

@@ -241,11 +241,35 @@ function createJiraServer(config = {}, env = process.env) {
   // 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.
+  // The conversion table it implements lives in those repos' `ai/JIRA_MARKUP.md`
+  // and `ai/TASK_TRACKER_MARKUP.md` — headings, bold/italic/strikethrough, inline
+  // and fenced code, links, blockquotes, nested lists, rules, and pipe tables.
+  function toMarkupInline(s) {
+    // Jira uses `*` for bold and `_` for italic. One pass handles `**b**` and
+    // `*i*`: group 1 captures which marker it was, the \s guards stop a bullet
+    // line ("* item") being read as emphasis, and the non-greedy body keeps
+    // `**b** and *i*` from matching as a single span.
+    s = s.replace(/(\*\*?)(?!\s)([^*\n]+?)(?<!\s)\1/g, (_, m, t) =>
+      m === '**' ? `*${t}*` : `_${t}_`,
+    );
+    s = s.replace(/~~([^~]+)~~/g, '-$1-');
+    s = s.replace(/`([^`]+)`/g, '{{$1}}');
+    s = s.replace(/\[([^\]]+)\]\(([^)]+)\)/g, '[$1|$2]');
+    return s;
+  }
+
   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 ROW = /^\s*\|(.+)\|\s*$/;
+    const isSep = (l) => l !== undefined && l.includes('|') && l.includes('-') && /^[\s|:-]+$/.test(l.trim());
+    const cells = (l) => l.match(ROW)[1].split('|').map((c) => toMarkupInline(c.trim()));
+
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i];
+
       const fence = line.match(/^```(\w*)\s*$/);
       if (fence) {
         out.push(inFence ? '{code}' : fence[1] ? `{code:${fence[1]}}` : '{code}');
@@ -256,15 +280,25 @@ function createJiraServer(config = {}, env = process.env) {
         out.push(line);
         continue;
       }
+
+      // Pipe table: a row followed by a `|---|---|` separator. Header cells take
+      // `||`, body cells `|`, and the separator row is dropped (Jira has none).
+      if (ROW.test(line) && isSep(lines[i + 1])) {
+        out.push(`||${cells(line).join('||')}||`);
+        i++; // consume the separator
+        while (ROW.test(lines[i + 1]) && !isSep(lines[i + 1])) {
+          out.push(`|${cells(lines[++i]).join('|')}|`);
+        }
+        continue;
+      }
+
       let s = line;
       s = s.replace(/^(#{1,6})\s+(.*)$/, (_, h, rest) => `h${h.length}. ${rest}`);
+      s = s.replace(/^\s*>\s?(.*)$/, 'bq. $1');
       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(/^---+$/, '----');
+      if (s !== '----') s = toMarkupInline(s);
       out.push(s);
     }
     return out.join('\n');

package/lib/tracker/youtrack.js

@@ -0,0 +1,317 @@
+'use strict';
+
+// YouTrack REST client.
+//
+// Ported from the hand-copied `ai/scripts/youtrack.js` in the snap-proof repos,
+// which those repos ran behind a `task-tracker.js` dispatcher alongside the Jira
+// client. Same shape as jira-server.js: a factory returning the shared Tracker
+// interface, nothing calls process.exit, failures throw TrackerError.
+//
+// YouTrack differs from Jira in three ways this file absorbs:
+//   - no Task/Sub-task issue-type split — a sub-issue is a plain issue joined to
+//     its parent by a "Subtask" issue link (OUTWARD = "parent for").
+//   - the workflow field is a "Stage" state bundle, not a transition graph, so
+//     any value in the bundle is reachable directly and NoTransitionError almost
+//     never fires. An unknown stage name is a TrackerError, not a no-op.
+//   - descriptions are markdown-native, so toMarkup is a passthrough.
+//
+// Auth is a permanent token via the Bearer header (YOUTRACK_TOKEN). The project
+// and stage-bundle lookups hit /api/admin/* — the token needs admin-read scope.
+
+const { TrackerError, NoTransitionError } = require('./jira-server');
+
+const REQUIRED_ENV = ['YOUTRACK_URL', 'YOUTRACK_TOKEN'];
+const STAGE_FIELD = 'Stage';
+const ASSIGNEE_FIELD = 'Assignee';
+
+function createYouTrack(config = {}, env = process.env) {
+  const baseUrl = (config.baseUrl || env.YOUTRACK_URL || '').replace(/\/+$/, '');
+  const token = config.token || env.YOUTRACK_TOKEN;
+  const projectKey = config.projectKey || env.YOUTRACK_PROJECT;
+
+  function assertConfig() {
+    const missing = REQUIRED_ENV.filter((k, i) => ![baseUrl, token][i]);
+    if (missing.length) {
+      throw new TrackerError(
+        `Missing YouTrack credentials: ${missing.join(', ')}. Set them in the repo's .env or the environment.`,
+      );
+    }
+    if (!projectKey) {
+      throw new TrackerError(
+        'YouTrack project is not set — pass tracker.projectKey in cairn.config.json or YOUTRACK_PROJECT in .env',
+      );
+    }
+  }
+
+  async function api(pathname, options = {}) {
+    assertConfig();
+    let res;
+    try {
+      res = await fetch(`${baseUrl}${pathname}`, {
+        ...options,
+        headers: {
+          Authorization: `Bearer ${token}`,
+          'Content-Type': 'application/json',
+          Accept: 'application/json',
+          ...(options.headers || {}),
+        },
+      });
+    } catch (err) {
+      throw new TrackerError(`Cannot reach YouTrack 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.error_description || body.error)
+          ? body.error_description || body.error
+          : typeof body === 'string'
+            ? body.slice(0, 400)
+            : JSON.stringify(body);
+      throw new TrackerError(`YouTrack ${res.status} on ${pathname}: ${detail}`, {
+        status: res.status,
+        body,
+      });
+    }
+    return body;
+  }
+
+  // --- internal lookups (admin scope) --------------------------------------
+
+  async function resolveProjectId() {
+    const projects = await api('/api/admin/projects?fields=id,shortName');
+    const p = (projects || []).find((pr) => pr.shortName === projectKey);
+    if (!p) throw new TrackerError(`YouTrack project "${projectKey}" not found`);
+    return p.id;
+  }
+
+  async function resolveStageBundleId(shortName = projectKey) {
+    const fields = await api(
+      `/api/admin/projects/${shortName}/customFields?fields=field(name),bundle(id)`,
+    );
+    const stage = (fields || []).find((f) => f.field && f.field.name === STAGE_FIELD);
+    if (!stage || !stage.bundle) {
+      throw new TrackerError(`No "${STAGE_FIELD}" field on YouTrack project ${shortName}`);
+    }
+    return stage.bundle.id;
+  }
+
+  async function stageNames() {
+    const bundleId = await resolveStageBundleId();
+    const bundle = await api(
+      `/api/admin/customFieldSettings/bundles/state/${bundleId}?fields=values(name,isResolved)`,
+    );
+    return (bundle.values || []).map((v) => ({ name: v.name, resolved: !!v.isResolved }));
+  }
+
+  async function issueLinks(key) {
+    return api(`/api/issues/${key}/links?fields=direction,linkType(name),issues(idReadable)`);
+  }
+
+  async function childKeys(key) {
+    const links = await issueLinks(key);
+    const sub = (links || []).find(
+      (l) => l.linkType && l.linkType.name === 'Subtask' && l.direction === 'OUTWARD',
+    );
+    return sub ? sub.issues.map((i) => i.idReadable) : [];
+  }
+
+  async function parentKeyOf(key) {
+    const links = await issueLinks(key);
+    const sub = (links || []).find(
+      (l) => l.linkType && l.linkType.name === 'Subtask' && l.direction === 'INWARD',
+    );
+    return sub && sub.issues.length ? sub.issues[0].idReadable : null;
+  }
+
+  // --- interface ---------------------------------------------------------
+
+  async function listProjects() {
+    const projects = await api('/api/admin/projects?fields=shortName,name');
+    return (projects || []).map((p) => ({ key: p.shortName, name: p.name }));
+  }
+
+  // One "Stage" bundle rather than a per-type status list, so a single group.
+  async function listStatuses() {
+    const values = await stageNames();
+    return [{ type: STAGE_FIELD, statuses: values.map((v) => v.name) }];
+  }
+
+  // `type` is accepted for interface parity and ignored — YouTrack has no split.
+  async function createIssue({ summary, description = '' } = {}) {
+    if (!summary) throw new TrackerError('createIssue requires a summary');
+    const projectId = await resolveProjectId();
+    const body = await api('/api/issues?fields=idReadable', {
+      method: 'POST',
+      body: JSON.stringify({ project: { id: projectId }, summary, description }),
+    });
+    return body.idReadable;
+  }
+
+  async function createSubIssue({ parentKey, summary, description = '' } = {}) {
+    if (!parentKey) throw new TrackerError('createSubIssue requires a parentKey');
+    if (!summary) throw new TrackerError('createSubIssue requires a summary');
+    const projectId = await resolveProjectId();
+    const created = await api('/api/issues?fields=id,idReadable', {
+      method: 'POST',
+      body: JSON.stringify({ project: { id: projectId }, summary, description }),
+    });
+    // Join to the parent with a Subtask link via the command API.
+    await api('/api/commands', {
+      method: 'POST',
+      body: JSON.stringify({ issues: [{ id: created.id }], query: `subtask of ${parentKey}` }),
+    });
+    return created.idReadable;
+  }
+
+  async function get(key) {
+    const data = await api(
+      `/api/issues/${key}?fields=idReadable,summary,description,customFields(name,value(name,login))`,
+    );
+    const fields = data.customFields || [];
+    const stage = fields.find((f) => f.name === STAGE_FIELD);
+    const assignee = fields.find((f) => f.name === ASSIGNEE_FIELD);
+    const [parent, subtasks] = await Promise.all([parentKeyOf(key), childKeys(key)]);
+    return {
+      key: data.idReadable,
+      summary: data.summary,
+      description: data.description,
+      status: (stage && stage.value && stage.value.name) || null,
+      assignee: (assignee && assignee.value && assignee.value.login) || null,
+      parent,
+      subtasks,
+    };
+  }
+
+  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(`/api/issues/${key}?fields=idReadable`, {
+      method: 'POST',
+      body: JSON.stringify(payload),
+    });
+    return key;
+  }
+
+  async function appendDescription(key, text) {
+    if (!text) throw new TrackerError('appendDescription requires text');
+    const current = await api(`/api/issues/${key}?fields=description`);
+    const existing = (current && current.description) || '';
+    const updated = existing ? `${existing}\n\n${text}` : text;
+    await api(`/api/issues/${key}?fields=idReadable`, {
+      method: 'POST',
+      body: JSON.stringify({ description: updated }),
+    });
+    return updated;
+  }
+
+  async function currentStage(key) {
+    const data = await api(`/api/issues/${key}?fields=customFields(name,value(name))`);
+    const f = (data.customFields || []).find((x) => x.name === STAGE_FIELD);
+    return (f && f.value && f.value.name) || null;
+  }
+
+  // Returns { key, from, to, changed }. Already at the target stage is a success
+  // with changed:false — re-running a workflow step must be safe. An unknown
+  // stage name throws TrackerError (with the valid names), not NoTransitionError:
+  // YouTrack has no transition graph, so this is a bad argument, not a dead end.
+  async function setStatus(key, statusName) {
+    if (!statusName) throw new TrackerError('setStatus requires a status name');
+    const from = await currentStage(key);
+    if (from && from.toLowerCase() === statusName.toLowerCase()) {
+      return { key, from, to: from, changed: false };
+    }
+    try {
+      await api(`/api/issues/${key}?fields=idReadable`, {
+        method: 'POST',
+        body: JSON.stringify({
+          customFields: [
+            { name: STAGE_FIELD, $type: 'StateIssueCustomField', value: { name: statusName } },
+          ],
+        }),
+      });
+    } catch (err) {
+      let names = [];
+      try {
+        names = (await stageNames()).map((v) => v.name);
+      } catch {
+        /* keep the original error if the bundle lookup also fails */
+      }
+      throw new TrackerError(
+        `Could not set ${key} ${STAGE_FIELD} to "${statusName}"` +
+          (names.length ? ` — valid: ${names.join(', ')}` : `: ${err.message}`),
+      );
+    }
+    return { key, from, to: statusName, changed: true };
+  }
+
+  // Move an issue and its subtasks. Subtasks first. A subtask that can't be
+  // moved is collected, not 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 TrackerError)) 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 TrackerError)) 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(`/api/issues/${key}?fields=idReadable`, {
+      method: 'POST',
+      body: JSON.stringify({
+        customFields: [
+          { name: ASSIGNEE_FIELD, $type: 'SingleUserIssueCustomField', value: { login: username } },
+        ],
+      }),
+    });
+    return { key, assignee: username };
+  }
+
+  // YouTrack renders markdown natively — nothing to convert.
+  function toMarkup(markdown) {
+    return markdown;
+  }
+
+  return {
+    name: 'youtrack',
+    projectKey,
+    issueTypes: {},
+    listProjects,
+    listStatuses,
+    createIssue,
+    createSubIssue,
+    get,
+    setFields,
+    appendDescription,
+    setStatus,
+    closeIssue,
+    setAssignee,
+    toMarkup,
+  };
+}
+
+module.exports = { createYouTrack, TrackerError, NoTransitionError };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stonepandastudio/cairn",
-  "version": "0.2.1",
+  "version": "0.3.1",
   "description": "Shared AI workflow scaffolding for Stone Panda repos — issue tracker client and drift doctor.",
   "license": "UNLICENSED",
   "repository": {

package/schema.json

@@ -22,16 +22,17 @@
       "properties": {
         "provider": {
           "type": "string",
-          "enum": ["jira-server", "none"],
+          "enum": ["jira-server", "youtrack", "none"],
           "default": "none"
         },
         "projectKey": {
           "type": "string",
-          "description": "Required unless provider is \"none\".",
+          "description": "Required unless provider is \"none\". For youtrack, falls back to YOUTRACK_PROJECT in .env.",
           "examples": ["PROOF", "GLO"]
         },
         "issueTypes": {
           "type": "object",
+          "description": "jira-server only. YouTrack has no Task/Sub-task type split.",
           "additionalProperties": false,
           "properties": {
             "story": { "type": "string", "default": "Story" },