@stonepandastudio/cairn 0.2.0 → 0.3.0

package/README.md

@@ -1,11 +1,10 @@
 # @stonepandastudio/cairn
 
-Shared AI workflow scaffolding for Stone Panda repos.
+Shared AI workflow scaffolding, kept in sync across several 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.
+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.
 
 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
@@ -13,21 +12,21 @@ agreeing.
 
 ```bash
 npm i -D @stonepandastudio/cairn
-npx cairn init --stack backend --tracker jira-server --project-key PROOF --story-type Task
+npx cairn init --stack backend --tracker jira-server --project-key MYPROJ --story-type Task
 ```
 
 ## What v1 does
 
 | Command | |
 |---|---|
-| `cairn tracker <cmd>` | Issue tracker client. Replaces the four 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 |
 
 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.
+v1 swaps the tracker client under the consuming repos; bundling prompt changes into
+the same release would make any regression impossible to attribute.
 
 ## The two folders
 
@@ -37,7 +36,7 @@ repo/
   _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.
+  ai/                    project-owned. cairn never touches it.
     contexts/  progress/  tasks/  infrastructure/
 ```
 
@@ -51,38 +50,43 @@ Generated files are **committed**, not gitignored. Claude Code discovers
 ## 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
+cairn tracker list-statuses MYPROJ
+cairn tracker create-task "Some task title"
+cairn tracker create-subtask MYPROJ-101 "Step 1: first slice"
+cairn tracker set-status MYPROJ-102 "In Progress"
+cairn tracker append-description MYPROJ-101 ./ai/tasks/MYPROJ-101/brief-step-1.md --markup
+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:
-`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.
+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 four copied scripts did that this does not:
+Three things the 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`.
+  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
 
 `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.
+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.
 
 ## Doctor
 
@@ -93,13 +97,15 @@ cairn doctor --json
 cairn doctor --strict                            # exit 1 on drift or a hand-edited generated file
 ```
 
+Run it from the directory holding `repos.json`, or pass `--config <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.
+file is normalized first: BOM and CRLF stripped, repo paths and names folded, issue
+keys 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 |
 |---|---|
@@ -116,8 +122,11 @@ 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 |
-| `DELETED` | it is gone; `sync` will restore it |
+| `OUTDATED` | cairn has newer content for it — needs template hashes, wired in v2 |
+| `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.
 
 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
@@ -128,17 +137,20 @@ overwriting a hand edit is the destructive outcome.
 - `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.
+- `pathAliases` — local → canonical. When one repo names a stub `execute-tests.md`
+  where the others use `execute-test-plan.md`, aliasing folds them onto the cohort's
+  names instead of reporting one `MISSING` and one `STRANDED` for 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.
+  `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`.
 
 ## Layout
 
@@ -147,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
@@ -155,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 34 tests.
+No runtime dependencies. Node >= 18. `npm test` runs 46 tests.

package/lib/init.js

@@ -89,8 +89,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;

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.0",
+  "version": "0.3.0",
   "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" },