@gr8ful/spf 0.5.1 → 0.7.0

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

@@ -10,12 +10,16 @@
  *
  * Auth is a classic PAT via `GITHUB_TOKEN` (`repo` scope), read once at
  * construction — matching the reference implementation's pattern and this
- * project's existing env-var-for-credentials philosophy. No pagination
- * beyond one page of 100: fine for the label-scoped queries a lean v1
- * makes (a repo with >100 open `<prefix>:ready` issues at once is not this
- * version's problem to solve).
+ * project's existing env-var-for-credentials philosophy. `listByLabel`
+ * paginates up to `MAX_LIST_PAGES` (500 issues per label query) — no longer
+ * "not this version's problem to solve," now that priority ordering makes a
+ * truncated first page a correctness bug (an old, high-priority issue past
+ * page 1 would silently lose to a new low-priority one), not just a missed
+ * issue. A repo past even that cap gets a loud warning, never a silent
+ * truncation — see `listByLabel`'s own doc comment.
  */
-import type { CodeHostProvider, EnsureLabelsResult, Issue, IssueAuthoringProvider, IssueProvider, PrRef, PrStatus, WatchMarker, WatchState } from "./provider.ts";
+import type { CodeHostProvider, EnsureLabelsResult, Issue, IssueAuthoringProvider, IssueComment, IssueProvider, PrRef, PrStatus, WatchMarker, WatchState } from "./provider.ts";
+import type { RefinedIssue } from "../data_types.ts";
 /** The refine lane's leaf/container taxonomy — see `data_types.ts`'s `RefinedIssueSchema.kind`. Not a `WatchState`: these never appear on the left of a `transition()` call, so `transition()` never strips them. */
 export declare const ISSUE_KINDS: readonly ["epic", "feature", "story", "bug", "task"];
 export type IssueKind = (typeof ISSUE_KINDS)[number];
@@ -28,6 +32,8 @@ export declare class GitHubProvider implements IssueProvider, CodeHostProvider,
     private gh;
     private label;
     private typeLabel;
+    /** Mirrors `core/refine.ts`'s own module-level `priorityLabel()` — that one stays provider-agnostic (a plain string, no `this`); this one is `ensureLabels()`'s seeding half. */
+    private priorityLabel;
     /** `null` on a real 404 (label doesn't exist yet) — any other non-2xx still throws, same as `gh()`. */
     private getLabel;
     /**
@@ -40,11 +46,32 @@ export declare class GitHubProvider implements IssueProvider, CodeHostProvider,
     private ensureOneLabel;
     ensureLabels(): Promise<EnsureLabelsResult>;
     private toIssue;
+    /**
+     * `sort=created&direction=asc` is stated, not inherited: without it,
+     * GitHub's own default (`created`, `desc` — newest first) is what
+     * `claimNewWork` used to walk, silently, which is why a >100-issue ready
+     * backlog used to be a real risk before pagination existed at all.
+     * Oldest-first is also `orderEligible`'s own final tiebreaker (`watch.ts`),
+     * so this method's order and that function's are the same order absent a
+     * priority/affinity difference — no redundant client-side re-sort needed
+     * for the plain case.
+     *
+     * Paginates up to `MAX_LIST_PAGES` (500 issues) — no longer "this
+     * version's problem to solve": a client-side priority sort over a
+     * truncated first page would silently misorder or hide real work, which is
+     * worse than the old unordered-100-issues behavior it replaces. A repo
+     * that still exceeds the cap gets a loud, named warning rather than a
+     * silent truncation.
+     */
     private listByLabel;
     listEligible(): Promise<Issue[]>;
     listInState(state: WatchState, opts?: {
         includeAll?: boolean;
     }): Promise<Issue[]>;
+    /** `null` on a real 404 — deleted, or (state defaults to open in a plain fetch) an issue GitHub itself considers gone. Any other non-2xx still throws, same as `gh()`. */
+    getIssue(id: string): Promise<Issue | null>;
+    /** `GET .../sub_issues` — the read-back half of `linkChild`; what makes container roll-up possible (`rollUp` in `watch.ts`). Closed children ARE returned (no `state` filter) — roll-up needs to see a `blocked` child too, to correctly NOT finish the container. */
+    listChildren(parent: Issue): Promise<Issue[]>;
     claim(issue: Issue, opts?: {
         from?: WatchState;
         to?: WatchState;
@@ -58,11 +85,18 @@ export declare class GitHubProvider implements IssueProvider, CodeHostProvider,
         base: string;
     }): Promise<PrRef>;
     prStatus(pr: PrRef): Promise<PrStatus>;
-    /** `IssueAuthoringProvider` — the refine lane's own need (see `provider.ts`'s module doc). */
+    /**
+     * `IssueAuthoringProvider` — the refine lane's own need (see `provider.ts`'s
+     * module doc). `input.kind` is unused here: GitHub has no native
+     * issue-type field the way Jira does, and `input.labels` already carries
+     * `<prefix>:type:<kind>` for GitHub's own bookkeeping — the parameter
+     * exists on the shared interface for `JiraProvider`'s sake.
+     */
     createIssue(input: {
         title: string;
         body: string;
         labels: string[];
+        kind: RefinedIssue["kind"];
     }): Promise<Issue>;
     /**
      * `POST /repos/{o}/{r}/issues/{parent_number}/sub_issues` — GitHub's
@@ -73,7 +107,13 @@ export declare class GitHubProvider implements IssueProvider, CodeHostProvider,
      * 100 sub-issues per parent, 8 levels of nesting.
      */
     linkChild(parent: Issue, child: Issue): Promise<void>;
+    /** The single fetch every comment-reading method (`findMarkerComment`, `listComments`) builds on. */
+    private fetchComments;
     private findMarkerComment;
     readMarker(issue: Issue): Promise<WatchMarker | null>;
     writeMarker(issue: Issue, marker: WatchMarker): Promise<void>;
+    /** Oldest-first (GitHub's own comment order), the hidden marker comment filtered out. */
+    listComments(issue: Issue): Promise<IssueComment[]>;
+    /** `state_reason: "completed"` — the refine lane's own reason for closing a spec once it's fully decomposed; see `finishSpec` in `watch.ts`. */
+    closeIssue(issue: Issue): Promise<void>;
 }

package/dist/core/issues/github_provider.js

@@ -1,6 +1,20 @@
 const API = "https://api.github.com";
-const STATES = ["ready", "working", "review", "done", "blocked", "spec-ready", "refining", "refined"];
+const STATES = [
+    "ready",
+    "working",
+    "review",
+    "done",
+    "blocked",
+    "spec-ready",
+    "refining",
+    "refined",
+    "needs-feedback",
+    "continue-refinement",
+    "spec-in-progress",
+];
 const MARKER_RE = /<!--\s*spf-watch:\s*(\{.*?\})\s*-->/s;
+/** `listByLabel`'s pagination bound — see its own doc comment. */
+const MAX_LIST_PAGES = 5;
 /** The refine lane's leaf/container taxonomy — see `data_types.ts`'s `RefinedIssueSchema.kind`. Not a `WatchState`: these never appear on the left of a `transition()` call, so `transition()` never strips them. */
 export const ISSUE_KINDS = ["epic", "feature", "story", "bug", "task"];
 // GitHub label colors are 6 hex digits, no leading '#'.
@@ -13,6 +27,9 @@ const LABEL_META = {
     "spec-ready": { color: "0e8a16", description: "spf watch's refine lane will claim this spec on its next poll" },
     refining: { color: "fbca04", description: "spf watch has claimed this spec and is decomposing it into issues" },
     refined: { color: "c2e0c6", description: "generated by spf watch's refine lane — promote to spf:ready when it's worth building" },
+    "needs-feedback": { color: "d93f0b", description: "spf's refiner needs a human answer before it can finish decomposing this spec" },
+    "continue-refinement": { color: "0e8a16", description: "add this once you've answered — spf will resume refining from where it left off" },
+    "spec-in-progress": { color: "1d76db", description: "decomposed and published — waiting on every generated issue to reach spf:done" },
 };
 const TYPE_LABEL_META = {
     epic: { color: "5319e7", description: "a container generated by spf watch's refine lane — not directly workable" },
@@ -21,6 +38,24 @@ const TYPE_LABEL_META = {
     bug: { color: "e99695", description: "a leaf generated by spf watch's refine lane — vertical-slice, independently workable" },
     task: { color: "d4c5f9", description: "a leaf generated by spf watch's refine lane — vertical-slice, independently workable" },
 };
+/**
+ * What `claimNewWork` (`watch.ts`) schedules by — see `RefinedPrioritySchema`
+ * in `data_types.ts`. Deliberately a LABEL, not this repo's own GitHub
+ * Projects v2 "Priority" field (a single-select with its own Urgent/High/
+ * Medium/Low options): a Projects v2 value is GraphQL-only, needs a
+ * `project` token scope and a project id in config, and has no Jira
+ * equivalent — the exact abstraction `jira_provider.ts` exists to protect.
+ * If a repo's board also carries a Priority field, the two are independent
+ * and nothing reconciles them; `spf watch` obeys only this label. See
+ * README.md's `spf watch` section for the reconciliation-by-hand caveat.
+ */
+const PRIORITIES = ["p0", "p1", "p2", "p3"];
+const PRIORITY_LABEL_META = {
+    p0: { color: "b60205", description: "drop everything — a broken promise to users, or blocking everything else" },
+    p1: { color: "d93f0b", description: "the spec's core value — the slices without which it isn't shipped" },
+    p2: { color: "fbca04", description: "the default — real scope, can wait a cycle" },
+    p3: { color: "c5def5", description: "worth writing down, not worth scheduling yet" },
+};
 export class GitHubProvider {
     repo;
     labelPrefix;
@@ -56,6 +91,10 @@ export class GitHubProvider {
     typeLabel(kind) {
         return `${this.labelPrefix}:type:${kind}`;
     }
+    /** Mirrors `core/refine.ts`'s own module-level `priorityLabel()` — that one stays provider-agnostic (a plain string, no `this`); this one is `ensureLabels()`'s seeding half. */
+    priorityLabel(priority) {
+        return `${this.labelPrefix}:priority:${priority}`;
+    }
     /** `null` on a real 404 (label doesn't exist yet) — any other non-2xx still throws, same as `gh()`. */
     async getLabel(name) {
         const response = await fetch(`${API}/repos/${this.repo}/labels/${encodeURIComponent(name)}`, {
@@ -103,6 +142,13 @@ export class GitHubProvider {
             const { color, description } = TYPE_LABEL_META[kind];
             await this.ensureOneLabel(this.typeLabel(kind), color, description, result);
         }
+        // `<prefix>:priority:p0..p3` — what claimNewWork schedules by (see
+        // PRIORITY_LABEL_META's doc comment above on why this is a label, not
+        // this repo's own Projects v2 Priority field).
+        for (const priority of PRIORITIES) {
+            const { color, description } = PRIORITY_LABEL_META[priority];
+            await this.ensureOneLabel(this.priorityLabel(priority), color, description, result);
+        }
         return result;
     }
     toIssue(raw) {
@@ -114,9 +160,36 @@ export class GitHubProvider {
             labels: raw.labels.map((l) => (typeof l === "string" ? l : l.name)),
         };
     }
+    /**
+     * `sort=created&direction=asc` is stated, not inherited: without it,
+     * GitHub's own default (`created`, `desc` — newest first) is what
+     * `claimNewWork` used to walk, silently, which is why a >100-issue ready
+     * backlog used to be a real risk before pagination existed at all.
+     * Oldest-first is also `orderEligible`'s own final tiebreaker (`watch.ts`),
+     * so this method's order and that function's are the same order absent a
+     * priority/affinity difference — no redundant client-side re-sort needed
+     * for the plain case.
+     *
+     * Paginates up to `MAX_LIST_PAGES` (500 issues) — no longer "this
+     * version's problem to solve": a client-side priority sort over a
+     * truncated first page would silently misorder or hide real work, which is
+     * worse than the old unordered-100-issues behavior it replaces. A repo
+     * that still exceeds the cap gets a loud, named warning rather than a
+     * silent truncation.
+     */
     async listByLabel(label, state) {
-        const raw = await this.gh(`/repos/${this.repo}/issues?labels=${encodeURIComponent(label)}&state=${state}&per_page=100`);
-        return raw.filter((i) => !i.pull_request).map((i) => this.toIssue(i));
+        const results = [];
+        for (let page = 1; page <= MAX_LIST_PAGES; page++) {
+            const raw = await this.gh(`/repos/${this.repo}/issues?labels=${encodeURIComponent(label)}&state=${state}&sort=created&direction=asc&per_page=100&page=${page}`);
+            results.push(...raw.filter((i) => !i.pull_request).map((i) => this.toIssue(i)));
+            if (raw.length < 100)
+                return results; // short page — this was the last one
+            if (page === MAX_LIST_PAGES) {
+                console.error(`spf watch: listByLabel(${JSON.stringify(label)}) hit the ${MAX_LIST_PAGES}-page (${MAX_LIST_PAGES * 100}-issue) cap — ` +
+                    `older ${JSON.stringify(label)} issues past this cap are invisible this tick`);
+            }
+        }
+        return results;
     }
     async listEligible() {
         return this.listByLabel(this.label("ready"), "open");
@@ -124,6 +197,24 @@ export class GitHubProvider {
     async listInState(state, opts) {
         return this.listByLabel(this.label(state), opts?.includeAll ? "all" : "open");
     }
+    /** `null` on a real 404 — deleted, or (state defaults to open in a plain fetch) an issue GitHub itself considers gone. Any other non-2xx still throws, same as `gh()`. */
+    async getIssue(id) {
+        const response = await fetch(`${API}/repos/${this.repo}/issues/${id}`, {
+            headers: { Authorization: `Bearer ${this.token}`, Accept: "application/vnd.github+json", "X-GitHub-Api-Version": "2022-11-28" },
+        });
+        if (response.status === 404)
+            return null;
+        if (!response.ok) {
+            const detail = await response.text().catch(() => "");
+            throw new Error(`GitHub GET /repos/${this.repo}/issues/${id} -> ${response.status}: ${detail.slice(0, 500)}`);
+        }
+        return this.toIssue((await response.json()));
+    }
+    /** `GET .../sub_issues` — the read-back half of `linkChild`; what makes container roll-up possible (`rollUp` in `watch.ts`). Closed children ARE returned (no `state` filter) — roll-up needs to see a `blocked` child too, to correctly NOT finish the container. */
+    async listChildren(parent) {
+        const raw = await this.gh(`/repos/${this.repo}/issues/${parent.id}/sub_issues`);
+        return raw.filter((i) => !i.pull_request).map((i) => this.toIssue(i));
+    }
     async claim(issue, opts) {
         const from = this.label(opts?.from ?? "ready");
         const to = this.label(opts?.to ?? "working");
@@ -196,7 +287,13 @@ export class GitHubProvider {
         }
         return { merged: detail.merged, state: detail.state, ciStatus };
     }
-    /** `IssueAuthoringProvider` — the refine lane's own need (see `provider.ts`'s module doc). */
+    /**
+     * `IssueAuthoringProvider` — the refine lane's own need (see `provider.ts`'s
+     * module doc). `input.kind` is unused here: GitHub has no native
+     * issue-type field the way Jira does, and `input.labels` already carries
+     * `<prefix>:type:<kind>` for GitHub's own bookkeeping — the parameter
+     * exists on the shared interface for `JiraProvider`'s sake.
+     */
     async createIssue(input) {
         const raw = await this.gh(`/repos/${this.repo}/issues`, {
             method: "POST",
@@ -221,8 +318,12 @@ export class GitHubProvider {
             body: JSON.stringify({ sub_issue_id: Number(child.internal_id) }),
         });
     }
+    /** The single fetch every comment-reading method (`findMarkerComment`, `listComments`) builds on. */
+    async fetchComments(issueId) {
+        return this.gh(`/repos/${this.repo}/issues/${issueId}/comments?per_page=100`);
+    }
     async findMarkerComment(issueId) {
-        const comments = await this.gh(`/repos/${this.repo}/issues/${issueId}/comments?per_page=100`);
+        const comments = await this.fetchComments(issueId);
         let found = null;
         for (const c of comments) {
             const match = MARKER_RE.exec(c.body || "");
@@ -251,4 +352,18 @@ export class GitHubProvider {
             await this.gh(`/repos/${this.repo}/issues/${issue.id}/comments`, { method: "POST", body: JSON.stringify({ body }) });
         }
     }
+    /** Oldest-first (GitHub's own comment order), the hidden marker comment filtered out. */
+    async listComments(issue) {
+        const comments = await this.fetchComments(issue.id);
+        return comments
+            .filter((c) => !MARKER_RE.test(c.body || ""))
+            .map((c) => ({ id: String(c.id), author: c.user?.login ?? "unknown", created_at: c.created_at, body: c.body || "" }));
+    }
+    /** `state_reason: "completed"` — the refine lane's own reason for closing a spec once it's fully decomposed; see `finishSpec` in `watch.ts`. */
+    async closeIssue(issue) {
+        await this.gh(`/repos/${this.repo}/issues/${issue.id}`, {
+            method: "PATCH",
+            body: JSON.stringify({ state: "closed", state_reason: "completed" }),
+        });
+    }
 }

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

@@ -30,25 +30,45 @@
  * Jira labels are freeform strings with no color/description registry to
  * seed, unlike GitHub's.
  *
- * Does NOT implement `IssueAuthoringProvider` — the refine lane's create/
- * link seam. Jira maps cleanly in principle (native issue types plus a
- * `parent` field give a real hierarchy, unlike the label trick this file
- * already leans on for state), but that is a real implementation, not a
- * one-line stub, so it is a deliberate follow-on rather than done here.
- * `resolveIssueAuthoringProvider()` (`cli/commands/watch.ts`) returns `null`
- * for this provider, and `watch.refine.enabled: true` with
- * `issue_provider: jira` fails loudly at startup rather than silently
- * running a refine lane that can never publish anything.
+ * Implements `IssueAuthoringProvider` — the refine lane's create/link seam
+ * — via Jira's native issue types plus the `parent` field: `createIssue`
+ * maps a `RefinedIssue.kind` to a real Jira issue type name through the
+ * configured `issueTypes` map (project setups rename/customize these often
+ * enough that hardcoding "Epic"/"Story"/"Bug"/"Task" would break silently
+ * on plenty of real projects), and `linkChild` sets the child's `parent`
+ * field to the parent's key. This is the MODERN mechanism only — it works
+ * on team-managed projects and on company-managed projects with Jira's
+ * current issue-hierarchy setting; it does NOT fall back to the legacy
+ * "Epic Link" custom field some older company-managed projects still rely
+ * on. A project not configured for `parent`-based hierarchy gets Jira's own
+ * API error surfaced as-is (this file's `jira()` wrapper never swallows a
+ * non-2xx), never silently ignored. `listChildren` reads the hierarchy back
+ * via a `parent = "<id>"` JQL search (same POST-body pattern
+ * `searchByLabel` already uses below), which is what makes container
+ * roll-up (`rollUp` in `watch.ts`) work here too, not just on GitHub.
+ * `validateIssueTypes()` (below) is a plain method, not part of any shared
+ * interface — GitHub has no equivalent concept — that `spf watch init` and
+ * `spf watch`'s own startup check (`cli/commands/watch.ts`) both call to
+ * catch a misconfigured `issueTypes` entry before anything unattended runs.
+ *
+ * One accepted platform limitation: Jira doesn't support Epic-under-Epic
+ * nesting the way GitHub's sub-issues API supports up to 8 levels. A
+ * refiner tree with a `feature` node parented under another `epic`/
+ * `feature` (both mapping to Jira's Epic type by default) surfaces a real
+ * Jira API error at publish time — a genuine platform difference, not
+ * something this file tries to paper over.
  */
-import type { EnsureLabelsResult, Issue, IssueProvider, WatchMarker, WatchState } from "./provider.ts";
-export declare class JiraProvider implements IssueProvider {
+import type { RefinedIssue, JiraIssueTypeMap } from "../data_types.ts";
+import type { EnsureLabelsResult, Issue, IssueAuthoringProvider, IssueComment, IssueProvider, WatchMarker, WatchState } from "./provider.ts";
+export declare class JiraProvider implements IssueProvider, IssueAuthoringProvider {
     private readonly baseUrl;
     private readonly projectKey;
     private readonly labelPrefix;
     private readonly email;
     private readonly apiToken;
+    private readonly issueTypes;
     constructor(baseUrl: string, // e.g. "https://your-domain.atlassian.net", no trailing slash
-    projectKey: string, labelPrefix: string, email: string, apiToken: string);
+    projectKey: string, labelPrefix: string, email: string, apiToken: string, issueTypes: JiraIssueTypeMap);
     private authHeader;
     private jira;
     private label;
@@ -73,13 +93,64 @@ export declare class JiraProvider implements IssueProvider {
      * could make a `review`-labeled issue vanish from an unfiltered query.
      */
     listInState(state: WatchState): Promise<Issue[]>;
+    /**
+     * `null` on a real 404 (deleted, or a key that never existed) — any other
+     * non-2xx still throws, same as `jira()`. What `claimNewWork`'s frontier
+     * check (`watch.ts`) uses to look up a `blocked_by` id's current labels.
+     * Unlike `github_provider.ts`'s hidden `spf-refine:` body marker, this
+     * file has no equivalent for a Jira issue's OWN parent/blockers — a
+     * caller here only ever sees what `blocked_by` it already has in hand,
+     * never discovers it from the issue body itself.
+     */
+    getIssue(id: string): Promise<Issue | null>;
+    /** `IssueAuthoringProvider` — the refine lane's own need (see `provider.ts`'s module doc). `POST /rest/api/3/issue`'s response is `{id, key, self}`, not the full read shape `toIssue` expects, so this constructs the returned `Issue` locally rather than re-fetching. */
+    createIssue(input: {
+        title: string;
+        body: string;
+        labels: string[];
+        kind: RefinedIssue["kind"];
+    }): Promise<Issue>;
+    /**
+     * The modern mechanism only — Jira's `parent` field, not the legacy
+     * "Epic Link" custom field. Works on team-managed projects and on
+     * company-managed projects with Jira's current issue-hierarchy setting;
+     * a project not configured for it surfaces Jira's own API error here,
+     * unmodified — see this file's module comment on the accepted
+     * Epic-under-Epic limitation this implies.
+     */
+    linkChild(parent: Issue, child: Issue): Promise<void>;
+    /** The read-back half of `linkChild` — same JQL-in-body pattern as `searchByLabel`, since a GET with query params silently returns nothing on this endpoint (see the module comment). What makes container roll-up (`rollUp` in `watch.ts`) work on Jira too. */
+    listChildren(parent: Issue): Promise<Issue[]>;
+    /**
+     * Read-only validation of the configured `issueTypes` map against this
+     * project's real issue types — what `spf watch init` and `spf watch`'s
+     * own refine-lane startup check (`cli/commands/watch.ts`) both call to
+     * catch a bad mapping before anything unattended runs on it, rather than
+     * discovering it the first time a spec tries to publish. Not part of
+     * `IssueAuthoringProvider` — GitHub has no equivalent concept, since it
+     * has no native issue-type field to get wrong.
+     *
+     * Fetches a single page (Jira's own default: 50) — a project with more
+     * issue types than that is exotic enough to warrant a loud warning
+     * rather than a silent multi-page fetch loop for an edge case this
+     * unlikely.
+     */
+    validateIssueTypes(): Promise<Array<{
+        kind: string;
+        jiraType: string;
+        exists: boolean;
+    }>>;
     claim(issue: Issue, opts?: {
         from?: WatchState;
         to?: WatchState;
     }): Promise<boolean>;
     transition(issue: Issue, to: WatchState, detail?: string): Promise<void>;
     comment(issue: Issue, body: string): Promise<void>;
+    /** The single fetch every comment-reading method (`findMarkerComment`, `listComments`) builds on. */
+    private fetchComments;
     private findMarkerComment;
+    /** Oldest-first (Jira's own comment order), the hidden `[spf-watch-marker]` comment filtered out. */
+    listComments(issue: Issue): Promise<IssueComment[]>;
     readMarker(issue: Issue): Promise<WatchMarker | null>;
     writeMarker(issue: Issue, marker: WatchMarker): Promise<void>;
 }

package/dist/core/issues/jira_provider.js

@@ -1,4 +1,16 @@
-const STATES = ["ready", "working", "review", "done", "blocked", "spec-ready", "refining", "refined"];
+const STATES = [
+    "ready",
+    "working",
+    "review",
+    "done",
+    "blocked",
+    "spec-ready",
+    "refining",
+    "refined",
+    "needs-feedback",
+    "continue-refinement",
+    "spec-in-progress",
+];
 const MARKER_RE = /\[spf-watch-marker\]\s*(\{.*?\})/s;
 function toAdf(text) {
     return {
@@ -24,13 +36,15 @@ export class JiraProvider {
     labelPrefix;
     email;
     apiToken;
+    issueTypes;
     constructor(baseUrl, // e.g. "https://your-domain.atlassian.net", no trailing slash
-    projectKey, labelPrefix, email, apiToken) {
+    projectKey, labelPrefix, email, apiToken, issueTypes) {
         this.baseUrl = baseUrl;
         this.projectKey = projectKey;
         this.labelPrefix = labelPrefix;
         this.email = email;
         this.apiToken = apiToken;
+        this.issueTypes = issueTypes;
     }
     authHeader() {
         return `Basic ${Buffer.from(`${this.email}:${this.apiToken}`).toString("base64")}`;
@@ -103,6 +117,86 @@ export class JiraProvider {
     async listInState(state) {
         return this.searchByLabel(this.label(state));
     }
+    /**
+     * `null` on a real 404 (deleted, or a key that never existed) — any other
+     * non-2xx still throws, same as `jira()`. What `claimNewWork`'s frontier
+     * check (`watch.ts`) uses to look up a `blocked_by` id's current labels.
+     * Unlike `github_provider.ts`'s hidden `spf-refine:` body marker, this
+     * file has no equivalent for a Jira issue's OWN parent/blockers — a
+     * caller here only ever sees what `blocked_by` it already has in hand,
+     * never discovers it from the issue body itself.
+     */
+    async getIssue(id) {
+        const response = await fetch(`${this.baseUrl}/rest/api/3/issue/${id}?fields=summary,description,labels`, {
+            headers: { Authorization: this.authHeader(), Accept: "application/json" },
+        });
+        if (response.status === 404)
+            return null;
+        if (!response.ok) {
+            const detail = await response.text().catch(() => "");
+            throw new Error(`Jira GET /rest/api/3/issue/${id} -> ${response.status}: ${detail.slice(0, 500)}`);
+        }
+        return this.toIssue((await response.json()));
+    }
+    /** `IssueAuthoringProvider` — the refine lane's own need (see `provider.ts`'s module doc). `POST /rest/api/3/issue`'s response is `{id, key, self}`, not the full read shape `toIssue` expects, so this constructs the returned `Issue` locally rather than re-fetching. */
+    async createIssue(input) {
+        const response = await this.jira("/rest/api/3/issue", {
+            method: "POST",
+            body: JSON.stringify({
+                fields: {
+                    project: { key: this.projectKey },
+                    summary: input.title,
+                    description: toAdf(input.body),
+                    issuetype: { name: this.issueTypes[input.kind] },
+                    labels: input.labels,
+                },
+            }),
+        });
+        return { id: response.key, title: input.title, body: input.body, labels: input.labels };
+    }
+    /**
+     * The modern mechanism only — Jira's `parent` field, not the legacy
+     * "Epic Link" custom field. Works on team-managed projects and on
+     * company-managed projects with Jira's current issue-hierarchy setting;
+     * a project not configured for it surfaces Jira's own API error here,
+     * unmodified — see this file's module comment on the accepted
+     * Epic-under-Epic limitation this implies.
+     */
+    async linkChild(parent, child) {
+        await this.jira(`/rest/api/3/issue/${child.id}`, { method: "PUT", body: JSON.stringify({ fields: { parent: { key: parent.id } } }) });
+    }
+    /** The read-back half of `linkChild` — same JQL-in-body pattern as `searchByLabel`, since a GET with query params silently returns nothing on this endpoint (see the module comment). What makes container roll-up (`rollUp` in `watch.ts`) work on Jira too. */
+    async listChildren(parent) {
+        const jql = `parent = ${JSON.stringify(parent.id)}`;
+        const result = await this.jira("/rest/api/3/search/jql", {
+            method: "POST",
+            body: JSON.stringify({ jql, maxResults: 100, fields: ["summary", "description", "labels"] }),
+        });
+        return result.issues.map((i) => this.toIssue(i));
+    }
+    /**
+     * Read-only validation of the configured `issueTypes` map against this
+     * project's real issue types — what `spf watch init` and `spf watch`'s
+     * own refine-lane startup check (`cli/commands/watch.ts`) both call to
+     * catch a bad mapping before anything unattended runs on it, rather than
+     * discovering it the first time a spec tries to publish. Not part of
+     * `IssueAuthoringProvider` — GitHub has no equivalent concept, since it
+     * has no native issue-type field to get wrong.
+     *
+     * Fetches a single page (Jira's own default: 50) — a project with more
+     * issue types than that is exotic enough to warrant a loud warning
+     * rather than a silent multi-page fetch loop for an edge case this
+     * unlikely.
+     */
+    async validateIssueTypes() {
+        const result = await this.jira(`/rest/api/3/issue/createmeta/${encodeURIComponent(this.projectKey)}/issuetypes`);
+        if (result.isLast === false) {
+            console.error(`spf watch: ${this.projectKey} has more issue types than one page reports — validateIssueTypes() may be missing some; ` +
+                `re-run with a narrower watch.jira.issue_types check if a false mismatch shows up`);
+        }
+        const available = new Set(result.issueTypes.map((t) => t.name));
+        return Object.entries(this.issueTypes).map(([kind, jiraType]) => ({ kind, jiraType, exists: available.has(jiraType) }));
+    }
     async claim(issue, opts) {
         const from = this.label(opts?.from ?? "ready");
         const to = this.label(opts?.to ?? "working");
@@ -129,10 +223,15 @@ export class JiraProvider {
     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) {
+    /** The single fetch every comment-reading method (`findMarkerComment`, `listComments`) builds on. */
+    async fetchComments(issueId) {
         const result = await this.jira(`/rest/api/3/issue/${issueId}/comment?maxResults=100`);
+        return result.comments;
+    }
+    async findMarkerComment(issueId) {
+        const comments = await this.fetchComments(issueId);
         let found = null;
-        for (const c of result.comments) {
+        for (const c of comments) {
             const match = MARKER_RE.exec(adfToText(c.body));
             if (!match)
                 continue;
@@ -145,6 +244,13 @@ export class JiraProvider {
         }
         return found;
     }
+    /** Oldest-first (Jira's own comment order), the hidden `[spf-watch-marker]` comment filtered out. */
+    async listComments(issue) {
+        const comments = await this.fetchComments(issue.id);
+        return comments
+            .filter((c) => !MARKER_RE.test(adfToText(c.body)))
+            .map((c) => ({ id: c.id, author: c.author?.displayName ?? "unknown", created_at: c.created, body: adfToText(c.body) }));
+    }
     async readMarker(issue) {
         const found = await this.findMarkerComment(issue.id);
         return found?.marker ?? null;