@shipwrights/source-jira 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Shipwrights contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,88 @@
+# @shipwrights/source-jira
+
+Jira backlog source adapter for [`@shipwrights/core`](https://github.com/shipwrights/core). Pulls issues via JQL, materialises them as epic files, writes status transitions and PR links back to Jira.
+
+## Install
+
+```bash
+npm install -D @shipwrights/core @shipwrights/source-jira
+# or
+pnpm add -D @shipwrights/core @shipwrights/source-jira
+```
+
+## Configure
+
+Generate a Jira API token at https://id.atlassian.com/manage-profile/security/api-tokens.
+
+Set env vars in your shell or `.env`:
+
+```bash
+export JIRA_EMAIL=you@example.com
+export JIRA_API_TOKEN=<your-token>
+```
+
+Reference them from `.shipwright.yml`:
+
+```yaml
+backlog:
+  source:
+    kind: jira
+    config:
+      host: myorg.atlassian.net
+      email_env: JIRA_EMAIL
+      token_env: JIRA_API_TOKEN
+      jql: 'project = SHOP AND status in ("Ready for Dev", "Refined") ORDER BY priority ASC'
+  state_dir: docs/backlog/epics
+```
+
+## What this adapter implements
+
+The `BacklogSource` contract from `@shipwrights/core`:
+
+| Method | Behaviour |
+|---|---|
+| `healthcheck()` | Calls `GET /myself` to validate auth |
+| `listAvailable()` | Runs the configured JQL (`POST /rest/api/3/search/jql`) with cursor pagination |
+| `pickNext()` | `listAvailable()` sorted by priority + key |
+| `materialize(item, dir)` | Renders the Jira issue's description (ADF) to markdown + writes an epic file with frontmatter |
+| `markStatus(id, status)` | Transitions the Jira issue (3 statuses) or posts a comment (middle states) |
+| `attachPR(id, prUrl)` | Posts a comment with the PR url |
+
+## Status mapping
+
+Most Shipwright lifecycle states are internal artefacts that don't have a useful Jira counterpart. The adapter only transitions the Jira issue for three states:
+
+| Shipwright status | Jira action (default) |
+|---|---|
+| `refined` | Transition to **Ready for Dev** |
+| `ready-for-human-review` | Transition to **In Review** |
+| `shipped` | Transition to **Done** |
+| anything else (`sliced`, `built`, `integrated`, `tested`, `reviewed`) | Post a comment, no transition |
+
+Override the mapping in `.shipwright.yml`:
+
+```yaml
+config:
+  status_mapping:
+    refined: "In Progress"
+    shipped: "Closed"
+```
+
+## Field mapping
+
+Standard fields (`summary`, `priority`, `status`, `labels`) are mapped by name. Story points and parent epic are custom fields — convention-detected by default, overridable:
+
+```yaml
+config:
+  field_mapping:
+    size: customfield_10016     # Story Points
+    parents: customfield_10014  # Epic Link
+```
+
+## Status
+
+v0.1.0 — Phase 1. Implements `healthcheck` + `listAvailable`. Materialise, transitions, and PR-link writes land in later phases.
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@shipwrights/source-jira",
+  "version": "0.1.0",
+  "description": "Jira backlog source adapter for @shipwrights/core. Pulls issues via JQL, materialises them as epic files, writes status transitions and PR links back to Jira.",
+  "type": "module",
+  "main": "./src/index.mjs",
+  "exports": {
+    ".": "./src/index.mjs"
+  },
+  "files": [
+    "src/",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test \"tests/**/*.test.mjs\"",
+    "lint": "echo 'no lint configured yet'",
+    "typecheck": "echo 'no typecheck configured yet'"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "keywords": [
+    "shipwrights",
+    "shipwrights-source",
+    "jira",
+    "backlog",
+    "orchestration",
+    "claude-code"
+  ],
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/shipwrights/source-jira.git"
+  },
+  "bugs": {
+    "url": "https://github.com/shipwrights/source-jira/issues"
+  },
+  "homepage": "https://github.com/shipwrights/source-jira#readme",
+  "peerDependencies": {
+    "@shipwrights/core": ">=0.1.3"
+  },
+  "peerDependenciesMeta": {
+    "@shipwrights/core": {
+      "optional": false
+    }
+  },
+  "devDependencies": {}
+}

package/src/client.mjs

@@ -0,0 +1,136 @@
+// Thin Jira Cloud REST API v3 client.
+//
+// Uses native fetch + Basic auth (email + API token). No external HTTP dep.
+// Exposes the few endpoints Phase 1 needs:
+//
+//   client.myself()                    -> GET /rest/api/3/myself
+//   client.searchJql({ jql, fields })  -> POST /rest/api/3/search/jql (paginates)
+//
+// Later phases extend this with:
+//   client.transitions(issueKey), client.transition(issueKey, transitionId)
+//   client.comment(issueKey, adf)
+//   client.issue(issueKey)
+
+const API_BASE = "/rest/api/3";
+
+class JiraClientError extends Error {
+  constructor(message, status, body) {
+    super(message);
+    this.name = "JiraClientError";
+    this.status = status;
+    this.body = body;
+  }
+}
+
+export function createClient({ host, email, token, fetch: fetchImpl = fetch } = {}) {
+  if (!host) throw new Error("Jira client: host is required (e.g. 'myorg.atlassian.net')");
+  if (!email) throw new Error("Jira client: email is required");
+  if (!token) throw new Error("Jira client: token is required (API token from id.atlassian.com)");
+
+  const baseUrl = `https://${host}${API_BASE}`;
+  const authHeader = `Basic ${Buffer.from(`${email}:${token}`).toString("base64")}`;
+
+  async function request(method, path, { body, query } = {}) {
+    const url = new URL(`${baseUrl}${path}`);
+    if (query) {
+      for (const [k, v] of Object.entries(query)) {
+        if (v !== undefined && v !== null) url.searchParams.set(k, String(v));
+      }
+    }
+    const response = await fetchImpl(url.toString(), {
+      method,
+      headers: {
+        Accept: "application/json",
+        Authorization: authHeader,
+        ...(body !== undefined ? { "Content-Type": "application/json" } : {}),
+      },
+      body: body !== undefined ? JSON.stringify(body) : undefined,
+    });
+
+    if (!response.ok) {
+      let errorBody = null;
+      try {
+        errorBody = await response.json();
+      } catch {
+        errorBody = await response.text().catch(() => null);
+      }
+      const message = errorBodySummary(errorBody) ?? response.statusText;
+      throw new JiraClientError(
+        `Jira ${method} ${path} failed: ${response.status} ${message}`,
+        response.status,
+        errorBody,
+      );
+    }
+
+    if (response.status === 204) return null;
+    return response.json();
+  }
+
+  return {
+    /** Confirm credentials are valid. Returns the authenticated user. */
+    myself() {
+      return request("GET", "/myself");
+    },
+
+    /**
+     * Paginate through JQL search results. Returns an async iterator yielding
+     * issues. Uses POST /search/jql with nextPageToken cursor pagination.
+     *
+     * @param {{ jql: string, fields?: string[], maxResults?: number, fieldsByKeys?: boolean }} opts
+     */
+    async *searchJql({ jql, fields, maxResults = 50, fieldsByKeys = false }) {
+      if (!jql) throw new Error("searchJql requires a `jql` string");
+      let nextPageToken;
+      while (true) {
+        const payload = {
+          jql,
+          maxResults,
+          fieldsByKeys,
+          ...(fields ? { fields } : {}),
+          ...(nextPageToken ? { nextPageToken } : {}),
+        };
+        const page = await request("POST", "/search/jql", { body: payload });
+        for (const issue of page.issues ?? []) {
+          yield issue;
+        }
+        if (page.isLast || !page.nextPageToken) break;
+        nextPageToken = page.nextPageToken;
+      }
+    },
+
+    /**
+     * Convenience wrapper: collect all paginated results into an array.
+     */
+    async searchJqlAll(opts) {
+      const out = [];
+      for await (const issue of this.searchJql(opts)) out.push(issue);
+      return out;
+    },
+
+    /**
+     * Low-level escape hatch. Useful for tests and for endpoints not yet
+     * added to this client.
+     */
+    request,
+  };
+}
+
+function errorBodySummary(body) {
+  if (!body) return null;
+  if (typeof body === "string") return body.slice(0, 200);
+  // Jira error shapes:
+  //   { errorMessages: ["..."], errors: { field: "..." } }
+  //   { message: "...", warningMessages: [...] }
+  if (Array.isArray(body.errorMessages) && body.errorMessages.length > 0) {
+    return body.errorMessages.join("; ");
+  }
+  if (body.errors && typeof body.errors === "object") {
+    return Object.entries(body.errors)
+      .map(([field, msg]) => `${field}: ${msg}`)
+      .join("; ");
+  }
+  if (body.message) return body.message;
+  return JSON.stringify(body).slice(0, 200);
+}
+
+export { JiraClientError };

package/src/index.mjs

@@ -0,0 +1,183 @@
+// @shipwrights/source-jira — entry point.
+//
+// Implements the BacklogSource interface from @shipwrights/core:
+//
+//   { healthcheck, listAvailable, pickNext, materialize, markStatus, attachPR }
+//
+// Phase 1 ships healthcheck + listAvailable + pickNext. The remaining three
+// land in Phases 2–4.
+
+import { createClient } from "./client.mjs";
+import { validateJql, fieldsForSearch } from "./jql.mjs";
+
+const PRIORITY_ORDER = { Highest: 0, High: 1, Medium: 2, Low: 3, Lowest: 4 };
+
+/**
+ * Resolve a config-declared env var to its value. Throws if missing.
+ */
+function readEnv(varName, role) {
+  const value = process.env[varName];
+  if (!value) {
+    throw new Error(
+      `@shipwrights/source-jira: env var ${varName} is required for ${role} but is not set`,
+    );
+  }
+  return value;
+}
+
+/**
+ * Map a Jira issue to a Shipwright BacklogItem. Phase 1 uses standard
+ * fields only — field_mapping for size / parents arrives in Phase 5.
+ */
+function toBacklogItem(issue, { idPrefix, fieldMapping }) {
+  const fields = issue.fields ?? {};
+  const id = issue.key; // SHOP-123
+  const sizeFieldKey = fieldMapping?.size;
+  const parentsFieldKey = fieldMapping?.parents;
+
+  const size = sizeFieldKey && fields[sizeFieldKey]
+    ? bucketSize(Number(fields[sizeFieldKey]))
+    : undefined;
+
+  const parents = parentsFieldKey && fields[parentsFieldKey]
+    ? [fields[parentsFieldKey]].flat().filter(Boolean)
+    : [];
+
+  return {
+    id,
+    title: fields.summary ?? `(no summary) ${id}`,
+    description: undefined, // ADF rendering lands in Phase 2 (materialize)
+    status: fields.status?.name ?? "unknown",
+    priority: fields.priority?.name,
+    size,
+    domain: undefined,
+    parents,
+    metadata: {
+      issueKey: issue.key,
+      issueId: issue.id,
+      jiraUrl: issue.self,
+      assignee: fields.assignee?.displayName,
+      reporter: fields.reporter?.displayName,
+      created: fields.created,
+      updated: fields.updated,
+      labels: fields.labels ?? [],
+      components: (fields.components ?? []).map((c) => c.name),
+    },
+  };
+}
+
+/**
+ * Map a numeric story-points value to Shipwright's coarse size bucket.
+ * Defaults follow common Fibonacci-style estimation.
+ */
+function bucketSize(points) {
+  if (!Number.isFinite(points)) return undefined;
+  if (points <= 2) return "small";
+  if (points <= 8) return "medium";
+  return "large";
+}
+
+function comparePriority(a, b) {
+  const ap = PRIORITY_ORDER[a.priority] ?? 99;
+  const bp = PRIORITY_ORDER[b.priority] ?? 99;
+  if (ap !== bp) return ap - bp;
+  return (a.id ?? "").localeCompare(b.id ?? "");
+}
+
+/**
+ * Factory called by @shipwrights/core's source-loader.
+ */
+export function createSource(rawConfig = {}) {
+  const {
+    host,
+    email_env = "JIRA_EMAIL",
+    token_env = "JIRA_API_TOKEN",
+    jql,
+    field_mapping = {},
+    id_prefix,
+    _client, // injected in tests
+  } = rawConfig;
+
+  if (!host) {
+    throw new Error("@shipwrights/source-jira: `host` is required (e.g. 'myorg.atlassian.net')");
+  }
+  if (!jql) {
+    throw new Error("@shipwrights/source-jira: `jql` is required");
+  }
+
+  // Validate early — surface bad JQL before any API call.
+  validateJql(jql);
+
+  const client = _client ?? createClient({
+    host,
+    email: readEnv(email_env, "Jira email"),
+    token: readEnv(token_env, "Jira API token"),
+  });
+
+  const fields = fieldsForSearch({ fieldMapping: field_mapping });
+
+  return {
+    /**
+     * Phase 1: confirm credentials by hitting /myself. Throws on failure.
+     */
+    async healthcheck() {
+      await client.myself();
+    },
+
+    /**
+     * Phase 1: paginate the configured JQL, map each issue to a BacklogItem.
+     * Optional filter narrows by status (Jira status name, not Shipwright
+     * status) — pass `statuses` to override the JQL's own status clause.
+     */
+    async listAvailable(filter = {}) {
+      let effectiveJql = jql;
+      if (Array.isArray(filter.statuses) && filter.statuses.length > 0) {
+        const escaped = filter.statuses.map((s) => `"${s.replace(/"/g, '\\"')}"`).join(", ");
+        effectiveJql = `(${jql}) AND status in (${escaped})`;
+      }
+      const issues = await client.searchJqlAll({
+        jql: effectiveJql,
+        fields,
+        maxResults: 50,
+      });
+      return issues.map((issue) =>
+        toBacklogItem(issue, { idPrefix: id_prefix, fieldMapping: field_mapping }),
+      );
+    },
+
+    /**
+     * Phase 1: pick the highest-priority item, then lowest key alphabetically
+     * for stable ordering. Doesn't yet honour `parents-shipped` blocking —
+     * that arrives once `materialize` can resolve Epic Link parents (Phase 2/5).
+     */
+    async pickNext(criteria = {}) {
+      const items = await this.listAvailable(criteria);
+      if (items.length === 0) return null;
+      items.sort(comparePriority);
+      return items[0];
+    },
+
+    /**
+     * Phases 2–4: not yet implemented. Each throws a clear error rather than
+     * silently no-oping, so consumers know they're on a Phase 1 release.
+     */
+    async materialize(_item, _targetDir) {
+      throw new Error(
+        "@shipwrights/source-jira: materialize() lands in Phase 2 (next release). Use listAvailable() / pickNext() for now and materialise epic files by hand.",
+      );
+    },
+    async markStatus(_itemId, _status) {
+      throw new Error(
+        "@shipwrights/source-jira: markStatus() lands in Phase 3 (next release).",
+      );
+    },
+    async attachPR(_itemId, _prUrl) {
+      throw new Error(
+        "@shipwrights/source-jira: attachPR() lands in Phase 4 (next release).",
+      );
+    },
+  };
+}
+
+// @shipwrights/core's source-loader accepts default export as the factory too.
+export default createSource;

package/src/jql.mjs

@@ -0,0 +1,71 @@
+// JQL helpers. Two responsibilities for now:
+//
+// 1. Light validation — surface obvious mistakes (empty string, mismatched
+//    quotes) before sending to Jira. Jira's 400 messages are useful but a
+//    cheap pre-check makes /shipwright:doctor output more actionable.
+//
+// 2. Field-list resolution — given the consumer's `field_mapping` config,
+//    produce the `fields` array we ask Jira to return so we don't pull the
+//    full issue payload (each issue is ~10kb of irrelevant data otherwise).
+
+const ALWAYS_REQUESTED_FIELDS = [
+  "summary",
+  "status",
+  "priority",
+  "issuetype",
+  "labels",
+  "components",
+  "assignee",
+  "reporter",
+  "created",
+  "updated",
+];
+
+/**
+ * Cheap structural validation. Throws on obvious errors. Returns the JQL
+ * unchanged on success.
+ */
+export function validateJql(jql) {
+  if (typeof jql !== "string") {
+    throw new Error("JQL must be a string");
+  }
+  const trimmed = jql.trim();
+  if (trimmed.length === 0) {
+    throw new Error("JQL is empty");
+  }
+  if (countUnescaped(trimmed, '"') % 2 !== 0) {
+    throw new Error(`JQL has unbalanced double quotes: ${trimmed}`);
+  }
+  if (countUnescaped(trimmed, "'") % 2 !== 0) {
+    throw new Error(`JQL has unbalanced single quotes: ${trimmed}`);
+  }
+  const opens = (trimmed.match(/\(/g) ?? []).length;
+  const closes = (trimmed.match(/\)/g) ?? []).length;
+  if (opens !== closes) {
+    throw new Error(`JQL has unbalanced parentheses (${opens} open, ${closes} close): ${trimmed}`);
+  }
+  return trimmed;
+}
+
+function countUnescaped(s, char) {
+  let count = 0;
+  for (let i = 0; i < s.length; i++) {
+    if (s[i] === char && s[i - 1] !== "\\") count++;
+  }
+  return count;
+}
+
+/**
+ * Compute the field list we request from Jira's search endpoint. Pulls only
+ * what the adapter needs, including any custom-field IDs from the consumer's
+ * field_mapping config.
+ */
+export function fieldsForSearch({ fieldMapping = {} } = {}) {
+  const fields = new Set(ALWAYS_REQUESTED_FIELDS);
+  // The mapping values may be `customfield_NNNNN` IDs or standard field
+  // names. Either way we ask for them.
+  for (const value of Object.values(fieldMapping)) {
+    if (typeof value === "string" && value.length > 0) fields.add(value);
+  }
+  return [...fields];
+}