@gr8ful/spf 0.1.4 → 0.1.6

package/dist/core/data_types.d.ts

@@ -356,27 +356,49 @@ export declare const ObservabilityConfigSchema: v.ObjectSchema<{
 }, undefined>;
 export type ObservabilityConfig = v.InferOutput<typeof ObservabilityConfigSchema>;
 /**
- * `spf watch`'s configuration. `provider` is a small enum today (just
- * `"github"`) by design — adding Jira/Linear later is a new provider
- * module (`core/issues/*_provider.ts`) implementing `IssueProvider` plus
- * one more enum entry here, not a rewrite of the poll loop.
+ * `spf watch`'s configuration. `issue_provider` (the tracker) and
+ * `code_host` (where PRs open) are independent enums, not one combined
+ * `provider` — a tracker and a code host are independent choices in
+ * practice (Jira issues against a Bitbucket repo, e.g.), and `watch.ts`'s
+ * poll loop is written against `IssueProvider`/`CodeHostProvider`
+ * separately (see `core/issues/provider.ts`) precisely so any combination
+ * is just config, never a rewrite of the loop. Adding a tracker or host
+ * later is a new module (`core/issues/*_provider.ts`) plus one more enum
+ * entry here.
  *
  * `repo` has no sensible default and is validated as required at `spf
  * watch` startup, not here — an empty string parses fine (this schema has
  * no opinion on whether watch is even configured), matching the same
  * "fails loudly before anything spawns, not eagerly at parse time" pattern
- * `quality:` already uses.
+ * `quality:` already uses. Its shape depends on `code_host`: "owner/name"
+ * for github, "workspace/repo_slug" for bitbucket.
  */
-export declare const WatchProviderSchema: v.PicklistSchema<["github"], undefined>;
-export type WatchProvider = v.InferOutput<typeof WatchProviderSchema>;
+export declare const WatchIssueProviderSchema: v.PicklistSchema<["github", "jira"], undefined>;
+export type WatchIssueProviderKind = v.InferOutput<typeof WatchIssueProviderSchema>;
+export declare const WatchCodeHostSchema: v.PicklistSchema<["github", "bitbucket"], undefined>;
+export type WatchCodeHostKind = v.InferOutput<typeof WatchCodeHostSchema>;
+/** Only consulted when `issue_provider: jira`. Auth is `JIRA_EMAIL` + `JIRA_API_TOKEN` env vars, checked at startup like `GITHUB_TOKEN`. */
+export declare const WatchJiraConfigSchema: v.ObjectSchema<{
+    readonly base_url: v.OptionalSchema<v.StringSchema<undefined>, "">;
+    readonly project_key: v.OptionalSchema<v.StringSchema<undefined>, "">;
+}, undefined>;
+export type WatchJiraConfig = v.InferOutput<typeof WatchJiraConfigSchema>;
 export declare const WatchConfigSchema: v.ObjectSchema<{
-    readonly provider: v.OptionalSchema<v.PicklistSchema<["github"], undefined>, "github">;
+    readonly issue_provider: v.OptionalSchema<v.PicklistSchema<["github", "jira"], undefined>, "github">;
+    readonly code_host: v.OptionalSchema<v.PicklistSchema<["github", "bitbucket"], undefined>, "github">;
     readonly repo: v.OptionalSchema<v.StringSchema<undefined>, "">;
     readonly label_prefix: v.OptionalSchema<v.StringSchema<undefined>, "spf">;
     readonly chain: v.OptionalSchema<v.StringSchema<undefined>, "plan-build-test">;
     readonly base_branch: v.OptionalSchema<v.StringSchema<undefined>, "main">;
     readonly poll_ms: v.OptionalSchema<v.NumberSchema<undefined>, 60000>;
     readonly concurrency: v.OptionalSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 1, undefined>]>, 2>;
+    readonly jira: v.OptionalSchema<v.ObjectSchema<{
+        readonly base_url: v.OptionalSchema<v.StringSchema<undefined>, "">;
+        readonly project_key: v.OptionalSchema<v.StringSchema<undefined>, "">;
+    }, undefined>, () => {
+        base_url: string;
+        project_key: string;
+    }>;
 }, undefined>;
 export type WatchConfig = v.InferOutput<typeof WatchConfigSchema>;
 export declare const SFConfigSchema: v.ObjectSchema<{
@@ -443,21 +465,34 @@ export declare const SFConfigSchema: v.ObjectSchema<{
         };
     }>;
     readonly watch: v.OptionalSchema<v.ObjectSchema<{
-        readonly provider: v.OptionalSchema<v.PicklistSchema<["github"], undefined>, "github">;
+        readonly issue_provider: v.OptionalSchema<v.PicklistSchema<["github", "jira"], undefined>, "github">;
+        readonly code_host: v.OptionalSchema<v.PicklistSchema<["github", "bitbucket"], undefined>, "github">;
         readonly repo: v.OptionalSchema<v.StringSchema<undefined>, "">;
         readonly label_prefix: v.OptionalSchema<v.StringSchema<undefined>, "spf">;
         readonly chain: v.OptionalSchema<v.StringSchema<undefined>, "plan-build-test">;
         readonly base_branch: v.OptionalSchema<v.StringSchema<undefined>, "main">;
         readonly poll_ms: v.OptionalSchema<v.NumberSchema<undefined>, 60000>;
         readonly concurrency: v.OptionalSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 1, undefined>]>, 2>;
+        readonly jira: v.OptionalSchema<v.ObjectSchema<{
+            readonly base_url: v.OptionalSchema<v.StringSchema<undefined>, "">;
+            readonly project_key: v.OptionalSchema<v.StringSchema<undefined>, "">;
+        }, undefined>, () => {
+            base_url: string;
+            project_key: string;
+        }>;
     }, undefined>, () => {
-        provider: "github";
+        issue_provider: "github" | "jira";
+        code_host: "bitbucket" | "github";
         repo: string;
         label_prefix: string;
         chain: string;
         base_branch: string;
         poll_ms: number;
         concurrency: number;
+        jira: {
+            base_url: string;
+            project_key: string;
+        };
     }>;
 }, undefined>;
 export type SFConfig = v.InferOutput<typeof SFConfigSchema>;

package/dist/core/data_types.js

@@ -275,26 +275,40 @@ export const ObservabilityConfigSchema = v.object({
     poll_ms: v.optional(v.number(), 500),
 });
 /**
- * `spf watch`'s configuration. `provider` is a small enum today (just
- * `"github"`) by design — adding Jira/Linear later is a new provider
- * module (`core/issues/*_provider.ts`) implementing `IssueProvider` plus
- * one more enum entry here, not a rewrite of the poll loop.
+ * `spf watch`'s configuration. `issue_provider` (the tracker) and
+ * `code_host` (where PRs open) are independent enums, not one combined
+ * `provider` — a tracker and a code host are independent choices in
+ * practice (Jira issues against a Bitbucket repo, e.g.), and `watch.ts`'s
+ * poll loop is written against `IssueProvider`/`CodeHostProvider`
+ * separately (see `core/issues/provider.ts`) precisely so any combination
+ * is just config, never a rewrite of the loop. Adding a tracker or host
+ * later is a new module (`core/issues/*_provider.ts`) plus one more enum
+ * entry here.
  *
  * `repo` has no sensible default and is validated as required at `spf
  * watch` startup, not here — an empty string parses fine (this schema has
  * no opinion on whether watch is even configured), matching the same
  * "fails loudly before anything spawns, not eagerly at parse time" pattern
- * `quality:` already uses.
+ * `quality:` already uses. Its shape depends on `code_host`: "owner/name"
+ * for github, "workspace/repo_slug" for bitbucket.
  */
-export const WatchProviderSchema = v.picklist(["github"]);
+export const WatchIssueProviderSchema = v.picklist(["github", "jira"]);
+export const WatchCodeHostSchema = v.picklist(["github", "bitbucket"]);
+/** Only consulted when `issue_provider: jira`. Auth is `JIRA_EMAIL` + `JIRA_API_TOKEN` env vars, checked at startup like `GITHUB_TOKEN`. */
+export const WatchJiraConfigSchema = v.object({
+    base_url: v.optional(v.string(), ""), // e.g. "https://your-domain.atlassian.net"
+    project_key: v.optional(v.string(), ""), // e.g. "PROJ"
+});
 export const WatchConfigSchema = v.object({
-    provider: v.optional(WatchProviderSchema, "github"),
-    repo: v.optional(v.string(), ""), // "owner/name"
+    issue_provider: v.optional(WatchIssueProviderSchema, "github"),
+    code_host: v.optional(WatchCodeHostSchema, "github"),
+    repo: v.optional(v.string(), ""),
     label_prefix: v.optional(v.string(), "spf"),
     chain: v.optional(v.string(), "plan-build-test"),
     base_branch: v.optional(v.string(), "main"),
     poll_ms: v.optional(v.number(), 60_000),
     concurrency: v.optional(v.pipe(v.number(), v.integer(), v.minValue(1)), 2),
+    jira: v.optional(WatchJiraConfigSchema, () => v.parse(WatchJiraConfigSchema, {})),
 });
 export const SFConfigSchema = v.object({
     defaults: v.optional(ConfigDefaultsSchema, () => v.parse(ConfigDefaultsSchema, {})),

package/dist/core/issues/bitbucket_provider.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Bitbucket Cloud REST API v2.0 implementation of `CodeHostProvider` —
+ * `spf watch`'s PR seam, not its tracker seam (see `provider.ts`'s module
+ * comment): this class never touches issues/labels, so it's paired with an
+ * `IssueProvider` (`github_provider.ts` or `jira_provider.ts`) at the CLI
+ * layer.
+ *
+ * Auth is HTTP Basic with an Atlassian account email + API token
+ * (`BITBUCKET_EMAIL` / `BITBUCKET_API_TOKEN`) — verified directly against
+ * Atlassian's current docs before writing this, not assumed from training
+ * data: Bitbucket Cloud app passwords are being fully removed (brownout
+ * window closes July 28, 2026), so this project only supports the
+ * replacement — API tokens, same auth shape as `jira_provider.ts`.
+ *
+ * `repo` is `"workspace/repo_slug"` (Bitbucket's own two-part identifier),
+ * the same config field GitHub uses for `"owner/name"` — the shape just
+ * means something different per `code_host`.
+ */
+import type { CodeHostProvider, PrRef, PrStatus } from "./provider.ts";
+export declare class BitbucketProvider implements CodeHostProvider {
+    private readonly email;
+    private readonly apiToken;
+    private readonly workspace;
+    private readonly repoSlug;
+    constructor(repo: string, // "workspace/repo_slug"
+    email: string, apiToken: string);
+    private bb;
+    openPr(opts: {
+        branch: string;
+        title: string;
+        body: string;
+        base: string;
+    }): Promise<PrRef>;
+    prStatus(pr: PrRef): Promise<PrStatus>;
+}

package/dist/core/issues/bitbucket_provider.js

@@ -0,0 +1,70 @@
+const API = "https://api.bitbucket.org/2.0";
+export class BitbucketProvider {
+    email;
+    apiToken;
+    workspace;
+    repoSlug;
+    constructor(repo, // "workspace/repo_slug"
+    email, apiToken) {
+        this.email = email;
+        this.apiToken = apiToken;
+        const [workspace, repoSlug] = repo.split("/");
+        if (!workspace || !repoSlug)
+            throw new Error(`watch.repo ${JSON.stringify(repo)} is not "workspace/repo_slug"`);
+        this.workspace = workspace;
+        this.repoSlug = repoSlug;
+    }
+    async bb(path, init) {
+        const response = await fetch(`${API}${path}`, {
+            ...init,
+            headers: {
+                Authorization: `Basic ${Buffer.from(`${this.email}:${this.apiToken}`).toString("base64")}`,
+                Accept: "application/json",
+                ...(init?.body ? { "Content-Type": "application/json" } : {}),
+                ...init?.headers,
+            },
+        });
+        if (!response.ok) {
+            const detail = await response.text().catch(() => "");
+            throw new Error(`Bitbucket ${init?.method ?? "GET"} ${path} -> ${response.status}: ${detail.slice(0, 500)}`);
+        }
+        if (response.status === 204)
+            return undefined;
+        return (await response.json());
+    }
+    async openPr(opts) {
+        const pr = await this.bb(`/repositories/${this.workspace}/${this.repoSlug}/pullrequests`, {
+            method: "POST",
+            body: JSON.stringify({
+                title: opts.title,
+                description: opts.body,
+                source: { branch: { name: opts.branch } },
+                destination: { branch: { name: opts.base } },
+            }),
+        });
+        return { number: pr.id, branch: opts.branch, url: pr.links.html.href };
+    }
+    async prStatus(pr) {
+        const detail = await this.bb(`/repositories/${this.workspace}/${this.repoSlug}/pullrequests/${pr.number}`);
+        let ciStatus = "pending";
+        try {
+            const statuses = await this.bb(`/repositories/${this.workspace}/${this.repoSlug}/commit/${detail.source.commit.hash}/statuses?pagelen=100`);
+            if (statuses.values.length === 0) {
+                ciStatus = "pending"; // no checks configured — never blocks a lean v1's own polling
+            }
+            else if (statuses.values.some((s) => s.state === "INPROGRESS")) {
+                ciStatus = "pending";
+            }
+            else if (statuses.values.some((s) => s.state === "FAILED" || s.state === "STOPPED")) {
+                ciStatus = "failure";
+            }
+            else {
+                ciStatus = "success";
+            }
+        }
+        catch {
+            ciStatus = "pending"; // status lookup failing shouldn't block merge/close detection
+        }
+        return { merged: detail.state === "MERGED", state: detail.state === "OPEN" ? "open" : "closed", ciStatus };
+    }
+}

package/dist/core/issues/github_provider.d.ts

@@ -1,7 +1,8 @@
 /**
- * GitHub REST implementation of `IssueProvider`, via Node 22's native
- * `fetch()` — deliberately not `octokit`: the full `octokit` meta-package
- * resolves to ~82MB of installed dependencies (`@octokit/app`,
+ * GitHub REST implementation of both `IssueProvider` and `CodeHostProvider`
+ * — one class, since GitHub natively is both an issue tracker and a code
+ * host — via Node 22's native `fetch()`: deliberately not `octokit`, whose
+ * full meta-package resolves to ~82MB of installed dependencies (`@octokit/app`,
  * `oauth-app`, `webhooks`, ...) for what `spf watch` actually needs, which
  * is six REST calls. `spf`'s own package stays dependency-free either way.
  *
@@ -12,8 +13,8 @@
  * makes (a repo with >100 open `<prefix>:ready` issues at once is not this
  * version's problem to solve).
  */
-import type { EnsureLabelsResult, Issue, IssueProvider, PrRef, PrStatus, WatchMarker, WatchState } from "./provider.ts";
-export declare class GitHubProvider implements IssueProvider {
+import type { CodeHostProvider, EnsureLabelsResult, Issue, IssueProvider, PrRef, PrStatus, WatchMarker, WatchState } from "./provider.ts";
+export declare class GitHubProvider implements IssueProvider, CodeHostProvider {
     private readonly repo;
     private readonly labelPrefix;
     private readonly token;
@@ -39,7 +40,7 @@ export declare class GitHubProvider implements IssueProvider {
     claim(issue: Issue): Promise<boolean>;
     transition(issue: Issue, to: WatchState, detail?: string): Promise<void>;
     comment(issue: Issue, body: string): Promise<void>;
-    openPr(issue: Issue, opts: {
+    openPr(opts: {
         branch: string;
         title: string;
         body: string;

package/dist/core/issues/github_provider.js

@@ -87,7 +87,7 @@ export class GitHubProvider {
     }
     toIssue(raw) {
         return {
-            number: raw.number,
+            id: String(raw.number),
             title: raw.title,
             body: raw.body ?? "",
             labels: raw.labels.map((l) => (typeof l === "string" ? l : l.name)),
@@ -104,19 +104,19 @@ export class GitHubProvider {
         return this.listByLabel(this.label(state), opts?.includeAll ? "all" : "open");
     }
     async claim(issue) {
-        await this.gh(`/repos/${this.repo}/issues/${issue.number}/labels/${encodeURIComponent(this.label("ready"))}`, {
+        await this.gh(`/repos/${this.repo}/issues/${issue.id}/labels/${encodeURIComponent(this.label("ready"))}`, {
             method: "DELETE",
         }).catch(() => undefined); // already gone is fine
-        await this.gh(`/repos/${this.repo}/issues/${issue.number}/labels`, {
+        await this.gh(`/repos/${this.repo}/issues/${issue.id}/labels`, {
             method: "POST",
             body: JSON.stringify({ labels: [this.label("working")] }),
         });
-        const fresh = await this.gh(`/repos/${this.repo}/issues/${issue.number}`);
+        const fresh = await this.gh(`/repos/${this.repo}/issues/${issue.id}`);
         const labels = this.toIssue(fresh).labels;
         const claimed = labels.includes(this.label("working")) && !labels.includes(this.label("ready"));
         if (!claimed) {
             // Lost the race (or something else relabeled it) — put ready back so it's not stuck.
-            await this.gh(`/repos/${this.repo}/issues/${issue.number}/labels`, {
+            await this.gh(`/repos/${this.repo}/issues/${issue.id}/labels`, {
                 method: "POST",
                 body: JSON.stringify({ labels: [this.label("ready")] }),
             }).catch(() => undefined);
@@ -127,10 +127,10 @@ export class GitHubProvider {
         for (const state of STATES) {
             const label = this.label(state);
             if (issue.labels.includes(label)) {
-                await this.gh(`/repos/${this.repo}/issues/${issue.number}/labels/${encodeURIComponent(label)}`, { method: "DELETE" }).catch(() => undefined);
+                await this.gh(`/repos/${this.repo}/issues/${issue.id}/labels/${encodeURIComponent(label)}`, { method: "DELETE" }).catch(() => undefined);
             }
         }
-        await this.gh(`/repos/${this.repo}/issues/${issue.number}/labels`, {
+        await this.gh(`/repos/${this.repo}/issues/${issue.id}/labels`, {
             method: "POST",
             body: JSON.stringify({ labels: [this.label(to)] }),
         });
@@ -138,20 +138,15 @@ export class GitHubProvider {
             await this.comment(issue, detail);
     }
     async comment(issue, body) {
-        await this.gh(`/repos/${this.repo}/issues/${issue.number}/comments`, {
+        await this.gh(`/repos/${this.repo}/issues/${issue.id}/comments`, {
             method: "POST",
             body: JSON.stringify({ body }),
         });
     }
-    async openPr(issue, opts) {
-        // Belt-and-suspenders: ensure the PR body closes the issue even if the
-        // caller's body forgot to say so — this is how `finishReviews`-style
-        // merge polling knows an issue's work landed at all.
-        const closesTag = `Closes #${issue.number}`;
-        const body = opts.body.includes(closesTag) ? opts.body : `${opts.body}\n\n${closesTag}`;
+    async openPr(opts) {
         const pr = await this.gh(`/repos/${this.repo}/pulls`, {
             method: "POST",
-            body: JSON.stringify({ title: opts.title, body, head: opts.branch, base: opts.base }),
+            body: JSON.stringify({ title: opts.title, body: opts.body, head: opts.branch, base: opts.base }),
         });
         return { number: pr.number, branch: opts.branch, url: pr.html_url };
     }
@@ -178,8 +173,8 @@ export class GitHubProvider {
         }
         return { merged: detail.merged, state: detail.state, ciStatus };
     }
-    async findMarkerComment(issueNumber) {
-        const comments = await this.gh(`/repos/${this.repo}/issues/${issueNumber}/comments?per_page=100`);
+    async findMarkerComment(issueId) {
+        const comments = await this.gh(`/repos/${this.repo}/issues/${issueId}/comments?per_page=100`);
         let found = null;
         for (const c of comments) {
             const match = MARKER_RE.exec(c.body || "");
@@ -195,17 +190,17 @@ export class GitHubProvider {
         return found;
     }
     async readMarker(issue) {
-        const found = await this.findMarkerComment(issue.number);
+        const found = await this.findMarkerComment(issue.id);
         return found?.marker ?? null;
     }
     async writeMarker(issue, marker) {
         const body = `<!-- spf-watch: ${JSON.stringify(marker)} -->`;
-        const existing = await this.findMarkerComment(issue.number);
+        const existing = await this.findMarkerComment(issue.id);
         if (existing) {
             await this.gh(`/repos/${this.repo}/issues/comments/${existing.id}`, { method: "PATCH", body: JSON.stringify({ body }) });
         }
         else {
-            await this.gh(`/repos/${this.repo}/issues/${issue.number}/comments`, { method: "POST", body: JSON.stringify({ body }) });
+            await this.gh(`/repos/${this.repo}/issues/${issue.id}/comments`, { method: "POST", body: JSON.stringify({ body }) });
         }
     }
 }

package/dist/core/issues/jira_provider.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Jira Cloud REST API v3 implementation of `IssueProvider` — `spf watch`'s
+ * tracker seam, not its PR seam (see `provider.ts`'s module comment): this
+ * class never opens a PR, so it's paired with a `CodeHostProvider`
+ * (`github_provider.ts` or `bitbucket_provider.ts`) at the CLI layer.
+ *
+ * Auth is HTTP Basic with an Atlassian account email + API token
+ * (`JIRA_EMAIL` / `JIRA_API_TOKEN`), base64-encoded — verified against
+ * developer.atlassian.com's current auth docs, not assumed.
+ *
+ * Two API-v3 specifics that would otherwise silently break this:
+ *  - `/rest/api/3/search` (GET, JQL as a query param) was fully removed
+ *    from Jira Cloud in October 2025. The only working search endpoint
+ *    now is `/rest/api/3/search/jql`.
+ *  - Comment/description bodies in API v3 are Atlassian Document Format
+ *    (ADF) JSON, not plain strings — `{"body": "text"}` is rejected
+ *    outright. `toAdf`/`adfToText` are the minimal round-trip this needs:
+ *    one paragraph of plain text, nothing richer.
+ *
+ * State is modeled as Jira labels (`<prefix>:ready`, etc.), mirroring
+ * `github_provider.ts` exactly, rather than native workflow status
+ * transitions — the latter would need per-project transition-id mapping
+ * (workflows vary by project/scheme in Jira), while labels work
+ * identically everywhere with zero per-project setup. One caveat, verified
+ * against Atlassian's own docs: colons ARE a legal label character and JQL
+ * matches on them fine, they just don't show up in Jira's label
+ * autocomplete UI — cosmetic only, not a functional issue.
+ *
+ * `ensureLabels()` is a no-op that reports the labels this run will use:
+ * Jira labels are freeform strings with no color/description registry to
+ * seed, unlike GitHub's.
+ */
+import type { EnsureLabelsResult, Issue, IssueProvider, WatchMarker, WatchState } from "./provider.ts";
+export declare class JiraProvider implements IssueProvider {
+    private readonly baseUrl;
+    private readonly projectKey;
+    private readonly labelPrefix;
+    private readonly email;
+    private readonly apiToken;
+    constructor(baseUrl: string, // e.g. "https://your-domain.atlassian.net", no trailing slash
+    projectKey: string, labelPrefix: string, email: string, apiToken: string);
+    private authHeader;
+    private jira;
+    private label;
+    /** Jira labels are freeform strings, not a seedable registry — report what's used, create nothing. */
+    ensureLabels(): Promise<EnsureLabelsResult>;
+    private toIssue;
+    private searchByLabel;
+    listEligible(): Promise<Issue[]>;
+    /**
+     * `opts.includeAll` is ignored: nothing but this provider's own
+     * `transition()` ever changes an issue's labels or resolution here, so
+     * there's no side channel (like GitHub's `Closes #n` auto-close) that
+     * could make a `review`-labeled issue vanish from an unfiltered query.
+     */
+    listInState(state: WatchState): Promise<Issue[]>;
+    claim(issue: Issue): Promise<boolean>;
+    transition(issue: Issue, to: WatchState, detail?: string): Promise<void>;
+    comment(issue: Issue, body: string): Promise<void>;
+    private findMarkerComment;
+    readMarker(issue: Issue): Promise<WatchMarker | null>;
+    writeMarker(issue: Issue, marker: WatchMarker): Promise<void>;
+}

package/dist/core/issues/jira_provider.js

@@ -0,0 +1,145 @@
+const STATES = ["ready", "working", "review", "done", "blocked"];
+const MARKER_RE = /\[spf-watch-marker\]\s*(\{.*?\})/s;
+function toAdf(text) {
+    return {
+        type: "doc",
+        version: 1,
+        content: [{ type: "paragraph", content: [{ type: "text", text }] }],
+    };
+}
+/** Walks an ADF document's `text` nodes and joins them — the minimal inverse of `toAdf`, not a full ADF renderer. */
+function adfToText(adf) {
+    if (!adf || typeof adf !== "object")
+        return "";
+    const node = adf;
+    if (node.type === "text" && typeof node.text === "string")
+        return node.text;
+    if (Array.isArray(node.content))
+        return node.content.map(adfToText).join("");
+    return "";
+}
+export class JiraProvider {
+    baseUrl;
+    projectKey;
+    labelPrefix;
+    email;
+    apiToken;
+    constructor(baseUrl, // e.g. "https://your-domain.atlassian.net", no trailing slash
+    projectKey, labelPrefix, email, apiToken) {
+        this.baseUrl = baseUrl;
+        this.projectKey = projectKey;
+        this.labelPrefix = labelPrefix;
+        this.email = email;
+        this.apiToken = apiToken;
+    }
+    authHeader() {
+        return `Basic ${Buffer.from(`${this.email}:${this.apiToken}`).toString("base64")}`;
+    }
+    async jira(path, init) {
+        const response = await fetch(`${this.baseUrl}${path}`, {
+            ...init,
+            headers: {
+                Authorization: this.authHeader(),
+                Accept: "application/json",
+                ...(init?.body ? { "Content-Type": "application/json" } : {}),
+                ...init?.headers,
+            },
+        });
+        if (!response.ok) {
+            const detail = await response.text().catch(() => "");
+            throw new Error(`Jira ${init?.method ?? "GET"} ${path} -> ${response.status}: ${detail.slice(0, 500)}`);
+        }
+        if (response.status === 204)
+            return undefined;
+        return (await response.json());
+    }
+    label(state) {
+        return `${this.labelPrefix}:${state}`;
+    }
+    /** Jira labels are freeform strings, not a seedable registry — report what's used, create nothing. */
+    async ensureLabels() {
+        return { created: [], updated: [], unchanged: STATES.map((s) => this.label(s)) };
+    }
+    toIssue(raw) {
+        return {
+            id: raw.key,
+            title: raw.fields.summary,
+            body: raw.fields.description ? adfToText(raw.fields.description) : "",
+            labels: raw.fields.labels,
+        };
+    }
+    async searchByLabel(label) {
+        const jql = `project = ${JSON.stringify(this.projectKey)} AND labels = ${JSON.stringify(label)}`;
+        const result = await this.jira(`/rest/api/3/search/jql?jql=${encodeURIComponent(jql)}&maxResults=100&fields=summary,description,labels`);
+        return result.issues.map((i) => this.toIssue(i));
+    }
+    async listEligible() {
+        return this.searchByLabel(this.label("ready"));
+    }
+    /**
+     * `opts.includeAll` is ignored: nothing but this provider's own
+     * `transition()` ever changes an issue's labels or resolution here, so
+     * there's no side channel (like GitHub's `Closes #n` auto-close) that
+     * could make a `review`-labeled issue vanish from an unfiltered query.
+     */
+    async listInState(state) {
+        return this.searchByLabel(this.label(state));
+    }
+    async claim(issue) {
+        const next = issue.labels.filter((l) => l !== this.label("ready"));
+        next.push(this.label("working"));
+        await this.jira(`/rest/api/3/issue/${issue.id}`, { method: "PUT", body: JSON.stringify({ fields: { labels: next } }) });
+        const fresh = await this.jira(`/rest/api/3/issue/${issue.id}?fields=summary,description,labels`);
+        const labels = fresh.fields.labels;
+        const claimed = labels.includes(this.label("working")) && !labels.includes(this.label("ready"));
+        if (!claimed) {
+            const revert = labels.filter((l) => l !== this.label("working"));
+            revert.push(this.label("ready"));
+            await this.jira(`/rest/api/3/issue/${issue.id}`, { method: "PUT", body: JSON.stringify({ fields: { labels: revert } }) }).catch(() => undefined);
+        }
+        return claimed;
+    }
+    async transition(issue, to, detail) {
+        const next = issue.labels.filter((l) => !STATES.some((s) => this.label(s) === l));
+        next.push(this.label(to));
+        await this.jira(`/rest/api/3/issue/${issue.id}`, { method: "PUT", body: JSON.stringify({ fields: { labels: next } }) });
+        if (detail)
+            await this.comment(issue, detail);
+    }
+    async comment(issue, body) {
+        await this.jira(`/rest/api/3/issue/${issue.id}/comment`, { method: "POST", body: JSON.stringify({ body: toAdf(body) }) });
+    }
+    async findMarkerComment(issueId) {
+        const result = await this.jira(`/rest/api/3/issue/${issueId}/comment?maxResults=100`);
+        let found = null;
+        for (const c of result.comments) {
+            const match = MARKER_RE.exec(adfToText(c.body));
+            if (!match)
+                continue;
+            try {
+                found = { id: c.id, marker: JSON.parse(match[1]) };
+            }
+            catch {
+                // malformed marker JSON — tolerate it and keep looking, like github_provider.ts does
+            }
+        }
+        return found;
+    }
+    async readMarker(issue) {
+        const found = await this.findMarkerComment(issue.id);
+        return found?.marker ?? null;
+    }
+    async writeMarker(issue, marker) {
+        // Unlike GitHub's HTML-comment trick, Jira's ADF has no way to actually
+        // hide this from a viewer — it's a plainly visible comment, just one
+        // that starts with a recognizable, regex-matchable tag.
+        const body = toAdf(`[spf-watch-marker] ${JSON.stringify(marker)}`);
+        const existing = await this.findMarkerComment(issue.id);
+        if (existing) {
+            await this.jira(`/rest/api/3/issue/${issue.id}/comment/${existing.id}`, { method: "PUT", body: JSON.stringify({ body }) });
+        }
+        else {
+            await this.jira(`/rest/api/3/issue/${issue.id}/comment`, { method: "POST", body: JSON.stringify({ body }) });
+        }
+    }
+}