mintree 0.1.10 → 0.2.0

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

@@ -0,0 +1,113 @@
+/**
+ * Shared types and the IssueProvider interface implemented by the
+ * github/plane providers. Keeping these in one file lets the dashboard and
+ * worktree commands talk to issues abstractly while each provider owns its
+ * own transport details.
+ *
+ * `IssueId` is a string in both providers — for GitHub it's the issue number
+ * stringified ("100"); for Plane it'll be the project-prefixed identifier
+ * ("BACK-100"). The branch convention encodes this same string verbatim, so
+ * worktree dir names round-trip through the IssueId without re-parsing.
+ */
+export type IssueId = string;
+/**
+ * A workflow issue normalised across providers. Shape mirrors what the GH
+ * `gh issue list --json` payload exposes minus the GH-specific `number`
+ * field, which is replaced by the universal `id` string.
+ */
+export type ProviderIssue = {
+    id: IssueId;
+    title: string;
+    state: string;
+    url: string;
+    labels: {
+        name: string;
+    }[];
+    body: string;
+    createdAt: string;
+    updatedAt: string;
+};
+/**
+ * The issue's membership on a project board (GitHub Projects v2 / Plane
+ * project), used to group the dashboard list. `status` is the workflow
+ * state's display name (null when the issue is on the board but no state is
+ * set). `statusOrder` gives the column index so the dashboard can order
+ * sub-groups the same way the board does. `statusColor` is an Ink-renderable
+ * colour string — a 16-colour name for GitHub's enum, or a #rrggbb hex for
+ * Plane states.
+ */
+export type IssueProjectInfo = {
+    projectTitle: string;
+    projectUrl: string;
+    projectNumber: number;
+    status: string | null;
+    statusColor: string;
+    statusOrder: number;
+};
+/**
+ * Result of transitionIssueToInProgress. Discriminated so the caller can
+ * render a precise status message without inventing one. Provider-agnostic:
+ * the github and plane implementations both yield these shapes.
+ */
+export type TransitionResult = {
+    kind: "transitioned";
+    projectTitle: string;
+    from: string | null;
+    to: string;
+} | {
+    kind: "noop-already";
+    projectTitle: string;
+} | {
+    kind: "noop-protected";
+    projectTitle: string;
+    current: string;
+} | {
+    kind: "skip-no-repo";
+} | {
+    kind: "skip-no-issue";
+} | {
+    kind: "skip-no-project";
+} | {
+    kind: "skip-ambiguous";
+    projects: string[];
+} | {
+    kind: "skip-no-status-field";
+    projects: string[];
+} | {
+    kind: "skip-no-in-progress-option";
+    projects: string[];
+} | {
+    kind: "error";
+    message: string;
+    hint?: string;
+};
+export interface IssueProvider {
+    readonly kind: "github" | "plane";
+    /**
+     * Lists open issues assigned to the current user, scoped to whatever the
+     * provider considers the active context (GH: the current repo on origin;
+     * Plane: the configured workspace/projects). Returns null on transient
+     * failure (auth, network) — the dashboard renders an error hint.
+     */
+    listAssignedIssues(): Promise<ProviderIssue[] | null>;
+    /**
+     * Returns project/board membership for the assigned issues (same scope as
+     * listAssignedIssues — typically a single round-trip). The dashboard uses
+     * this to group rows by project → status.
+     *
+     * Return shapes:
+     *   - non-empty map: the lookup succeeded and found project membership
+     *   - empty map: the lookup succeeded but no issue is on any project
+     *   - null: the lookup failed for ALL projects (transient API error,
+     *     auth missing). Distinct from empty so the dashboard can treat
+     *     null as a partial load failure and keep its last-good state.
+     */
+    fetchProjectAssignments(): Promise<Map<IssueId, IssueProjectInfo> | null>;
+    /**
+     * Moves the issue to its project's "In Progress" workflow state. Idempotent
+     * by design (returns noop-already when already there) and conservative on
+     * later stages (returns noop-protected when the issue is past In Progress,
+     * e.g. "In Review" / "Done").
+     */
+    transitionIssueToInProgress(issueId: IssueId): Promise<TransitionResult>;
+}

package/dist/lib/providers/types.js

@@ -0,0 +1,12 @@
+/**
+ * Shared types and the IssueProvider interface implemented by the
+ * github/plane providers. Keeping these in one file lets the dashboard and
+ * worktree commands talk to issues abstractly while each provider owns its
+ * own transport details.
+ *
+ * `IssueId` is a string in both providers — for GitHub it's the issue number
+ * stringified ("100"); for Plane it'll be the project-prefixed identifier
+ * ("BACK-100"). The branch convention encodes this same string verbatim, so
+ * worktree dir names round-trip through the IssueId without re-parsing.
+ */
+export {};

package/dist/lib/session-signal.d.ts

@@ -16,9 +16,10 @@ export declare function extractRepoAndDir(cwd: string): {
     worktreeDir: string;
 } | null;
 /**
- * Pulls the issue number out of a `<issue>-<desc>` worktree directory name.
+ * Pulls the issue id out of a `<issue>-<desc>` worktree directory name.
  * Returns null when the directory name doesn't follow the convention (e.g.
- * a manually-created worktree dropped under .mintree/worktrees/).
+ * a manually-created worktree dropped under .mintree/worktrees/). The id
+ * is either bare digits (GitHub) or a `<PROJ>-\d+` Plane identifier.
  */
 export declare function issueIdFromWorktreeDir(worktreeDir: string): string | null;
 export type StatePayload = {

package/dist/lib/session-signal.js

@@ -32,12 +32,13 @@ export function extractRepoAndDir(cwd) {
     return { repoRoot, worktreeDir };
 }
 /**
- * Pulls the issue number out of a `<issue>-<desc>` worktree directory name.
+ * Pulls the issue id out of a `<issue>-<desc>` worktree directory name.
  * Returns null when the directory name doesn't follow the convention (e.g.
- * a manually-created worktree dropped under .mintree/worktrees/).
+ * a manually-created worktree dropped under .mintree/worktrees/). The id
+ * is either bare digits (GitHub) or a `<PROJ>-\d+` Plane identifier.
  */
 export function issueIdFromWorktreeDir(worktreeDir) {
-    const m = worktreeDir.match(/^(\d+)-/);
+    const m = worktreeDir.match(/^((?:[A-Z][A-Z0-9_]*-)?\d+)-/);
     return m && m[1] ? m[1] : null;
 }
 /**

package/dist/lib/worktreeCreate.js

@@ -224,7 +224,10 @@ export function runCreateDetached(opts) {
             hint: "Run `mintree init` first.",
         };
     }
-    if (!/^\d+$/.test(opts.issueId)) {
+    // Same shape as BRANCH_REGEX's issueId capture: bare digits (GitHub) or
+    // `<PROJ>-\d+` (Plane). Otherwise the detached-worktree flow rejects
+    // valid Plane ids like "AUTH-6" when they reach this entry point.
+    if (!/^(?:[A-Z][A-Z0-9_]*-)?\d+$/.test(opts.issueId)) {
         return { ok: false, message: `Invalid issueId: ${opts.issueId}` };
     }
     if (!/^[a-z0-9][a-z0-9-]*$/.test(opts.descKebab)) {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "mintree",
-	"version": "0.1.10",
+	"version": "0.2.0",
 	"description": "Issue-driven git worktrees + Claude Code sessions for repos with an opinionated SDD+TDD flow.",
 	"license": "MIT",
 	"author": "Martin Mineo <mmineo@canarytechnologies.com>",

package/dist/lib/github.d.ts

@@ -1,7 +0,0 @@
-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/githubProject.d.ts

@@ -1,55 +0,0 @@
-export type TransitionResult = {
-    kind: "transitioned";
-    projectTitle: string;
-    from: string | null;
-    to: string;
-} | {
-    kind: "noop-already";
-    projectTitle: string;
-} | {
-    kind: "noop-protected";
-    projectTitle: string;
-    current: string;
-} | {
-    kind: "skip-no-repo";
-} | {
-    kind: "skip-no-issue";
-} | {
-    kind: "skip-no-project";
-} | {
-    kind: "skip-ambiguous";
-    projects: string[];
-} | {
-    kind: "skip-no-status-field";
-    projects: string[];
-} | {
-    kind: "skip-no-in-progress-option";
-    projects: string[];
-} | {
-    kind: "error";
-    message: string;
-    hint?: string;
-};
-/**
- * Moves the GitHub issue to "In Progress" on its project. Auto-discovers the
- * project from the issue's projectItems; if there are several candidates and
- * `.mintree/metadata.json` doesn't pin one (via `project.url`), bails out
- * rather than guess.
- *
- * Skips silently when the status is already In Progress or one of the
- * protected statuses (In Review, Done by default) — to avoid clobbering
- * a PR-driven transition done by something else.
- */
-export declare function transitionIssueToInProgress(repoRoot: string, issueNumber: number | string): 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.
- */
-export declare function getGhTokenScopes(): Promise<string[] | null>;
-export declare function hasProjectScope(scopes: string[]): boolean;
-export declare function describeTransition(result: TransitionResult): {
-    kind: "ok" | "skip" | "warn";
-    label: string;
-    detail?: string;
-};

package/dist/lib/githubProject.js

@@ -1,277 +0,0 @@
-import { execFile } from "child_process";
-import { promisify } from "util";
-import { getRepoFullName } from "./github.js";
-import { readMetadata } from "./metadata.js";
-const execFileAsync = promisify(execFile);
-const DEFAULT_STATUS_FIELD = "Status";
-const DEFAULT_IN_PROGRESS_OPTION = "In Progress";
-const DEFAULT_PROTECTED_STATUSES = ["In Review", "Done"];
-async function runGhGraphql(query, fields) {
-    const args = ["api", "graphql", "-f", `query=${query}`];
-    for (const [key, value] of fields) {
-        if (typeof value === "number") {
-            args.push("-F", `${key}=${value}`);
-        }
-        else {
-            args.push("-f", `${key}=${value}`);
-        }
-    }
-    const { stdout } = await execFileAsync("gh", args);
-    return JSON.parse(stdout);
-}
-function readProjectConfig(repoRoot) {
-    return readMetadata(repoRoot).project ?? {};
-}
-function parseProjectNumberFromUrl(url) {
-    const m = url.match(/\/projects\/(\d+)/);
-    return m && m[1] ? Number(m[1]) : null;
-}
-function interpretGhError(err) {
-    const stderr = err && typeof err === "object" && "stderr" in err
-        ? String(err.stderr)
-        : err instanceof Error
-            ? err.message
-            : String(err);
-    if (/INSUFFICIENT_SCOPES/i.test(stderr) || (/scope/i.test(stderr) && /project/i.test(stderr))) {
-        return {
-            kind: "error",
-            message: "gh token is missing the `project` scope.",
-            hint: "Run: gh auth refresh -s project",
-        };
-    }
-    if (/Could not resolve to a Repository/i.test(stderr)) {
-        return { kind: "skip-no-repo" };
-    }
-    if (/Could not resolve to an Issue/i.test(stderr)) {
-        return { kind: "skip-no-issue" };
-    }
-    const firstLine = stderr.split("\n").find((line) => line.trim().length > 0) ?? "";
-    return {
-        kind: "error",
-        message: firstLine.slice(0, 200) || "gh api graphql failed",
-    };
-}
-/**
- * Moves the GitHub issue to "In Progress" on its project. Auto-discovers the
- * project from the issue's projectItems; if there are several candidates and
- * `.mintree/metadata.json` doesn't pin one (via `project.url`), bails out
- * rather than guess.
- *
- * Skips silently when the status is already In Progress or one of the
- * protected statuses (In Review, Done by default) — to avoid clobbering
- * a PR-driven transition done by something else.
- */
-export async function transitionIssueToInProgress(repoRoot, issueNumber) {
-    const repo = await getRepoFullName();
-    if (!repo)
-        return { kind: "skip-no-repo" };
-    const [owner, name] = repo.split("/");
-    if (!owner || !name)
-        return { kind: "skip-no-repo" };
-    const cfg = readProjectConfig(repoRoot);
-    const statusFieldName = cfg.statusField ?? DEFAULT_STATUS_FIELD;
-    const inProgressOptionName = cfg.inProgressOption ?? DEFAULT_IN_PROGRESS_OPTION;
-    const protectedStatuses = cfg.protectedStatuses ?? DEFAULT_PROTECTED_STATUSES;
-    // The Status field name is interpolated into the query (not a variable)
-    // because GraphQL field-argument names are not parameterizable through
-    // the variables object. Escape any embedded quotes to keep the query valid.
-    const escapedFieldName = statusFieldName.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
-    const query = `query($owner: String!, $repo: String!, $number: Int!) {
-  repository(owner: $owner, name: $repo) {
-    issue(number: $number) {
-      id
-      projectItems(first: 20, includeArchived: false) {
-        nodes {
-          id
-          project {
-            id
-            title
-            number
-            url
-            field(name: "${escapedFieldName}") {
-              ... on ProjectV2SingleSelectField {
-                id
-                name
-                options { id name }
-              }
-            }
-          }
-          fieldValues(first: 30) {
-            nodes {
-              ... on ProjectV2ItemFieldSingleSelectValue {
-                name
-                field {
-                  ... on ProjectV2SingleSelectField { name }
-                }
-              }
-            }
-          }
-        }
-      }
-    }
-  }
-}`;
-    let raw;
-    try {
-        raw = (await runGhGraphql(query, [
-            ["owner", owner],
-            ["repo", name],
-            ["number", Number(issueNumber)],
-        ]));
-    }
-    catch (err) {
-        return interpretGhError(err);
-    }
-    const issue = raw?.data?.repository?.issue;
-    if (!issue)
-        return { kind: "skip-no-issue" };
-    let nodes = issue.projectItems.nodes;
-    if (nodes.length === 0)
-        return { kind: "skip-no-project" };
-    // Honour an explicit project URL in the config before doing anything else.
-    if (cfg.url) {
-        const targetNumber = parseProjectNumberFromUrl(cfg.url);
-        nodes = nodes.filter((n) => n.project.url === cfg.url || (targetNumber !== null && n.project.number === targetNumber));
-        if (nodes.length === 0)
-            return { kind: "skip-no-project" };
-    }
-    const withField = nodes.filter((n) => n.project.field !== null);
-    if (withField.length === 0) {
-        return { kind: "skip-no-status-field", projects: nodes.map((n) => n.project.title) };
-    }
-    const withOption = withField.filter((n) => n.project.field.options.some((o) => o.name === inProgressOptionName));
-    if (withOption.length === 0) {
-        return {
-            kind: "skip-no-in-progress-option",
-            projects: withField.map((n) => n.project.title),
-        };
-    }
-    if (withOption.length > 1) {
-        return { kind: "skip-ambiguous", projects: withOption.map((n) => n.project.title) };
-    }
-    const item = withOption[0];
-    const project = item.project;
-    const field = project.field;
-    const option = field.options.find((o) => o.name === inProgressOptionName);
-    if (!option) {
-        // Defensive — already filtered above, but TypeScript can't see it.
-        return { kind: "skip-no-in-progress-option", projects: [project.title] };
-    }
-    const currentStatus = item.fieldValues.nodes.find((v) => v.field?.name === statusFieldName)?.name ?? null;
-    if (currentStatus === inProgressOptionName) {
-        return { kind: "noop-already", projectTitle: project.title };
-    }
-    if (currentStatus !== null && protectedStatuses.includes(currentStatus)) {
-        return { kind: "noop-protected", projectTitle: project.title, current: currentStatus };
-    }
-    const mutation = `mutation($projectId: ID!, $itemId: ID!, $fieldId: ID!, $optionId: String!) {
-  updateProjectV2ItemFieldValue(input: {
-    projectId: $projectId
-    itemId: $itemId
-    fieldId: $fieldId
-    value: { singleSelectOptionId: $optionId }
-  }) {
-    projectV2Item { id }
-  }
-}`;
-    try {
-        await runGhGraphql(mutation, [
-            ["projectId", project.id],
-            ["itemId", item.id],
-            ["fieldId", field.id],
-            ["optionId", option.id],
-        ]);
-    }
-    catch (err) {
-        return interpretGhError(err);
-    }
-    return {
-        kind: "transitioned",
-        projectTitle: project.title,
-        from: currentStatus,
-        to: inProgressOptionName,
-    };
-}
-/**
- * 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.
- */
-export async function getGhTokenScopes() {
-    try {
-        const { stdout, stderr } = await execFileAsync("gh", ["auth", "status"]);
-        const combined = `${stdout}\n${stderr}`;
-        return parseScopesFromAuthStatus(combined);
-    }
-    catch (err) {
-        const out = err && typeof err === "object" && "stdout" in err && "stderr" in err
-            ? `${String(err.stdout)}\n${String(err.stderr)}`
-            : "";
-        const parsed = parseScopesFromAuthStatus(out);
-        return parsed ?? null;
-    }
-}
-function parseScopesFromAuthStatus(text) {
-    const m = text.match(/Token scopes:\s*([^\n]+)/i);
-    if (!m || !m[1])
-        return null;
-    return m[1]
-        .split(",")
-        .map((s) => s.trim().replace(/^['"]|['"]$/g, ""))
-        .filter(Boolean);
-}
-export function hasProjectScope(scopes) {
-    return scopes.some((s) => s === "project" || s === "write:project");
-}
-export function describeTransition(result) {
-    switch (result.kind) {
-        case "transitioned":
-            return {
-                kind: "ok",
-                label: `issue → ${result.to}`,
-                detail: result.from ? `${result.projectTitle} (was: ${result.from})` : result.projectTitle,
-            };
-        case "noop-already":
-            return {
-                kind: "skip",
-                label: "issue already In Progress",
-                detail: result.projectTitle,
-            };
-        case "noop-protected":
-            return {
-                kind: "skip",
-                label: `issue kept at ${result.current}`,
-                detail: `${result.projectTitle} (status is protected)`,
-            };
-        case "skip-no-repo":
-            return { kind: "skip", label: "no GitHub repo — skipping project update" };
-        case "skip-no-issue":
-            return { kind: "skip", label: "issue not found on GitHub — skipping project update" };
-        case "skip-no-project":
-            return { kind: "skip", label: "issue not on any project — skipping project update" };
-        case "skip-ambiguous":
-            return {
-                kind: "warn",
-                label: "multiple matching projects — skipping",
-                detail: `set .mintree/metadata.json project.url to one of: ${result.projects.join(", ")}`,
-            };
-        case "skip-no-status-field":
-            return {
-                kind: "skip",
-                label: "no Status field on project — skipping",
-                detail: result.projects.join(", "),
-            };
-        case "skip-no-in-progress-option":
-            return {
-                kind: "skip",
-                label: "no In Progress option on Status field — skipping",
-                detail: result.projects.join(", "),
-            };
-        case "error":
-            return {
-                kind: "warn",
-                label: "project update failed",
-                detail: result.hint ? `${result.message} — ${result.hint}` : result.message,
-            };
-    }
-}