mintree 0.2.3 → 0.3.0

package/dist/lib/providers/plane.js

@@ -1,749 +0,0 @@
-/**
- * PlaneProvider — implements IssueProvider against Plane's REST API
- * (https://api.plane.so by default, overridable for self-hosted).
- *
- * Talks raw HTTP rather than going through Plane's MCP server because
- * mintree runs as a Node CLI, not inside an MCP host. The shape of the
- * calls mirrors the MCP tools (list_work_items, list_states, get_me,
- * update_work_item) so the eventual error surface looks familiar.
- *
- * Auth resolution order: `PLANE_API_KEY` env var → `~/.mintree/
- * credentials.json` (`{ plane: { apiKey: "..." } }`). Never reads or
- * writes credentials to the repo's `.mintree/` directory — workspace API
- * keys are user-scoped, not repo-scoped.
- *
- * Filtering by assignee is done client-side: Plane's documented list
- * endpoint doesn't expose an assignee filter, so the provider fetches
- * the project's work items (paginated, per_page=100) and drops ones not
- * assigned to the current user. Acceptable for typical project sizes;
- * if a workspace ever grows past a few hundred items per project we can
- * revisit (probably by switching to the `/work-items/search/` endpoint
- * when it stabilises).
- */
-import * as fs from "fs";
-import * as os from "os";
-import * as path from "path";
-import { readMetadata } from "../metadata.js";
-const DEFAULT_API_URL = "https://api.plane.so";
-const DEFAULT_PROTECTED_STATE_GROUPS = ["completed", "cancelled"];
-const STATUS_ORDER_UNSET = 999;
-const WORK_ITEMS_PER_PAGE = 100;
-// Plane's list endpoints on large projects (with expand=state) routinely
-// take 10–15s to respond — we'd hit our previous 10s cap and start a chain
-// of retries before the original request even finished. 20s comfortably
-// fits the slowest projects in observed traffic without making real
-// failures (DNS issues, network down) drag too long.
-const REQUEST_TIMEOUT_MS = 20_000;
-const MAX_RETRIES = 2;
-const RETRY_BASE_DELAY_MS = 400;
-const STATES_CACHE_TTL_MS = 60 * 60 * 1000; // 1 hour
-// Cap retry-after at this — we don't want to freeze the dashboard for a minute
-// because Plane is being overly defensive. Beyond this we just give up.
-const RETRY_AFTER_CAP_MS = 5_000;
-const MIN_REQUEST_INTERVAL_MS = 300;
-const USER_ID_CACHE_TTL_MS = 60 * 60 * 1000; // 1 hour
-const EMPTY_PROJECT_TTL_MS = 30 * 60 * 1000; // 30 minutes
-const statesCache = new Map();
-function statesCacheKey(workspaceSlug, projectId) {
-    return `${workspaceSlug}\x00${projectId}`;
-}
-function readStatesCache(workspaceSlug, projectId) {
-    const entry = statesCache.get(statesCacheKey(workspaceSlug, projectId));
-    if (!entry)
-        return null;
-    if (Date.now() - entry.fetchedAt > STATES_CACHE_TTL_MS) {
-        statesCache.delete(statesCacheKey(workspaceSlug, projectId));
-        return null;
-    }
-    return entry.states;
-}
-function writeStatesCache(workspaceSlug, projectId, states) {
-    statesCache.set(statesCacheKey(workspaceSlug, projectId), {
-        states,
-        fetchedAt: Date.now(),
-    });
-}
-// Module-level cache for the current user's id. /users/me/ is otherwise
-// fetched on every dashboard refresh (each one constructs a new
-// PlaneProvider); caching it for an hour drops the per-refresh call count
-// by one and avoids triggering rate limits when many refreshes pile up.
-let cachedUserIdEntry = null;
-function readCachedUserId() {
-    if (!cachedUserIdEntry)
-        return null;
-    if (Date.now() - cachedUserIdEntry.fetchedAt > USER_ID_CACHE_TTL_MS) {
-        cachedUserIdEntry = null;
-        return null;
-    }
-    return cachedUserIdEntry.id;
-}
-function writeCachedUserId(id) {
-    cachedUserIdEntry = { id, fetchedAt: Date.now() };
-}
-// Tracks projects that returned zero assigned items on the last successful
-// fetch — we skip their work-items endpoint on subsequent refreshes for a
-// while. This is the single biggest win against Plane's rate limit when the
-// user has many configured projects but only contributes to a few. New
-// assignments get picked up after the TTL expires.
-const emptyProjectsCache = new Map();
-function emptyKey(workspaceSlug, projectId) {
-    return `${workspaceSlug}\x00${projectId}`;
-}
-function isKnownEmptyProject(workspaceSlug, projectId) {
-    const entry = emptyProjectsCache.get(emptyKey(workspaceSlug, projectId));
-    if (!entry)
-        return false;
-    if (Date.now() - entry.fetchedAt > EMPTY_PROJECT_TTL_MS) {
-        emptyProjectsCache.delete(emptyKey(workspaceSlug, projectId));
-        return false;
-    }
-    return true;
-}
-function markProjectEmpty(workspaceSlug, projectId) {
-    emptyProjectsCache.set(emptyKey(workspaceSlug, projectId), { fetchedAt: Date.now() });
-}
-function clearProjectEmpty(workspaceSlug, projectId) {
-    emptyProjectsCache.delete(emptyKey(workspaceSlug, projectId));
-}
-// Process-global throttle: serialises all Plane HTTP requests with a minimum
-// gap between them. Without this, parallel calls inside loadDashboard burst
-// past Plane's per-second cap and end up retrying for tens of seconds. With
-// a 300ms gap, 14 calls take ~4 seconds in the worst case — well within the
-// dashboard's tolerable response time, and well under any reasonable rate
-// limit.
-let throttleQueue = Promise.resolve();
-let lastRequestAt = 0;
-function throttle() {
-    const wait = throttleQueue.then(async () => {
-        const elapsed = Date.now() - lastRequestAt;
-        if (elapsed < MIN_REQUEST_INTERVAL_MS) {
-            await sleep(MIN_REQUEST_INTERVAL_MS - elapsed);
-        }
-        lastRequestAt = Date.now();
-    });
-    throttleQueue = wait;
-    return wait;
-}
-const DEBUG_LOG_PATH = path.join(os.homedir(), ".mintree", "plane-debug.log");
-/**
- * Set `MINTREE_DEBUG=1` to enable Plane HTTP debug logging to
- * `~/.mintree/plane-debug.log`. Always-on stderr/stdout would corrupt the
- * Ink-rendered dashboard, so the log is file-only and opt-in.
- */
-function debugEnabled() {
-    const v = process.env["MINTREE_DEBUG"];
-    return v === "1" || v === "true";
-}
-function logDebug(message) {
-    if (!debugEnabled())
-        return;
-    try {
-        const dir = path.dirname(DEBUG_LOG_PATH);
-        if (!fs.existsSync(dir))
-            fs.mkdirSync(dir, { recursive: true });
-        fs.appendFileSync(DEBUG_LOG_PATH, `[${new Date().toISOString()}] ${message}\n`);
-    }
-    catch {
-        // Logging never crashes the dashboard.
-    }
-}
-function isRetryableStatus(status) {
-    // 0  → AbortError / network timeout / DNS / TLS
-    // 429 → rate-limited
-    // 5xx → server error
-    return status === 0 || status === 429 || (status >= 500 && status < 600);
-}
-function sleep(ms) {
-    return new Promise((resolve) => setTimeout(resolve, ms));
-}
-/**
- * Plucks the array of items out of a Plane list response. Tolerates three
- * shapes seen in the wild:
- *   - { results: [...] }   — the paginated work-items / projects endpoints
- *   - { result: [...] }    — the /states/ endpoint
- *   - [ ... ]              — bare array (some non-paginated endpoints)
- */
-function extractList(data) {
-    if (Array.isArray(data))
-        return data;
-    if (data && typeof data === "object") {
-        const d = data;
-        if (Array.isArray(d.results))
-            return d.results;
-        if (Array.isArray(d.result))
-            return d.result;
-    }
-    return [];
-}
-function extractCursor(data) {
-    if (data && typeof data === "object") {
-        const d = data;
-        if (typeof d.next_cursor === "string")
-            return d.next_cursor;
-    }
-    return null;
-}
-function resolveApiKey() {
-    const env = process.env["PLANE_API_KEY"];
-    if (env && env.length > 0)
-        return env;
-    const credsPath = path.join(os.homedir(), ".mintree", "credentials.json");
-    try {
-        if (!fs.existsSync(credsPath))
-            return null;
-        const parsed = JSON.parse(fs.readFileSync(credsPath, "utf-8"));
-        const k = parsed?.plane?.apiKey;
-        return typeof k === "string" && k.length > 0 ? k : null;
-    }
-    catch {
-        return null;
-    }
-}
-async function doPlaneRequest(apiUrl, apiKey, method, endpoint, body) {
-    await throttle();
-    const url = `${apiUrl.replace(/\/$/, "")}${endpoint}`;
-    const controller = new AbortController();
-    const timer = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS);
-    try {
-        const res = await fetch(url, {
-            method,
-            headers: {
-                "X-API-Key": apiKey,
-                "Content-Type": "application/json",
-                Accept: "application/json",
-            },
-            body: body !== undefined ? JSON.stringify(body) : undefined,
-            signal: controller.signal,
-        });
-        clearTimeout(timer);
-        if (!res.ok) {
-            const text = await res.text().catch(() => "");
-            const failure = interpretHttpError(res.status, text);
-            // Pull a Retry-After header if Plane sent one — it can be either a
-            // number of seconds or an HTTP date. We only honour the seconds
-            // form (the date form is virtually never used by JSON APIs).
-            if (res.status === 429) {
-                const ra = res.headers.get("retry-after");
-                if (ra) {
-                    const seconds = Number(ra);
-                    if (Number.isFinite(seconds) && seconds > 0) {
-                        failure.retryAfterMs = Math.min(seconds * 1000, RETRY_AFTER_CAP_MS);
-                    }
-                }
-            }
-            return failure;
-        }
-        // 204 No Content — return empty object as T (callers shouldn't rely on
-        // shape when they know the response is empty).
-        if (res.status === 204)
-            return { ok: true, data: {} };
-        const data = (await res.json());
-        return { ok: true, data };
-    }
-    catch (err) {
-        clearTimeout(timer);
-        if (err instanceof Error && err.name === "AbortError") {
-            return { ok: false, status: 0, error: "Plane API request timed out" };
-        }
-        return {
-            ok: false,
-            status: 0,
-            error: err instanceof Error ? err.message : String(err),
-        };
-    }
-}
-/**
- * Calls the Plane API with retry on transient errors. Retries up to
- * MAX_RETRIES times on 429 (rate-limited), 5xx (server error), and status
- * 0 (network timeout / abort). Permanent errors (401, 403, 404) are
- * returned immediately. Every failure path writes to the debug log when
- * MINTREE_DEBUG=1.
- *
- * The backoff is exponential with a tiny base (400ms → 800ms) so a brief
- * rate-limit window passes without making the dashboard feel sluggish.
- * Plane's published rate limits aren't aggressive; this is a safety net
- * for occasional bursts, not a workaround for sustained over-fetching.
- */
-async function planeRequest(apiUrl, apiKey, method, endpoint, body) {
-    let attempt = 0;
-    let lastResult = null;
-    while (attempt <= MAX_RETRIES) {
-        const result = await doPlaneRequest(apiUrl, apiKey, method, endpoint, body);
-        if (result.ok) {
-            if (attempt > 0) {
-                logDebug(`recovered ${method} ${endpoint} after ${attempt} retry/retries`);
-            }
-            return result;
-        }
-        lastResult = result;
-        if (!isRetryableStatus(result.status) || attempt === MAX_RETRIES) {
-            logDebug(`failed ${method} ${endpoint} status=${result.status} error=${result.error}${result.hint ? ` hint=${result.hint}` : ""}`);
-            return result;
-        }
-        // Prefer the server-supplied Retry-After when present; fall back to
-        // exponential backoff. Capping is already applied when the header is
-        // parsed in doPlaneRequest.
-        const delay = result.retryAfterMs !== undefined
-            ? result.retryAfterMs
-            : RETRY_BASE_DELAY_MS * Math.pow(2, attempt);
-        logDebug(`retry ${attempt + 1}/${MAX_RETRIES} after ${delay}ms ${method} ${endpoint} (last status=${result.status}${result.retryAfterMs !== undefined ? ", server-Retry-After" : ""})`);
-        await sleep(delay);
-        attempt += 1;
-    }
-    // Defensive — loop above always returns inside.
-    return (lastResult ?? {
-        ok: false,
-        status: 0,
-        error: "planeRequest exhausted retries with no recorded error",
-    });
-}
-function interpretHttpError(status, body) {
-    if (status === 401 || status === 403) {
-        return {
-            ok: false,
-            status,
-            error: "Plane rejected the API key (401/403).",
-            hint: "Verify PLANE_API_KEY or ~/.mintree/credentials.json#plane.apiKey",
-        };
-    }
-    if (status === 404) {
-        return {
-            ok: false,
-            status,
-            error: "Plane workspace or project not found (404).",
-            hint: "Check workspaceSlug and projects[].id in .mintree/metadata.json",
-        };
-    }
-    const snippet = body.slice(0, 200).replace(/\s+/g, " ").trim();
-    return {
-        ok: false,
-        status,
-        error: snippet || `Plane API responded with HTTP ${status}`,
-    };
-}
-function toIssueId(project, sequence) {
-    return `${project.identifier}-${sequence}`;
-}
-function normaliseAssignees(raw) {
-    if (!raw)
-        return [];
-    const out = [];
-    for (const a of raw) {
-        if (typeof a === "string") {
-            out.push(a);
-        }
-        else if (a && typeof a === "object") {
-            if (typeof a.id === "string")
-                out.push(a.id);
-            if (typeof a.member === "string")
-                out.push(a.member);
-        }
-    }
-    return out;
-}
-function normaliseState(raw) {
-    if (!raw)
-        return null;
-    if (typeof raw === "string")
-        return { id: raw };
-    if (typeof raw === "object" && typeof raw.id === "string") {
-        return { id: raw.id, name: raw.name, group: raw.group };
-    }
-    return null;
-}
-function mapWorkItemToProviderIssue(project, workspaceSlug, wi) {
-    const labels = [];
-    if (Array.isArray(wi.labels)) {
-        for (const l of wi.labels) {
-            if (typeof l === "string")
-                labels.push({ name: l });
-            else if (l && typeof l === "object" && typeof l.name === "string")
-                labels.push({ name: l.name });
-        }
-    }
-    const state = normaliseState(wi.state);
-    const url = `https://app.plane.so/${workspaceSlug}/browse/${project.identifier}-${wi.sequence_id}/`;
-    return {
-        id: toIssueId(project, wi.sequence_id),
-        title: wi.name,
-        state: state?.name ?? "",
-        url,
-        labels,
-        body: wi.description_stripped ?? wi.description_html ?? wi.description ?? "",
-        createdAt: wi.created_at ?? "",
-        updatedAt: wi.updated_at ?? "",
-    };
-}
-export class PlaneProvider {
-    repoRoot;
-    kind = "plane";
-    cachedUserId = null;
-    // Per-instance cache so the dashboard's back-to-back listAssignedIssues +
-    // fetchProjectAssignments don't double-fetch the work items. Keyed by
-    // project.id. Resets each time createProvider() is called.
-    workItemsByProject = null;
-    statesByProject = null;
-    constructor(repoRoot) {
-        this.repoRoot = repoRoot;
-    }
-    getConfig() {
-        return readMetadata(this.repoRoot).plane ?? null;
-    }
-    async getUserId(apiUrl, apiKey) {
-        // Instance cache first (within a load), then module-level cache (across
-        // loads). /users/me/ is otherwise the most-called endpoint after work-
-        // items because every refresh built a new PlaneProvider.
-        if (this.cachedUserId)
-            return this.cachedUserId;
-        const fromModule = readCachedUserId();
-        if (fromModule) {
-            this.cachedUserId = fromModule;
-            return fromModule;
-        }
-        const r = await planeRequest(apiUrl, apiKey, "GET", "/api/v1/users/me/");
-        if (!r.ok)
-            return null;
-        this.cachedUserId = r.data.id;
-        writeCachedUserId(r.data.id);
-        return r.data.id;
-    }
-    async fetchAssignedWorkItems(apiUrl, apiKey, workspaceSlug, projectId, userId) {
-        if (this.workItemsByProject?.has(projectId)) {
-            return this.workItemsByProject.get(projectId);
-        }
-        // Skip projects that were empty last time we successfully fetched
-        // them. Cuts the call count dramatically for users who have many
-        // projects configured but only contribute to a few. The cache
-        // expires after EMPTY_PROJECT_TTL_MS so new assignments still get
-        // picked up.
-        if (isKnownEmptyProject(workspaceSlug, projectId)) {
-            if (!this.workItemsByProject)
-                this.workItemsByProject = new Map();
-            this.workItemsByProject.set(projectId, []);
-            return [];
-        }
-        const items = [];
-        let cursor = null;
-        // Hard cap to keep us safe from accidentally walking a 10k-item project.
-        // 5 pages × 100 = 500 items is plenty for "issues assigned to me".
-        const maxPages = 5;
-        let pages = 0;
-        do {
-            const qs = new URLSearchParams({
-                per_page: String(WORK_ITEMS_PER_PAGE),
-                // expand=state turns the `state` UUID into a full object with
-                // name/group/color (no extra API call needed). expand=labels
-                // does the same for labels — without it the labels field is
-                // just an array of UUIDs and the dashboard renders `[uuid]`
-                // instead of `[name]` in the issue detail pane.
-                expand: "state,labels",
-            });
-            if (cursor)
-                qs.set("cursor", cursor);
-            const endpoint = `/api/v1/workspaces/${encodeURIComponent(workspaceSlug)}/projects/${encodeURIComponent(projectId)}/work-items/?${qs.toString()}`;
-            const r = await planeRequest(apiUrl, apiKey, "GET", endpoint);
-            if (!r.ok)
-                return null;
-            const page = extractList(r.data);
-            for (const wi of page) {
-                const assignees = normaliseAssignees(wi.assignees);
-                if (!assignees.includes(userId))
-                    continue;
-                items.push(wi);
-            }
-            cursor = extractCursor(r.data);
-            pages += 1;
-        } while (cursor && pages < maxPages);
-        if (!this.workItemsByProject)
-            this.workItemsByProject = new Map();
-        this.workItemsByProject.set(projectId, items);
-        // Remember which projects had zero assignments for us — next refresh
-        // can skip them entirely. Successful but non-empty fetches clear
-        // any stale "empty" marker so we don't get stuck thinking a project
-        // is empty after a new assignment lands.
-        if (items.length === 0) {
-            markProjectEmpty(workspaceSlug, projectId);
-        }
-        else {
-            clearProjectEmpty(workspaceSlug, projectId);
-        }
-        return items;
-    }
-    async fetchStates(apiUrl, apiKey, workspaceSlug, projectId) {
-        // Instance cache first — fastest path.
-        if (this.statesByProject?.has(projectId)) {
-            return this.statesByProject.get(projectId);
-        }
-        // Then the cross-instance module-level cache. Workflow states rarely
-        // change, so a 1-hour TTL is plenty and saves an entire fetch per
-        // project on every dashboard refresh.
-        const cached = readStatesCache(workspaceSlug, projectId);
-        if (cached) {
-            if (!this.statesByProject)
-                this.statesByProject = new Map();
-            this.statesByProject.set(projectId, cached);
-            return cached;
-        }
-        const endpoint = `/api/v1/workspaces/${encodeURIComponent(workspaceSlug)}/projects/${encodeURIComponent(projectId)}/states/?per_page=100`;
-        const r = await planeRequest(apiUrl, apiKey, "GET", endpoint);
-        if (!r.ok)
-            return null;
-        const sorted = extractList(r.data).sort((a, b) => (a.sequence ?? 0) - (b.sequence ?? 0));
-        if (!this.statesByProject)
-            this.statesByProject = new Map();
-        this.statesByProject.set(projectId, sorted);
-        writeStatesCache(workspaceSlug, projectId, sorted);
-        return sorted;
-    }
-    async listAssignedIssues() {
-        const cfg = this.getConfig();
-        if (!cfg || cfg.projects.length === 0)
-            return [];
-        const apiKey = resolveApiKey();
-        if (!apiKey)
-            return null;
-        const apiUrl = cfg.apiUrl ?? DEFAULT_API_URL;
-        const userId = await this.getUserId(apiUrl, apiKey);
-        if (!userId)
-            return null;
-        // Per-project failures shouldn't blow up the entire dashboard — a
-        // transient HTTP error in one project would otherwise drop the user
-        // back to the error screen even when the other 6 projects are fine.
-        // Collect successful projects, count failures, and only null out when
-        // EVERY configured project failed.
-        const out = [];
-        let failed = 0;
-        const protectedGroups = new Set(cfg.protectedStateGroups ?? DEFAULT_PROTECTED_STATE_GROUPS);
-        for (const project of cfg.projects) {
-            const items = await this.fetchAssignedWorkItems(apiUrl, apiKey, cfg.workspaceSlug, project.id, userId);
-            if (items === null) {
-                failed += 1;
-                continue;
-            }
-            // Drop work items in completed/cancelled groups — dashboard only shows
-            // open work. Same intent as `gh issue list --state open`.
-            for (const wi of items) {
-                const state = normaliseState(wi.state);
-                if (state?.group && protectedGroups.has(state.group))
-                    continue;
-                out.push(mapWorkItemToProviderIssue(project, cfg.workspaceSlug, wi));
-            }
-        }
-        if (failed === cfg.projects.length)
-            return null;
-        return out;
-    }
-    async fetchProjectAssignments() {
-        const result = new Map();
-        const cfg = this.getConfig();
-        if (!cfg || cfg.projects.length === 0)
-            return result;
-        const apiKey = resolveApiKey();
-        if (!apiKey)
-            return null;
-        const apiUrl = cfg.apiUrl ?? DEFAULT_API_URL;
-        const userId = await this.getUserId(apiUrl, apiKey);
-        if (!userId)
-            return null;
-        // Track per-project failures so we can distinguish "all states fetches
-        // failed" (return null → caller treats as load failure, keeps last-good
-        // state) from "everything succeeded but the user has no work in any
-        // project" (return empty map). Without this distinction a transient
-        // Plane API hiccup silently drops project headers from the dashboard.
-        let succeededAtLeastOne = false;
-        for (const project of cfg.projects) {
-            const states = await this.fetchStates(apiUrl, apiKey, cfg.workspaceSlug, project.id);
-            if (!states)
-                continue;
-            succeededAtLeastOne = true;
-            const stateById = new Map(states.map((s, idx) => [s.id, { state: s, order: idx }]));
-            const items = await this.fetchAssignedWorkItems(apiUrl, apiKey, cfg.workspaceSlug, project.id, userId);
-            if (!items)
-                continue;
-            const projectTitle = project.name ?? project.identifier;
-            const projectUrl = `https://app.plane.so/${cfg.workspaceSlug}/projects/${project.id}/`;
-            for (const wi of items) {
-                const state = normaliseState(wi.state);
-                const lookup = state ? stateById.get(state.id) : undefined;
-                const issueId = toIssueId(project, wi.sequence_id);
-                result.set(issueId, {
-                    projectTitle,
-                    projectUrl,
-                    projectNumber: 0,
-                    status: lookup?.state.name ?? state?.name ?? null,
-                    statusColor: lookup?.state.color ?? "yellow",
-                    statusOrder: lookup?.order ?? STATUS_ORDER_UNSET,
-                });
-            }
-        }
-        if (!succeededAtLeastOne)
-            return null;
-        return result;
-    }
-    async transitionIssueToInProgress(issueId) {
-        const cfg = this.getConfig();
-        if (!cfg) {
-            return {
-                kind: "error",
-                message: "Plane config missing in .mintree/metadata.json",
-                hint: "Run `mintree init --provider plane --workspace <slug>` first",
-            };
-        }
-        const apiKey = resolveApiKey();
-        if (!apiKey) {
-            return {
-                kind: "error",
-                message: "PLANE_API_KEY not set",
-                hint: "export PLANE_API_KEY=<your key> (or write ~/.mintree/credentials.json)",
-            };
-        }
-        const apiUrl = cfg.apiUrl ?? DEFAULT_API_URL;
-        const dash = issueId.lastIndexOf("-");
-        if (dash <= 0)
-            return { kind: "skip-no-issue" };
-        const identifier = issueId.slice(0, dash);
-        const sequence = Number(issueId.slice(dash + 1));
-        if (!Number.isFinite(sequence))
-            return { kind: "skip-no-issue" };
-        const project = cfg.projects.find((p) => p.identifier === identifier);
-        if (!project)
-            return { kind: "skip-no-project" };
-        const userId = await this.getUserId(apiUrl, apiKey);
-        if (!userId) {
-            return {
-                kind: "error",
-                message: "Could not resolve current user from Plane API",
-                hint: "Check that the API key has access to the workspace",
-            };
-        }
-        const states = await this.fetchStates(apiUrl, apiKey, cfg.workspaceSlug, project.id);
-        if (!states) {
-            return { kind: "error", message: `Could not fetch states for project ${project.identifier}` };
-        }
-        const targetStateName = cfg.inProgressStateName;
-        let targetState = targetStateName ? states.find((s) => s.name === targetStateName) : undefined;
-        if (!targetState)
-            targetState = states.find((s) => s.group === "started");
-        if (!targetState) {
-            return {
-                kind: "skip-no-in-progress-option",
-                projects: [project.name ?? project.identifier],
-            };
-        }
-        const items = await this.fetchAssignedWorkItems(apiUrl, apiKey, cfg.workspaceSlug, project.id, userId);
-        if (!items) {
-            return { kind: "error", message: `Could not fetch work items for ${project.identifier}` };
-        }
-        const workItem = items.find((w) => w.sequence_id === sequence);
-        if (!workItem)
-            return { kind: "skip-no-issue" };
-        const protectedGroups = new Set(cfg.protectedStateGroups ?? DEFAULT_PROTECTED_STATE_GROUPS);
-        const currentState = normaliseState(workItem.state);
-        if (currentState) {
-            if (currentState.id === targetState.id) {
-                return { kind: "noop-already", projectTitle: project.name ?? project.identifier };
-            }
-            if (currentState.group && protectedGroups.has(currentState.group)) {
-                return {
-                    kind: "noop-protected",
-                    projectTitle: project.name ?? project.identifier,
-                    current: currentState.name ?? currentState.group,
-                };
-            }
-        }
-        const patchEndpoint = `/api/v1/workspaces/${encodeURIComponent(cfg.workspaceSlug)}/projects/${encodeURIComponent(project.id)}/work-items/${encodeURIComponent(workItem.id)}/`;
-        const patch = await planeRequest(apiUrl, apiKey, "PATCH", patchEndpoint, {
-            state: targetState.id,
-        });
-        if (!patch.ok) {
-            return {
-                kind: "error",
-                message: patch.error,
-                ...(patch.hint ? { hint: patch.hint } : {}),
-            };
-        }
-        // Cache invalidation — the work item's state changed, so subsequent
-        // queries within this process should see fresh data. Wipes the per-
-        // project work-item cache; the next call refetches.
-        this.workItemsByProject?.delete(project.id);
-        return {
-            kind: "transitioned",
-            projectTitle: project.name ?? project.identifier,
-            from: currentState?.name ?? null,
-            to: targetState.name,
-        };
-    }
-}
-export async function checkPlaneSetup(repoRoot) {
-    const cfg = readMetadata(repoRoot).plane;
-    if (!cfg) {
-        return {
-            configured: false,
-            hasApiKey: false,
-            authOk: false,
-            projects: [],
-            hint: "Plane not configured. Run: mintree init --provider plane --workspace <slug>",
-        };
-    }
-    const apiUrl = cfg.apiUrl ?? DEFAULT_API_URL;
-    const apiKey = resolveApiKey();
-    if (!apiKey) {
-        return {
-            configured: true,
-            hasApiKey: false,
-            authOk: false,
-            workspaceSlug: cfg.workspaceSlug,
-            apiUrl,
-            projects: cfg.projects.map((p) => ({ identifier: p.identifier, id: p.id, ok: false })),
-            hint: "export PLANE_API_KEY=<key> or populate ~/.mintree/credentials.json#plane.apiKey",
-        };
-    }
-    const me = await planeRequest(apiUrl, apiKey, "GET", "/api/v1/users/me/");
-    if (!me.ok) {
-        return {
-            configured: true,
-            hasApiKey: true,
-            authOk: false,
-            workspaceSlug: cfg.workspaceSlug,
-            apiUrl,
-            projects: cfg.projects.map((p) => ({ identifier: p.identifier, id: p.id, ok: false })),
-            hint: me.hint ?? me.error,
-        };
-    }
-    // Probe each configured project so the row can show per-project
-    // reachability — most common misconfig is a wrong project UUID. Done
-    // sequentially to keep the doctor's output deterministic.
-    const projectResults = [];
-    let allProjectsOk = true;
-    for (const p of cfg.projects) {
-        const endpoint = `/api/v1/workspaces/${encodeURIComponent(cfg.workspaceSlug)}/projects/${encodeURIComponent(p.id)}/`;
-        const r = await planeRequest(apiUrl, apiKey, "GET", endpoint);
-        if (r.ok) {
-            projectResults.push({ identifier: p.identifier, id: p.id, ok: true });
-        }
-        else {
-            allProjectsOk = false;
-            projectResults.push({
-                identifier: p.identifier,
-                id: p.id,
-                ok: false,
-                error: r.hint ?? r.error,
-            });
-        }
-    }
-    const noProjects = cfg.projects.length === 0;
-    return {
-        configured: true,
-        hasApiKey: true,
-        authOk: true,
-        user: me.data.display_name ?? me.data.email ?? me.data.id,
-        workspaceSlug: cfg.workspaceSlug,
-        apiUrl,
-        projects: projectResults,
-        hint: noProjects
-            ? "No projects configured. Add at least one to .mintree/metadata.json#plane.projects[]"
-            : !allProjectsOk
-                ? "One or more configured projects could not be reached — check projects[].id"
-                : undefined,
-    };
-}