mintree 0.1.10 → 0.2.0

package/dist/lib/dashboard.js

@@ -1,43 +1,22 @@
 import * as fs from "fs";
 import * as path from "path";
-import { execFile } from "child_process";
-import { promisify } from "util";
-import { tryExec } from "./exec.js";
 import { listWorktrees, getWorktreesDir, isDirty, getAheadBehind, } from "./git.js";
 import { readMetadata } from "./metadata.js";
-import { getRepoFullName } from "./github.js";
-const execFileAsync = promisify(execFile);
-const ISSUE_LIST_LIMIT = 50;
+import { fetchPrForBranch } from "./pr.js";
+import { createProvider } from "./providers/index.js";
 /**
- * Fetches open issues assigned to the authenticated GitHub user for the
- * current cwd's repo. Returns null when `gh` isn't authenticated, the cwd
- * isn't a GitHub repo, or the API call fails — the caller surfaces the
- * appropriate hint.
- */
-export async function fetchAssignedIssues() {
-    const json = await tryExec(`gh issue list --assignee @me --state open --json number,title,state,url,labels,body,createdAt,updatedAt --limit ${ISSUE_LIST_LIMIT} 2>/dev/null`);
-    if (!json)
-        return null;
-    try {
-        const parsed = JSON.parse(json);
-        if (!Array.isArray(parsed))
-            return null;
-        return parsed;
-    }
-    catch {
-        return null;
-    }
-}
-/**
- * Builds a map from issue id (number, as string) to the matching mintree
- * worktree. IssueId comes from the worktree dir name (`<issue>-<desc>`)
- * rather than the branch, so detached worktrees (created via the dashboard's
- * "current branch" mode) are included alongside the regular branch-based
- * ones. Worktrees outside `.mintree/worktrees/` are skipped.
+ * Builds a map from issue id (the canonical string — "100" on GitHub,
+ * "BACK-100" on Plane once that lands) to the matching mintree worktree.
+ * IssueId comes from the worktree dir name (`<issue>-<desc>`) rather than
+ * the branch, so detached worktrees (created via the dashboard's "current
+ * branch" mode) are included alongside the regular branch-based ones.
+ * Worktrees outside `.mintree/worktrees/` are skipped.
  */
 function buildWorktreeIndex(repoRoot) {
     const worktreesRoot = path.resolve(getWorktreesDir(repoRoot));
-    const dirNameRegex = /^(\d+)-/;
+    // Same shape as the BRANCH_REGEX issueId capture: bare digits (GitHub) or
+    // `<PROJ>-\d+` (Plane). Matches `100-foo` and `BACK-100-foo` alike.
+    const dirNameRegex = /^((?:[A-Z][A-Z0-9_]*-)?\d+)-/;
     const index = new Map();
     for (const w of listWorktrees(repoRoot)) {
         const wAbs = path.resolve(w.path);
@@ -84,153 +63,6 @@ function readSessionState(repoRoot, issueId) {
 function isSessionState(v) {
     return v === "active" || v === "idle" || v === "waiting" || v === "exited";
 }
-function shQuote(value) {
-    return `'${value.replace(/'/g, `'\\''`)}'`;
-}
-/**
- * Looks up the most recent PR for a branch (any state). Returns null when
- * there's no PR or `gh` can't reach the API. Used to populate the detail
- * pane's "Pull Request" section.
- */
-async function fetchPrForBranch(branch) {
-    const out = await tryExec(`gh pr list --head ${shQuote(branch)} --state all --json number,state,url --limit 1 2>/dev/null`);
-    if (!out)
-        return null;
-    try {
-        const arr = JSON.parse(out);
-        if (Array.isArray(arr) && arr.length > 0 && arr[0])
-            return arr[0];
-    }
-    catch {
-        // fall through
-    }
-    return null;
-}
-// GitHub Projects v2 single-select options carry their own colour enum.
-// Map each to the closest Ink/chalk colour; ORANGE and PINK have no 16-colour
-// keyword so they use hex (truecolor terminals render them, others approximate).
-const PROJECT_STATUS_COLORS = {
-    GRAY: "gray",
-    BLUE: "blue",
-    GREEN: "green",
-    YELLOW: "yellow",
-    ORANGE: "#d18616",
-    RED: "red",
-    PINK: "#d2a8ff",
-    PURPLE: "magenta",
-};
-const STATUS_ORDER_UNSET = 999;
-function parseProjectNumberFromUrl(url) {
-    const m = url.match(/\/projects\/(\d+)/);
-    return m && m[1] ? Number(m[1]) : null;
-}
-/**
- * Runs a GraphQL query via `gh api graphql`. Returns null on any failure
- * (gh not authenticated, missing scope, network) — the caller degrades
- * gracefully to an ungrouped list.
- */
-async function ghGraphql(query) {
-    try {
-        const { stdout } = await execFileAsync("gh", ["api", "graphql", "-f", `query=${query}`]);
-        return JSON.parse(stdout);
-    }
-    catch {
-        return null;
-    }
-}
-/**
- * Picks which project board an issue belongs to for grouping purposes. When
- * `.mintree/metadata.json` pins a project URL, only that board counts;
- * otherwise the first board the issue appears on wins.
- */
-function pickProjectNode(nodes, configuredUrl) {
-    if (nodes.length === 0)
-        return null;
-    if (configuredUrl) {
-        const targetNumber = parseProjectNumberFromUrl(configuredUrl);
-        return (nodes.find((n) => n.project?.url === configuredUrl ||
-            (targetNumber !== null && n.project?.number === targetNumber)) ?? null);
-    }
-    return nodes[0] ?? null;
-}
-function toProjectInfo(node) {
-    const proj = node.project;
-    if (!proj)
-        return null;
-    const options = proj.field?.options ?? [];
-    const status = node.fieldValueByName?.name ?? null;
-    const optionIndex = status ? options.findIndex((o) => o.name === status) : -1;
-    const option = optionIndex >= 0 ? options[optionIndex] : undefined;
-    return {
-        projectTitle: proj.title ?? "(untitled project)",
-        projectUrl: proj.url ?? "",
-        projectNumber: proj.number ?? 0,
-        status,
-        statusColor: option?.color
-            ? (PROJECT_STATUS_COLORS[option.color] ?? "yellow")
-            : status
-                ? "yellow"
-                : "gray",
-        statusOrder: optionIndex >= 0 ? optionIndex : STATUS_ORDER_UNSET,
-    };
-}
-/**
- * Fetches, in a single GraphQL round-trip, which Projects v2 board (and
- * Status value) each open assigned issue belongs to. Returns an empty map
- * when the lookup fails — the dashboard then renders an ungrouped list.
- */
-async function fetchProjectAssignments(statusFieldName, configuredUrl) {
-    const result = new Map();
-    const repo = await getRepoFullName();
-    if (!repo)
-        return result;
-    // The Status field name is interpolated into the query (not a variable)
-    // because it appears as a field argument; escape embedded quotes.
-    const escapedField = statusFieldName.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
-    const searchQuery = `repo:${repo} is:issue is:open assignee:@me`.replace(/"/g, '\\"');
-    const query = `query {
-  search(query: "${searchQuery}", type: ISSUE, first: ${ISSUE_LIST_LIMIT}) {
-    nodes {
-      ... on Issue {
-        number
-        projectItems(first: 10, includeArchived: false) {
-          nodes {
-            project {
-              title
-              number
-              url
-              field(name: "${escapedField}") {
-                ... on ProjectV2SingleSelectField {
-                  options { name color }
-                }
-              }
-            }
-            fieldValueByName(name: "${escapedField}") {
-              ... on ProjectV2ItemFieldSingleSelectValue { name }
-            }
-          }
-        }
-      }
-    }
-  }
-}`;
-    const raw = (await ghGraphql(query));
-    const nodes = raw?.data?.search?.nodes;
-    if (!Array.isArray(nodes))
-        return result;
-    for (const node of nodes) {
-        if (typeof node?.number !== "number")
-            continue;
-        const items = node.projectItems?.nodes ?? [];
-        const picked = pickProjectNode(items, configuredUrl);
-        if (!picked)
-            continue;
-        const info = toProjectInfo(picked);
-        if (info)
-            result.set(node.number, info);
-    }
-    return result;
-}
 /**
  * Orders the flat issue list so issues are contiguous by project, then by
  * Status (board column order), then newest issue first. The dashboard derives
@@ -260,7 +92,14 @@ function sortGroupedIssues(issues, configuredUrl) {
                 return a.project.statusOrder - b.project.statusOrder;
             }
         }
-        return b.issue.number - a.issue.number;
+        // Newest-first for issues — id is a numeric-or-prefixed string. Numeric
+        // compare falls back to localeCompare for non-numeric ids (Plane's
+        // "BACK-100" form).
+        const an = Number(a.issue.id);
+        const bn = Number(b.issue.id);
+        if (Number.isFinite(an) && Number.isFinite(bn))
+            return bn - an;
+        return b.issue.id.localeCompare(a.issue.id);
     });
 }
 /**
@@ -269,7 +108,8 @@ function sortGroupedIssues(issues, configuredUrl) {
  * `r` refresh — cheap because all the per-worktree probes are local.
  */
 export async function loadDashboard(repoRoot) {
-    const issues = await fetchAssignedIssues();
+    const provider = createProvider(repoRoot);
+    const issues = await provider.listAssignedIssues();
     if (!issues)
         return null;
     const worktreesByIssue = buildWorktreeIndex(repoRoot);
@@ -288,24 +128,28 @@ export async function loadDashboard(repoRoot) {
         if (pr)
             prByBranch.set(w.branch, pr);
     });
-    // Project membership comes from a single GraphQL query; fetch it alongside
-    // the per-branch PR probes so neither blocks the other.
+    // Project membership comes from the provider in a single call; fetch it
+    // alongside the per-branch PR probes so neither blocks the other.
     const [, projectByIssue] = await Promise.all([
         Promise.all(prFetches),
-        fetchProjectAssignments(projectCfg.statusField ?? "Status", configuredUrl),
+        provider.fetchProjectAssignments(),
     ]);
+    // Provider signals total failure (vs no projects configured) with null —
+    // treat as a partial load failure so the caller's resilient refresh
+    // keeps the last-good state instead of regressing to a flat list.
+    if (projectByIssue === null)
+        return null;
     const enriched = issues.map((issue) => {
-        const issueId = String(issue.number);
-        const worktreeRaw = worktreesByIssue.get(issueId) ?? null;
-        const sessionId = metadata.issues[issueId]?.session_id;
+        const worktreeRaw = worktreesByIssue.get(issue.id) ?? null;
+        const sessionId = metadata.issues[issue.id]?.session_id;
         const worktree = worktreeRaw ? { ...worktreeRaw, sessionId } : null;
         const pr = worktree && worktree.branch ? (prByBranch.get(worktree.branch) ?? null) : null;
         return {
             issue,
             worktree,
-            session: readSessionState(repoRoot, issueId),
+            session: readSessionState(repoRoot, issue.id),
             pr,
-            project: projectByIssue.get(issue.number) ?? null,
+            project: projectByIssue.get(issue.id) ?? null,
         };
     });
     return sortGroupedIssues(enriched, configuredUrl);

package/dist/lib/gh.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Thin shell helpers around the `gh` CLI. These are deliberately
+ * provider-agnostic — even when mintree's issue provider is Plane, `gh` is
+ * still used to look up PR status for worktree branches, so doctor and a
+ * couple of dashboard surfaces need to know whether `gh` is reachable.
+ *
+ * The GitHub issue / Project v2 logic lives in `providers/github.ts` and
+ * uses these helpers internally; the Plane provider doesn't touch them.
+ */
+export declare function ghCliAvailable(): Promise<boolean>;
+export declare function getGhUserLogin(): Promise<string | null>;
+/**
+ * Returns "owner/name" for the GitHub repo of the current working directory,
+ * or null if not a GitHub repo / `gh` can't reach the API.
+ */
+export declare function getRepoFullName(): Promise<string | null>;

package/dist/lib/{github.js → gh.js}

@@ -1,3 +1,12 @@
+/**
+ * Thin shell helpers around the `gh` CLI. These are deliberately
+ * provider-agnostic — even when mintree's issue provider is Plane, `gh` is
+ * still used to look up PR status for worktree branches, so doctor and a
+ * couple of dashboard surfaces need to know whether `gh` is reachable.
+ *
+ * The GitHub issue / Project v2 logic lives in `providers/github.ts` and
+ * uses these helpers internally; the Plane provider doesn't touch them.
+ */
 import { tryExec } from "./exec.js";
 export async function ghCliAvailable() {
     const out = await tryExec("which gh");

package/dist/lib/metadata.d.ts

@@ -8,10 +8,25 @@ export type ProjectMeta = {
     inProgressOption?: string;
     protectedStatuses?: string[];
 };
+export type ProviderKind = "github" | "plane";
+export type PlaneProjectRef = {
+    id: string;
+    identifier: string;
+    name?: string;
+};
+export type PlaneMeta = {
+    apiUrl?: string;
+    workspaceSlug: string;
+    projects: PlaneProjectRef[];
+    inProgressStateName?: string;
+    protectedStateGroups?: string[];
+};
 export type Metadata = {
     version: 1;
+    provider?: ProviderKind;
     issues: Record<string, IssueMeta>;
     project?: ProjectMeta;
+    plane?: PlaneMeta;
 };
 export declare function readMetadata(repoRoot: string): Metadata;
 export declare function writeMetadata(repoRoot: string, data: Metadata): void;

package/dist/lib/metadata.js

@@ -1,6 +1,53 @@
 import * as fs from "fs";
 import { getMetadataPath } from "./git.js";
 const EMPTY = { version: 1, issues: {} };
+function sanitizeProvider(raw) {
+    if (raw === "github" || raw === "plane")
+        return raw;
+    return undefined;
+}
+function sanitizePlaneProject(raw) {
+    if (typeof raw !== "object" || raw === null)
+        return undefined;
+    const r = raw;
+    if (typeof r["id"] !== "string" || r["id"].length === 0)
+        return undefined;
+    if (typeof r["identifier"] !== "string" || r["identifier"].length === 0)
+        return undefined;
+    const out = { id: r["id"], identifier: r["identifier"] };
+    if (typeof r["name"] === "string" && r["name"].length > 0)
+        out.name = r["name"];
+    return out;
+}
+function sanitizePlane(raw) {
+    if (typeof raw !== "object" || raw === null)
+        return undefined;
+    const r = raw;
+    if (typeof r["workspaceSlug"] !== "string" || r["workspaceSlug"].length === 0)
+        return undefined;
+    const projectsRaw = Array.isArray(r["projects"]) ? r["projects"] : [];
+    const projects = [];
+    for (const p of projectsRaw) {
+        const sanitized = sanitizePlaneProject(p);
+        if (sanitized)
+            projects.push(sanitized);
+    }
+    const out = {
+        workspaceSlug: r["workspaceSlug"],
+        projects,
+    };
+    if (typeof r["apiUrl"] === "string" && r["apiUrl"].length > 0)
+        out.apiUrl = r["apiUrl"];
+    if (typeof r["inProgressStateName"] === "string" && r["inProgressStateName"].length > 0) {
+        out.inProgressStateName = r["inProgressStateName"];
+    }
+    if (Array.isArray(r["protectedStateGroups"])) {
+        const arr = r["protectedStateGroups"].filter((v) => typeof v === "string" && v.length > 0);
+        if (arr.length > 0)
+            out.protectedStateGroups = arr;
+    }
+    return out;
+}
 function sanitizeProject(raw) {
     if (typeof raw !== "object" || raw === null)
         return undefined;
@@ -30,12 +77,16 @@ export function readMetadata(repoRoot) {
         if (typeof parsed !== "object" || parsed === null)
             return { ...EMPTY, issues: {} };
         const project = sanitizeProject(parsed.project);
+        const provider = sanitizeProvider(parsed.provider);
+        const plane = sanitizePlane(parsed.plane);
         return {
             version: 1,
             issues: typeof parsed.issues === "object" && parsed.issues !== null
                 ? parsed.issues
                 : {},
+            ...(provider ? { provider } : {}),
             ...(project ? { project } : {}),
+            ...(plane ? { plane } : {}),
         };
     }
     catch {

package/dist/lib/pr.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Shared `gh pr list` helpers. The dashboard, `worktree list --pr`, and
+ * `worktree clean` all need to look up the PR status of a branch, with the
+ * same `gh pr list --head <branch>` shape. Centralising them here avoids
+ * three copies of the shell-quote + JSON-parse dance going out of sync.
+ *
+ * PR detection stays gh-only even when the issue provider is Plane —
+ * mintree's worktree branches live on GitHub, and Plane has no concept of
+ * git PRs. Callers that aren't sure whether `gh` is available pass through
+ * `tryExec`-style failures as `null`, so the dashboard degrades to "no PR"
+ * rows instead of erroring.
+ */
+export type PrState = "OPEN" | "CLOSED" | "MERGED";
+export type PrInfo = {
+    number: number;
+    state: PrState;
+    url?: string;
+};
+/**
+ * Looks up the most recent PR for a branch (any state). Returns null when
+ * there's no PR or `gh` can't reach the API. `withUrl` controls whether the
+ * URL field is requested — dashboard wants it for display, list/clean don't.
+ */
+export declare function fetchPrForBranch(branch: string, { withUrl }?: {
+    withUrl?: boolean;
+}): Promise<PrInfo | null>;

package/dist/lib/pr.js

@@ -0,0 +1,49 @@
+/**
+ * Shared `gh pr list` helpers. The dashboard, `worktree list --pr`, and
+ * `worktree clean` all need to look up the PR status of a branch, with the
+ * same `gh pr list --head <branch>` shape. Centralising them here avoids
+ * three copies of the shell-quote + JSON-parse dance going out of sync.
+ *
+ * PR detection stays gh-only even when the issue provider is Plane —
+ * mintree's worktree branches live on GitHub, and Plane has no concept of
+ * git PRs. Callers that aren't sure whether `gh` is available pass through
+ * `tryExec`-style failures as `null`, so the dashboard degrades to "no PR"
+ * rows instead of erroring.
+ */
+import { tryExec } from "./exec.js";
+function shQuote(value) {
+    return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+function normaliseState(s) {
+    const u = s.toUpperCase();
+    if (u === "OPEN" || u === "CLOSED" || u === "MERGED")
+        return u;
+    return null;
+}
+/**
+ * Looks up the most recent PR for a branch (any state). Returns null when
+ * there's no PR or `gh` can't reach the API. `withUrl` controls whether the
+ * URL field is requested — dashboard wants it for display, list/clean don't.
+ */
+export async function fetchPrForBranch(branch, { withUrl = true } = {}) {
+    const fields = withUrl ? "number,state,url" : "number,state";
+    const out = await tryExec(`gh pr list --head ${shQuote(branch)} --state all --json ${fields} --limit 1 2>/dev/null`);
+    if (!out)
+        return null;
+    try {
+        const arr = JSON.parse(out);
+        if (!Array.isArray(arr) || arr.length === 0 || !arr[0])
+            return null;
+        const first = arr[0];
+        const state = normaliseState(first.state);
+        if (!state)
+            return null;
+        const result = { number: first.number, state };
+        if (withUrl && first.url)
+            result.url = first.url;
+        return result;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/lib/providers/github.d.ts

@@ -0,0 +1,33 @@
+/**
+ * GithubProvider — implements IssueProvider against GitHub Issues + Projects
+ * v2 via the `gh` CLI. All the GraphQL plumbing that previously lived in
+ * dashboard.ts (project assignment lookup) and githubProject.ts (status
+ * transition) is consolidated here so the rest of mintree can talk to issues
+ * through a stable, provider-agnostic interface.
+ *
+ * Stays gh-CLI-driven (not raw octokit) because gh transparently handles
+ * auth tokens, scope refresh, and the user's preferred login — mintree's
+ * doctor already validates that flow, and not having a second auth path
+ * means there's only one thing to break.
+ */
+import type { IssueId, IssueProjectInfo, IssueProvider, ProviderIssue, TransitionResult } from "./types.js";
+export declare class GithubProvider implements IssueProvider {
+    private readonly repoRoot;
+    readonly kind: "github";
+    constructor(repoRoot: string);
+    private readProjectConfig;
+    listAssignedIssues(): Promise<ProviderIssue[] | null>;
+    fetchProjectAssignments(): Promise<Map<IssueId, IssueProjectInfo> | null>;
+    transitionIssueToInProgress(issueId: IssueId): Promise<TransitionResult>;
+}
+/**
+ * Returns the gh CLI token scopes for github.com, or null when `gh` can't be
+ * called / the user isn't authenticated. `gh auth status` writes the scopes
+ * line to stderr; we capture both streams and grep for it.
+ *
+ * Kept as a standalone export (not part of IssueProvider) because it's
+ * consumed by doctor for the Project v2 scope row — a doctor-side concern,
+ * not part of the runtime issue flow.
+ */
+export declare function getGhTokenScopes(): Promise<string[] | null>;
+export declare function hasProjectScope(scopes: string[]): boolean;