@gr8ful/spf 0.14.0 → 0.15.0

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

@@ -8,7 +8,8 @@
  * a couple dozen REST calls, none of them exotic. `spf`'s own package stays
  * dependency-free either way.
  *
- * Auth is a classic PAT via `GITHUB_TOKEN` (`repo` scope), read once at
+ * Auth is a classic PAT via `GITHUB_TOKEN` (`repo` scope — plus `project` if
+ * `watch.github.status_map` is configured, see below), read once at
  * construction — matching the reference implementation's pattern and this
  * project's existing env-var-for-credentials philosophy. `listByLabel`
  * paginates up to `MAX_LIST_PAGES` (500 issues per label query) — no longer
@@ -17,7 +18,21 @@
  * 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.
+ *
+ * State is modeled as labels (`<prefix>:ready`, etc.) — labels are spf's
+ * ACTUAL state machine and always get written, unconditionally. Native
+ * GitHub Projects v2 board status is a separate, OPTIONAL, best-effort layer
+ * on top (`syncStatus()`), driven entirely by `watch.github.status_map` —
+ * empty by default, so an existing config's behavior is unchanged. It's
+ * opt-in, and GraphQL-only (Projects v2 has no REST API), because not every
+ * repo has a board wired up, and a board's Status option names are per-
+ * project configuration `spf` can't assume; a misconfigured or unreachable
+ * entry degrades to a logged warning, never a thrown error — same rule
+ * `jira_provider.ts`'s own `syncStatus()` follows, for the same reason: a
+ * status-sync miss must never block the label update `spf watch` actually
+ * depends on.
  */
+import type { GithubStatusMap } from "../data_types.ts";
 import type { CodeHostProvider, EnsureLabelsResult, Issue, IssueAuthoringKind, IssueAuthoringProvider, IssueComment, IssueProvider, PrRef, PrStatus, WatchMarker, WatchState } from "./provider.ts";
 /**
  * The refine lane's leaf/container taxonomy — see `data_types.ts`'s
@@ -32,9 +47,23 @@ export declare class GitHubProvider implements IssueProvider, CodeHostProvider,
     private readonly repo;
     private readonly labelPrefix;
     private readonly token;
+    private readonly projectNumber;
+    private readonly statusMap;
+    /** Resolved lazily by `resolveProjectStatusField()` — cached only on SUCCESS, so a transient GraphQL hiccup gets retried the next call rather than disabling status sync for this instance's entire (potentially daemon-long) lifetime. */
+    private projectMeta?;
     constructor(repo: string, // "owner/name"
-    labelPrefix: string, token: string);
+    labelPrefix: string, token: string, projectNumber?: number, // 0 = status sync disabled, regardless of statusMap
+    statusMap?: GithubStatusMap);
     private gh;
+    /**
+     * Projects v2 has no REST surface at all — this is the one place this
+     * file talks GraphQL instead of REST. A GraphQL "not found" (bad login,
+     * bad project number, missing `project` scope) comes back as a 200 with a
+     * null data field plus an `errors` array, not a non-2xx — callers read
+     * `data` being falsy as "couldn't resolve," same as a 404 elsewhere in
+     * this file.
+     */
+    private ghGraphql;
     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. */
@@ -82,6 +111,41 @@ export declare class GitHubProvider implements IssueProvider, CodeHostProvider,
         to?: WatchState;
     }): Promise<boolean>;
     transition(issue: Issue, to: WatchState, detail?: string): Promise<void>;
+    /**
+     * Best-effort native Projects v2 status sync — a no-op unless
+     * `project_number` AND `status_map` both configure something for `to`.
+     * Every failure mode (unconfigured, project/field not found, no matching
+     * option, a rejected mutation) is logged and swallowed, never thrown —
+     * see this file's module comment on why a status-sync miss must never
+     * break the label update callers depend on.
+     */
+    private syncStatus;
+    /**
+     * Resolves (and caches — see `projectMeta`'s own doc comment) `watch.github.project_number`'s
+     * "Status" single-select field against the repo OWNER's Projects v2 board
+     * (Projects v2 numbers are per-owner, not per-repo — see
+     * `WatchGithubConfigSchema`'s doc comment). Tries `organization(login:)`
+     * first, then `user(login:)`: an owner is exactly one of the two, and
+     * GraphQL returns that field as `null` (not a hard error) when it's the
+     * wrong kind, so falling through is safe.
+     */
+    private resolveProjectStatusField;
+    /** The item-id half of `syncStatus()`: an issue already on the project has one; otherwise this adds it, since a `status_map` entry is an implicit "yes, put this on the board" — the same way a Jira issue is already assumed to be on its project. `null` (logged) on any lookup/add failure. */
+    private resolveProjectItemId;
+    /**
+     * Read-only validation of the configured `status_map` against the real
+     * project's Status options — what `spf watch init` and `spf watch`'s own
+     * startup check call to catch a misnamed option before an unattended run
+     * silently no-ops its status sync every time, the same role
+     * `validateIssueTypes()`/`validateStatusMap()` play on the Jira side.
+     * Empty when `status_map` has no entries configured at all — nothing to
+     * report, not a mismatch.
+     */
+    validateStatusMap(): Promise<Array<{
+        state: string;
+        githubStatus: string;
+        exists: boolean;
+    }>>;
     comment(issue: Issue, body: string): Promise<void>;
     openPr(opts: {
         branch: string;

package/dist/core/issues/github_provider.js

@@ -86,11 +86,18 @@ export class GitHubProvider {
     repo;
     labelPrefix;
     token;
+    projectNumber;
+    statusMap;
+    /** Resolved lazily by `resolveProjectStatusField()` — cached only on SUCCESS, so a transient GraphQL hiccup gets retried the next call rather than disabling status sync for this instance's entire (potentially daemon-long) lifetime. */
+    projectMeta;
     constructor(repo, // "owner/name"
-    labelPrefix, token) {
+    labelPrefix, token, projectNumber = 0, // 0 = status sync disabled, regardless of statusMap
+    statusMap = {}) {
         this.repo = repo;
         this.labelPrefix = labelPrefix;
         this.token = token;
+        this.projectNumber = projectNumber;
+        this.statusMap = statusMap;
     }
     async gh(path, init) {
         const response = await fetch(`${API}${path}`, {
@@ -111,6 +118,34 @@ export class GitHubProvider {
             return undefined;
         return (await response.json());
     }
+    /**
+     * Projects v2 has no REST surface at all — this is the one place this
+     * file talks GraphQL instead of REST. A GraphQL "not found" (bad login,
+     * bad project number, missing `project` scope) comes back as a 200 with a
+     * null data field plus an `errors` array, not a non-2xx — callers read
+     * `data` being falsy as "couldn't resolve," same as a 404 elsewhere in
+     * this file.
+     */
+    async ghGraphql(query, variables) {
+        const response = await fetch(`${API}/graphql`, {
+            method: "POST",
+            headers: {
+                Authorization: `Bearer ${this.token}`,
+                Accept: "application/vnd.github+json",
+                "Content-Type": "application/json",
+            },
+            body: JSON.stringify({ query, variables }),
+        });
+        if (!response.ok) {
+            const detail = await response.text().catch(() => "");
+            throw new Error(`GitHub GraphQL -> ${response.status}: ${detail.slice(0, 500)}`);
+        }
+        const json = (await response.json());
+        if (!json.data) {
+            throw new Error(`GitHub GraphQL returned no data${json.errors ? `: ${json.errors.map((e) => e.message).join("; ")}` : ""}`);
+        }
+        return json.data;
+    }
     label(state) {
         return `${this.labelPrefix}:${state}`;
     }
@@ -242,8 +277,9 @@ export class GitHubProvider {
         return raw.filter((i) => !i.pull_request).map((i) => this.toIssue(i));
     }
     async claim(issue, opts) {
+        const toState = opts?.to ?? "working";
         const from = this.label(opts?.from ?? "ready");
-        const to = this.label(opts?.to ?? "working");
+        const to = this.label(toState);
         await this.gh(`/repos/${this.repo}/issues/${issue.id}/labels/${encodeURIComponent(from)}`, {
             method: "DELETE",
         }).catch(() => undefined); // already gone is fine
@@ -261,6 +297,9 @@ export class GitHubProvider {
                 body: JSON.stringify({ labels: [from] }),
             }).catch(() => undefined);
         }
+        else {
+            await this.syncStatus(issue, toState);
+        }
         return claimed;
     }
     async transition(issue, to, detail) {
@@ -274,9 +313,129 @@ export class GitHubProvider {
             method: "POST",
             body: JSON.stringify({ labels: [this.label(to)] }),
         });
+        await this.syncStatus(issue, to);
         if (detail)
             await this.comment(issue, detail);
     }
+    /**
+     * Best-effort native Projects v2 status sync — a no-op unless
+     * `project_number` AND `status_map` both configure something for `to`.
+     * Every failure mode (unconfigured, project/field not found, no matching
+     * option, a rejected mutation) is logged and swallowed, never thrown —
+     * see this file's module comment on why a status-sync miss must never
+     * break the label update callers depend on.
+     */
+    async syncStatus(issue, to) {
+        const statusName = this.statusMap[to];
+        if (!statusName)
+            return;
+        const meta = await this.resolveProjectStatusField();
+        if (!meta)
+            return; // already logged inside resolveProjectStatusField, or simply unconfigured (project_number: 0)
+        const optionId = meta.options.get(statusName);
+        if (!optionId) {
+            console.error(`spf watch: issue #${issue.id} — GitHub Projects #${this.projectNumber} has no Status option named ${JSON.stringify(statusName)} (watch.github.status_map.${to}) — skipping status sync, label already updated`);
+            return;
+        }
+        try {
+            const itemId = await this.resolveProjectItemId(issue, meta.projectId);
+            if (!itemId)
+                return; // already logged inside resolveProjectItemId
+            await this.ghGraphql(`mutation($projectId: ID!, $itemId: ID!, $fieldId: ID!, $optionId: String!) {
+          updateProjectV2ItemFieldValue(input: {projectId: $projectId, itemId: $itemId, fieldId: $fieldId, value: {singleSelectOptionId: $optionId}}) {
+            clientMutationId
+          }
+        }`, { projectId: meta.projectId, itemId, fieldId: meta.statusFieldId, optionId });
+        }
+        catch (err) {
+            console.error(`spf watch: issue #${issue.id} — GitHub Projects status sync to ${JSON.stringify(statusName)} failed; label already updated — ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    /**
+     * Resolves (and caches — see `projectMeta`'s own doc comment) `watch.github.project_number`'s
+     * "Status" single-select field against the repo OWNER's Projects v2 board
+     * (Projects v2 numbers are per-owner, not per-repo — see
+     * `WatchGithubConfigSchema`'s doc comment). Tries `organization(login:)`
+     * first, then `user(login:)`: an owner is exactly one of the two, and
+     * GraphQL returns that field as `null` (not a hard error) when it's the
+     * wrong kind, so falling through is safe.
+     */
+    async resolveProjectStatusField() {
+        if (!this.projectNumber)
+            return null;
+        if (this.projectMeta)
+            return this.projectMeta;
+        const owner = this.repo.split("/")[0];
+        let data;
+        try {
+            data = await this.ghGraphql(`query($login: String!, $number: Int!) {
+          organization(login: $login) { projectV2(number: $number) { id fields(first: 50) { nodes { ... on ProjectV2SingleSelectField { id name options { id name } } } } } }
+          user(login: $login) { projectV2(number: $number) { id fields(first: 50) { nodes { ... on ProjectV2SingleSelectField { id name options { id name } } } } } }
+        }`, { login: owner, number: this.projectNumber });
+        }
+        catch (err) {
+            console.error(`spf watch: couldn't resolve GitHub Projects v2 #${this.projectNumber} for ${owner} — status sync skipped this run — ${err instanceof Error ? err.message : String(err)}`);
+            return null;
+        }
+        const project = data.organization?.projectV2 ?? data.user?.projectV2;
+        if (!project) {
+            console.error(`spf watch: GitHub Projects v2 #${this.projectNumber} not found for ${owner} (or GITHUB_TOKEN lacks "project" scope) — status sync skipped this run`);
+            return null;
+        }
+        const statusField = project.fields.nodes.find((f) => f !== null && f.name === "Status");
+        if (!statusField) {
+            console.error(`spf watch: GitHub Projects v2 #${this.projectNumber} has no "Status" single-select field — status sync skipped this run`);
+            return null;
+        }
+        this.projectMeta = { projectId: project.id, statusFieldId: statusField.id, options: new Map(statusField.options.map((o) => [o.name, o.id])) };
+        return this.projectMeta;
+    }
+    /** The item-id half of `syncStatus()`: an issue already on the project has one; otherwise this adds it, since a `status_map` entry is an implicit "yes, put this on the board" — the same way a Jira issue is already assumed to be on its project. `null` (logged) on any lookup/add failure. */
+    async resolveProjectItemId(issue, projectId) {
+        const [owner, name] = this.repo.split("/");
+        let data;
+        try {
+            data = await this.ghGraphql(`query($owner: String!, $name: String!, $number: Int!) {
+          repository(owner: $owner, name: $name) {
+            issue(number: $number) { id projectItems(first: 20) { nodes { id project { id } } } }
+          }
+        }`, { owner, name, number: Number(issue.id) });
+        }
+        catch (err) {
+            console.error(`spf watch: issue #${issue.id} — couldn't look up its GitHub Projects item; status sync skipped, label already updated — ${err instanceof Error ? err.message : String(err)}`);
+            return null;
+        }
+        const ghIssue = data.repository?.issue;
+        if (!ghIssue)
+            return null; // deleted between the label update and here — nothing left to sync
+        const existing = ghIssue.projectItems.nodes.find((n) => n.project.id === projectId);
+        if (existing)
+            return existing.id;
+        try {
+            const added = await this.ghGraphql(`mutation($projectId: ID!, $contentId: ID!) { addProjectV2ItemById(input: {projectId: $projectId, contentId: $contentId}) { item { id } } }`, { projectId, contentId: ghIssue.id });
+            return added.addProjectV2ItemById.item.id;
+        }
+        catch (err) {
+            console.error(`spf watch: issue #${issue.id} — couldn't add it to GitHub Projects #${this.projectNumber}; status sync skipped, label already updated — ${err instanceof Error ? err.message : String(err)}`);
+            return null;
+        }
+    }
+    /**
+     * Read-only validation of the configured `status_map` against the real
+     * project's Status options — what `spf watch init` and `spf watch`'s own
+     * startup check call to catch a misnamed option before an unattended run
+     * silently no-ops its status sync every time, the same role
+     * `validateIssueTypes()`/`validateStatusMap()` play on the Jira side.
+     * Empty when `status_map` has no entries configured at all — nothing to
+     * report, not a mismatch.
+     */
+    async validateStatusMap() {
+        const entries = Object.entries(this.statusMap).filter((entry) => Boolean(entry[1]));
+        if (entries.length === 0)
+            return [];
+        const meta = await this.resolveProjectStatusField();
+        return entries.map(([state, githubStatus]) => ({ state, githubStatus, exists: meta ? meta.options.has(githubStatus) : false }));
+    }
     async comment(issue, body) {
         await this.gh(`/repos/${this.repo}/issues/${issue.id}/comments`, {
             method: "POST",

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

@@ -18,13 +18,22 @@
  *    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.
+ * `github_provider.ts` exactly — labels are spf's ACTUAL state machine and
+ * always get written, unconditionally. 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.
+ *
+ * Native workflow status is a separate, OPTIONAL, best-effort layer on top
+ * (`syncStatus()`), driven entirely by the configured `statusMap` — empty
+ * by default, so an existing config's behavior is unchanged. It's optional
+ * rather than baked into every `transition()` call unconditionally because
+ * Jira workflows vary by project/scheme (status names, which transitions
+ * are reachable from where) in a way labels never do; a project that wants
+ * its board's Status column to move when spf changes a label opts in with
+ * `watch.jira.status_map`, and a misconfigured or unreachable entry there
+ * degrades to a logged warning, never a thrown error — a status-sync miss
+ * must never block the label update `spf watch` actually depends on.
  *
  * `ensureLabels()` is a no-op that reports the labels this run will use:
  * Jira labels are freeform strings with no color/description registry to
@@ -58,7 +67,7 @@
  * Jira API error at publish time — a genuine platform difference, not
  * something this file tries to paper over.
  */
-import type { JiraIssueTypeMap } from "../data_types.ts";
+import type { JiraIssueTypeMap, JiraStatusMap } from "../data_types.ts";
 import type { EnsureLabelsResult, Issue, IssueAuthoringKind, IssueAuthoringProvider, IssueComment, IssueProvider, WatchMarker, WatchState } from "./provider.ts";
 export declare class JiraProvider implements IssueProvider, IssueAuthoringProvider {
     private readonly baseUrl;
@@ -67,8 +76,9 @@ export declare class JiraProvider implements IssueProvider, IssueAuthoringProvid
     private readonly email;
     private readonly apiToken;
     private readonly issueTypes;
+    private readonly statusMap;
     constructor(baseUrl: string, // e.g. "https://your-domain.atlassian.net", no trailing slash
-    projectKey: string, labelPrefix: string, email: string, apiToken: string, issueTypes: JiraIssueTypeMap);
+    projectKey: string, labelPrefix: string, email: string, apiToken: string, issueTypes: JiraIssueTypeMap, statusMap?: JiraStatusMap);
     private authHeader;
     private jira;
     private label;
@@ -145,6 +155,37 @@ export declare class JiraProvider implements IssueProvider, IssueAuthoringProvid
         to?: WatchState;
     }): Promise<boolean>;
     transition(issue: Issue, to: WatchState, detail?: string): Promise<void>;
+    /**
+     * Best-effort native workflow-status sync — a no-op unless `statusMap`
+     * configures a name for `to`. Looked up per call, not cached: the
+     * available transitions are FROM-status-dependent, so the same target
+     * status can need a different transition id depending where the issue
+     * currently sits, and this same issue's status keeps moving across calls
+     * as it advances through the build lane. Every failure mode here
+     * (unconfigured, unreachable, or a rejected transition) is logged and
+     * swallowed, never thrown — see this file's module comment on why a
+     * status-sync miss must never break the label update callers depend on.
+     */
+    private syncStatus;
+    /**
+     * Read-only validation of the configured `status_map` against this
+     * project's real statuses — what `spf watch init` and `spf watch`'s own
+     * startup check should call to catch a misnamed status before an
+     * unattended run silently no-ops its status sync every time, the same
+     * role `validateIssueTypes()` plays for `issue_types`.
+     *
+     * Uses `/rest/api/3/project/{key}/statuses`, which groups statuses by
+     * issue type — Jira workflows can differ per issue type within one
+     * project. A configured name is "exists" if ANY issue type in the project
+     * has it: good enough to catch a typo, not a guarantee every issue type
+     * this map is used against can actually reach it (that's what
+     * `syncStatus()`'s own per-call transition lookup is for).
+     */
+    validateStatusMap(): Promise<Array<{
+        state: string;
+        jiraStatus: string;
+        exists: boolean;
+    }>>;
     comment(issue: Issue, body: string): Promise<void>;
     /** The single fetch every comment-reading method (`findMarkerComment`, `listComments`) builds on. */
     private fetchComments;

package/dist/core/issues/jira_provider.js

@@ -52,14 +52,16 @@ export class JiraProvider {
     email;
     apiToken;
     issueTypes;
+    statusMap;
     constructor(baseUrl, // e.g. "https://your-domain.atlassian.net", no trailing slash
-    projectKey, labelPrefix, email, apiToken, issueTypes) {
+    projectKey, labelPrefix, email, apiToken, issueTypes, statusMap = {}) {
         this.baseUrl = baseUrl;
         this.projectKey = projectKey;
         this.labelPrefix = labelPrefix;
         this.email = email;
         this.apiToken = apiToken;
         this.issueTypes = issueTypes;
+        this.statusMap = statusMap;
     }
     authHeader() {
         return `Basic ${Buffer.from(`${this.email}:${this.apiToken}`).toString("base64")}`;
@@ -213,8 +215,9 @@ export class JiraProvider {
         return Object.entries(this.issueTypes).map(([kind, jiraType]) => ({ kind, jiraType, exists: available.has(jiraType) }));
     }
     async claim(issue, opts) {
+        const toState = opts?.to ?? "working";
         const from = this.label(opts?.from ?? "ready");
-        const to = this.label(opts?.to ?? "working");
+        const to = this.label(toState);
         const next = issue.labels.filter((l) => l !== from);
         next.push(to);
         await this.jira(`/rest/api/3/issue/${issue.id}`, { method: "PUT", body: JSON.stringify({ fields: { labels: next } }) });
@@ -226,15 +229,72 @@ export class JiraProvider {
             revert.push(from);
             await this.jira(`/rest/api/3/issue/${issue.id}`, { method: "PUT", body: JSON.stringify({ fields: { labels: revert } }) }).catch(() => undefined);
         }
+        else {
+            await this.syncStatus(issue, toState);
+        }
         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 } }) });
+        await this.syncStatus(issue, to);
         if (detail)
             await this.comment(issue, detail);
     }
+    /**
+     * Best-effort native workflow-status sync — a no-op unless `statusMap`
+     * configures a name for `to`. Looked up per call, not cached: the
+     * available transitions are FROM-status-dependent, so the same target
+     * status can need a different transition id depending where the issue
+     * currently sits, and this same issue's status keeps moving across calls
+     * as it advances through the build lane. Every failure mode here
+     * (unconfigured, unreachable, or a rejected transition) is logged and
+     * swallowed, never thrown — see this file's module comment on why a
+     * status-sync miss must never break the label update callers depend on.
+     */
+    async syncStatus(issue, to) {
+        const statusName = this.statusMap[to];
+        if (!statusName)
+            return;
+        let transitions;
+        try {
+            ({ transitions } = await this.jira(`/rest/api/3/issue/${issue.id}/transitions`));
+        }
+        catch (err) {
+            console.error(`spf watch: ${issue.id} — couldn't fetch available Jira transitions to sync status ${JSON.stringify(statusName)}; label already updated — ${err instanceof Error ? err.message : String(err)}`);
+            return;
+        }
+        const match = transitions.find((t) => t.to.name === statusName);
+        if (!match) {
+            console.error(`spf watch: ${issue.id} has no available transition to Jira status ${JSON.stringify(statusName)} (watch.jira.status_map.${to}) from its current status — skipping status sync, label already updated`);
+            return;
+        }
+        await this.jira(`/rest/api/3/issue/${issue.id}/transitions`, { method: "POST", body: JSON.stringify({ transition: { id: match.id } }) }).catch((err) => {
+            console.error(`spf watch: ${issue.id} — Jira transition to ${JSON.stringify(statusName)} failed; label already updated — ${err instanceof Error ? err.message : String(err)}`);
+        });
+    }
+    /**
+     * Read-only validation of the configured `status_map` against this
+     * project's real statuses — what `spf watch init` and `spf watch`'s own
+     * startup check should call to catch a misnamed status before an
+     * unattended run silently no-ops its status sync every time, the same
+     * role `validateIssueTypes()` plays for `issue_types`.
+     *
+     * Uses `/rest/api/3/project/{key}/statuses`, which groups statuses by
+     * issue type — Jira workflows can differ per issue type within one
+     * project. A configured name is "exists" if ANY issue type in the project
+     * has it: good enough to catch a typo, not a guarantee every issue type
+     * this map is used against can actually reach it (that's what
+     * `syncStatus()`'s own per-call transition lookup is for).
+     */
+    async validateStatusMap() {
+        const result = await this.jira(`/rest/api/3/project/${encodeURIComponent(this.projectKey)}/statuses`);
+        const available = new Set(result.flatMap((t) => t.statuses.map((s) => s.name)));
+        return Object.entries(this.statusMap)
+            .filter((entry) => Boolean(entry[1]))
+            .map(([state, jiraStatus]) => ({ state, jiraStatus, exists: available.has(jiraStatus) }));
+    }
     async comment(issue, body) {
         await this.jira(`/rest/api/3/issue/${issue.id}/comment`, { method: "POST", body: JSON.stringify({ body: toAdf(body) }) });
     }

package/dist/core/refine.js

@@ -41,7 +41,7 @@ export function resolveAuthoringProvider(cfg) {
         if (!email || !token) {
             throw new Error('JIRA_EMAIL and JIRA_API_TOKEN must both be set — the refine lane needs an Atlassian account email plus an API token (id.atlassian.com -> Security -> API tokens)');
         }
-        return new JiraProvider(cfg.watch.jira.base_url, cfg.watch.jira.project_key, cfg.watch.label_prefix, email, token, cfg.watch.jira.issue_types);
+        return new JiraProvider(cfg.watch.jira.base_url, cfg.watch.jira.project_key, cfg.watch.label_prefix, email, token, cfg.watch.jira.issue_types, cfg.watch.jira.status_map);
     }
     if (cfg.watch.issue_provider !== "github") {
         throw new Error(`watch.issue_provider ${JSON.stringify(cfg.watch.issue_provider)} does not support issue authoring — the refine lane needs "github" or "jira"`);
@@ -61,7 +61,7 @@ export function resolveAuthoringProvider(cfg) {
     if (!token) {
         throw new Error('GITHUB_TOKEN is not set — the refine lane needs a classic PAT with "repo" scope (or "public_repo" for a public-only repo)');
     }
-    return new GitHubProvider(repo, cfg.watch.label_prefix, token);
+    return new GitHubProvider(repo, cfg.watch.label_prefix, token, cfg.watch.github.project_number, cfg.watch.github.status_map);
 }
 function typeLabel(labelPrefix, kind) {
     return `${labelPrefix}:type:${kind}`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gr8ful/spf",
-  "version": "0.14.0",
+  "version": "0.15.0",
   "description": "Super Portable Factory — a global CLI for repeatable agents-plus-code workflows (ADWs)",
   "type": "module",
   "license": "MIT",