cortex-agents 2.3.1 → 3.4.0

package/dist/utils/github.js

@@ -0,0 +1,243 @@
+import { gh, which, git } from "./shell.js";
+// ─── Constants ───────────────────────────────────────────────────────────────
+/** Maximum character length for issue body in list views to avoid overwhelming context. */
+const BODY_TRUNCATE_LENGTH = 200;
+/** Maximum character length for issue body in detail views (plan formatting). */
+const BODY_DETAIL_LENGTH = 2000;
+// ─── GitHub CLI Availability ─────────────────────────────────────────────────
+/**
+ * Check full GitHub CLI availability and repo context.
+ * Returns a status object with installation, authentication, and repo info.
+ */
+export async function checkGhAvailability(cwd) {
+    const status = {
+        installed: false,
+        authenticated: false,
+        hasRemote: false,
+        projects: [],
+    };
+    // 1. Check if gh is installed
+    const ghPath = await which("gh");
+    if (!ghPath)
+        return status;
+    status.installed = true;
+    // 2. Check if authenticated
+    try {
+        await gh(cwd, "auth", "status");
+        status.authenticated = true;
+    }
+    catch {
+        return status;
+    }
+    // 3. Extract repo owner/name from remote
+    try {
+        const { stdout } = await git(cwd, "remote", "get-url", "origin");
+        const parsed = parseRepoUrl(stdout.trim());
+        if (parsed) {
+            status.hasRemote = true;
+            status.repoOwner = parsed.owner;
+            status.repoName = parsed.name;
+        }
+    }
+    catch {
+        // No remote configured — hasRemote stays false
+    }
+    return status;
+}
+/**
+ * Parse a git remote URL to extract owner and repo name.
+ * Handles HTTPS, SSH, and GitHub CLI formats.
+ * Supports both github.com and GitHub Enterprise Server URLs (e.g., github.mycompany.com).
+ *
+ * The regex requires "github" to appear at a hostname boundary (after `//` or `@`)
+ * to prevent false positives like "notgithub.com" or "fakegithub.evil.com".
+ */
+export function parseRepoUrl(url) {
+    // HTTPS: https://github.com/owner/repo.git  OR  https://github.mycompany.com/owner/repo.git
+    // The `//` anchor ensures "github" is at the start of the hostname, not mid-word.
+    const httpsMatch = url.match(/\/\/github[^/]*\/([^/]+)\/([^/.]+?)(?:\.git)?$/);
+    if (httpsMatch) {
+        return { owner: httpsMatch[1], name: httpsMatch[2] };
+    }
+    // SSH: git@github.com:owner/repo.git  OR  git@github.mycompany.com:owner/repo.git
+    // The `git@` prefix already anchors to the hostname start.
+    const sshMatch = url.match(/git@github[^:]*:([^/]+)\/([^/.]+?)(?:\.git)?$/);
+    if (sshMatch) {
+        return { owner: sshMatch[1], name: sshMatch[2] };
+    }
+    return null;
+}
+// ─── Issue Formatting ────────────────────────────────────────────────────────
+/**
+ * Truncate a string to the given length, appending "..." if truncated.
+ */
+export function truncate(str, maxLen) {
+    if (!str)
+        return "";
+    if (str.length <= maxLen)
+        return str;
+    return str.substring(0, maxLen).trimEnd() + "...";
+}
+/**
+ * Format a single GitHub issue into a compact list entry.
+ * Used when presenting multiple issues for selection.
+ */
+export function formatIssueListEntry(issue) {
+    const labels = issue.labels.length > 0 ? ` [${issue.labels.join(", ")}]` : "";
+    const assignees = issue.assignees.length > 0 ? ` → ${issue.assignees.join(", ")}` : "";
+    const body = issue.body ? `\n   ${truncate(issue.body.replace(/\n/g, " "), BODY_TRUNCATE_LENGTH)}` : "";
+    return `#${issue.number}: ${issue.title}${labels}${assignees}${body}`;
+}
+/**
+ * Format multiple issues into a numbered selection list.
+ */
+export function formatIssueList(issues) {
+    if (issues.length === 0)
+        return "No issues found.";
+    return issues.map((issue) => formatIssueListEntry(issue)).join("\n\n");
+}
+/**
+ * Format a GitHub issue into a planning-friendly markdown block.
+ * Used by the architect agent to seed plan content from selected issues.
+ */
+export function formatIssueForPlan(issue) {
+    const parts = [];
+    parts.push(`### Issue #${issue.number}: ${issue.title}`);
+    parts.push("");
+    if (issue.labels.length > 0) {
+        parts.push(`**Labels:** ${issue.labels.join(", ")}`);
+    }
+    if (issue.assignees.length > 0) {
+        parts.push(`**Assignees:** ${issue.assignees.join(", ")}`);
+    }
+    if (issue.milestone) {
+        parts.push(`**Milestone:** ${issue.milestone}`);
+    }
+    parts.push(`**URL:** ${issue.url}`);
+    parts.push("");
+    if (issue.body) {
+        parts.push("**Description:**");
+        parts.push("");
+        parts.push(truncate(issue.body, BODY_DETAIL_LENGTH));
+    }
+    return parts.join("\n");
+}
+// ─── Project Item Formatting ─────────────────────────────────────────────────
+/**
+ * Format a single GitHub Project item into a compact list entry.
+ */
+export function formatProjectItemEntry(item) {
+    const status = item.status ? ` (${item.status})` : "";
+    const type = item.type === "DRAFT_ISSUE" ? " [Draft]" : item.type === "PULL_REQUEST" ? " [PR]" : "";
+    const labels = item.labels.length > 0 ? ` [${item.labels.join(", ")}]` : "";
+    const assignees = item.assignees.length > 0 ? ` → ${item.assignees.join(", ")}` : "";
+    const ref = item.issueNumber ? `#${item.issueNumber}: ` : "";
+    return `${ref}${item.title}${type}${status}${labels}${assignees}`;
+}
+/**
+ * Format multiple project items into a list.
+ */
+export function formatProjectItemList(items) {
+    if (items.length === 0)
+        return "No project items found.";
+    return items.map((item) => formatProjectItemEntry(item)).join("\n");
+}
+// ─── GitHub CLI Data Fetching ────────────────────────────────────────────────
+/**
+ * Fetch GitHub projects associated with the repo owner.
+ */
+export async function fetchProjects(cwd, owner) {
+    try {
+        const { stdout } = await gh(cwd, "project", "list", "--owner", owner, "--format", "json");
+        const parsed = JSON.parse(stdout);
+        // gh project list --format json returns { projects: [...] }
+        const projects = parsed.projects ?? parsed ?? [];
+        return projects.map((p) => ({
+            id: String(p.id ?? ""),
+            number: Number(p.number ?? 0),
+            title: String(p.title ?? "Untitled"),
+        }));
+    }
+    catch (error) {
+        // Surface auth errors — these are actionable for the user.
+        // Other errors (no projects, API format changes) are non-critical.
+        const msg = error?.message ?? String(error);
+        if (msg.includes("auth") || msg.includes("401") || msg.includes("403")) {
+            throw new Error(`GitHub authentication error while fetching projects: ${msg}`);
+        }
+        return [];
+    }
+}
+/**
+ * Fetch issues from the current repository using gh CLI.
+ */
+export async function fetchIssues(cwd, options = {}) {
+    const args = [
+        "issue", "list",
+        "--json", "number,title,state,labels,assignees,milestone,body,url,createdAt,updatedAt",
+        "--limit", String(options.limit ?? 20),
+    ];
+    if (options.state)
+        args.push("--state", options.state);
+    if (options.labels)
+        args.push("--label", options.labels);
+    if (options.milestone)
+        args.push("--milestone", options.milestone);
+    if (options.assignee)
+        args.push("--assignee", options.assignee);
+    const { stdout } = await gh(cwd, ...args);
+    const raw = JSON.parse(stdout);
+    return raw.map((item) => ({
+        number: item.number,
+        title: item.title ?? "",
+        state: item.state ?? "open",
+        labels: (item.labels ?? []).map((l) => (typeof l === "string" ? l : l.name ?? "")),
+        assignees: (item.assignees ?? []).map((a) => (typeof a === "string" ? a : a.login ?? "")),
+        milestone: item.milestone?.title ?? undefined,
+        body: item.body ?? "",
+        url: item.url ?? "",
+        createdAt: item.createdAt ?? "",
+        updatedAt: item.updatedAt ?? "",
+    }));
+}
+/**
+ * Fetch project items from a specific GitHub Project.
+ */
+export async function fetchProjectItems(cwd, owner, projectNumber, options = {}) {
+    const { stdout } = await gh(cwd, "project", "item-list", String(projectNumber), "--owner", owner, "--format", "json", "--limit", String(options.limit ?? 30));
+    const parsed = JSON.parse(stdout);
+    // gh project item-list --format json returns { items: [...] }
+    const raw = parsed.items ?? parsed ?? [];
+    const items = raw.map((item) => ({
+        id: String(item.id ?? ""),
+        title: item.title ?? "",
+        type: normalizeItemType(item.type),
+        status: item.status ?? undefined,
+        assignees: Array.isArray(item.assignees)
+            ? item.assignees.map((a) => (typeof a === "string" ? a : a.login ?? ""))
+            : [],
+        labels: Array.isArray(item.labels)
+            ? item.labels.map((l) => (typeof l === "string" ? l : l.name ?? ""))
+            : [],
+        issueNumber: item.content?.number ?? undefined,
+        url: item.content?.url ?? undefined,
+        body: item.content?.body ?? undefined,
+    }));
+    // Apply status filter client-side if provided
+    if (options.status) {
+        const filterStatus = options.status.toLowerCase();
+        return items.filter((item) => item.status?.toLowerCase().includes(filterStatus));
+    }
+    return items;
+}
+/**
+ * Normalize the item type string from GitHub's API into our union type.
+ */
+function normalizeItemType(type) {
+    const t = String(type ?? "").toUpperCase();
+    if (t.includes("PULL") || t === "PULL_REQUEST")
+        return "PULL_REQUEST";
+    if (t.includes("DRAFT") || t === "DRAFT_ISSUE")
+        return "DRAFT_ISSUE";
+    return "ISSUE";
+}

package/dist/utils/ide.d.ts

@@ -0,0 +1,76 @@
+/**
+ * IDE Detection System
+ *
+ * Detects the current Integrated Development Environment or editor context.
+ * This is used to offer appropriate worktree launch options that match
+ * the user's current workflow.
+ *
+ * Detection is based on environment variables set by various IDEs when
+ * running terminal sessions within them.
+ */
+export type IDEType = "vscode" | "cursor" | "windsurf" | "jetbrains" | "zed" | "terminal" | "unknown";
+export interface IDEDetection {
+    type: IDEType;
+    name: string;
+    version?: string;
+    hasIntegratedTerminal: boolean;
+    canOpenInTerminal: boolean;
+    canOpenInWindow: boolean;
+    cliAvailable?: boolean;
+    cliBinary?: string;
+    cliInstallHint?: string;
+    detectionSource: string;
+}
+export interface EnvironmentRecommendation {
+    option: string;
+    priority: "high" | "medium" | "low";
+    reason: string;
+    mode?: "ide" | "terminal" | "pty" | "background" | "stay";
+}
+/**
+ * Detect the current IDE/editor environment.
+ * Checks environment variables, process hierarchy, and context clues.
+ */
+export declare function detectIDE(): IDEDetection;
+/**
+ * Get the command to open a worktree in the IDE's integrated terminal.
+ * Returns null if the IDE doesn't support CLI-based opening.
+ *
+ * Note: This function is currently unused but kept for future use.
+ * All inputs are escaped to prevent command injection.
+ */
+export declare function getIDEOpenCommand(ide: IDEDetection, worktreePath: string): string | null;
+/**
+ * Get the name of the CLI binary for the detected IDE.
+ * Returns null if no CLI is available or known.
+ */
+export declare function getIDECliBinary(ide: IDEDetection): string | null;
+/**
+ * Get a human-readable hint for installing an IDE's CLI binary.
+ * Each IDE has a different installation method.
+ */
+export declare function getInstallHint(type: IDEType, binary: string): string;
+/**
+ * Async version of detectIDE() that also checks whether the IDE's CLI binary
+ * is actually available in PATH. Use this in tools where you need to verify
+ * runtime availability before offering IDE launch options.
+ *
+ * The sync detectIDE() is preserved for non-async contexts.
+ */
+export declare function detectIDEWithCLICheck(): Promise<IDEDetection>;
+/**
+ * Check if we're already inside an IDE terminal.
+ * This helps determine if we should offer "stay here" as primary option.
+ */
+export declare function isInIDETerminal(): boolean;
+/**
+ * Generate contextual recommendations based on detected environment.
+ * Used by agents to offer appropriate launch options to users.
+ */
+export declare function generateEnvironmentRecommendations(ide: IDEDetection): EnvironmentRecommendation[];
+/**
+ * Format environment detection as a human-readable report.
+ * Used by the detect_environment tool.
+ */
+export declare function formatEnvironmentReport(ide: IDEDetection, terminalName: string): string;
+//# sourceMappingURL=ide.d.ts.map

package/dist/utils/ide.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ide.d.ts","sourceRoot":"","sources":["../../src/utils/ide.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,MAAM,MAAM,OAAO,GACf,QAAQ,GACR,QAAQ,GACR,UAAU,GACV,WAAW,GACX,KAAK,GACL,UAAU,GACV,SAAS,CAAC;AAEd,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,OAAO,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,qBAAqB,EAAE,OAAO,CAAC;IAC/B,iBAAiB,EAAE,OAAO,CAAC;IAC3B,eAAe,EAAE,OAAO,CAAC;IACzB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,eAAe,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,yBAAyB;IACxC,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,GAAG,QAAQ,GAAG,KAAK,CAAC;IACpC,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,KAAK,GAAG,UAAU,GAAG,KAAK,GAAG,YAAY,GAAG,MAAM,CAAC;CAC3D;AAED;;;GAGG;AACH,wBAAgB,SAAS,IAAI,YAAY,CAoGxC;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CA6BxF;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,YAAY,GAAG,MAAM,GAAG,IAAI,CAahE;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAapE;AAED;;;;;;GAMG;AACH,wBAAsB,qBAAqB,IAAI,OAAO,CAAC,YAAY,CAAC,CAgBnE;AAED;;;GAGG;AACH,wBAAgB,eAAe,IAAI,OAAO,CAGzC;AAED;;;GAGG;AACH,wBAAgB,kCAAkC,CAAC,GAAG,EAAE,YAAY,GAAG,yBAAyB,EAAE,CAkDjG;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM,CAgDvF"}

package/dist/utils/ide.js

@@ -0,0 +1,307 @@
+/**
+ * IDE Detection System
+ *
+ * Detects the current Integrated Development Environment or editor context.
+ * This is used to offer appropriate worktree launch options that match
+ * the user's current workflow.
+ *
+ * Detection is based on environment variables set by various IDEs when
+ * running terminal sessions within them.
+ */
+import { shellEscape, which } from "./shell.js";
+/**
+ * Detect the current IDE/editor environment.
+ * Checks environment variables, process hierarchy, and context clues.
+ */
+export function detectIDE() {
+    const env = process.env;
+    // VS Code detection
+    // VSCODE_PID is set when running in VS Code's integrated terminal
+    // VSCODE_CWD is set in some VS Code contexts
+    // TERM_PROGRAM=vscode is set by VS Code's terminal
+    if (env.VSCODE_PID || env.VSCODE_CWD || env.TERM_PROGRAM === "vscode") {
+        return {
+            type: "vscode",
+            name: "Visual Studio Code",
+            version: env.VSCODE_VERSION,
+            hasIntegratedTerminal: true,
+            canOpenInTerminal: true,
+            canOpenInWindow: true,
+            detectionSource: env.VSCODE_PID ? "VSCODE_PID" :
+                env.VSCODE_CWD ? "VSCODE_CWD" : "TERM_PROGRAM",
+        };
+    }
+    // Cursor detection
+    // CURSOR_TRACE_ID is set by Cursor AI editor
+    // CURSOR_SHELL_VERSION indicates Cursor's shell integration
+    if (env.CURSOR_TRACE_ID || env.CURSOR_SHELL_VERSION) {
+        return {
+            type: "cursor",
+            name: "Cursor",
+            version: env.CURSOR_SHELL_VERSION,
+            hasIntegratedTerminal: true,
+            canOpenInTerminal: true,
+            canOpenInWindow: true,
+            detectionSource: env.CURSOR_TRACE_ID ? "CURSOR_TRACE_ID" : "CURSOR_SHELL_VERSION",
+        };
+    }
+    // Windsurf detection
+    // WINDSURF_PARENT_PROCESS indicates Windsurf editor
+    // WINDSURF_EDITOR is set by Windsurf's terminal
+    if (env.WINDSURF_PARENT_PROCESS || env.WINDSURF_EDITOR) {
+        return {
+            type: "windsurf",
+            name: "Windsurf",
+            hasIntegratedTerminal: true,
+            canOpenInTerminal: true,
+            canOpenInWindow: true,
+            detectionSource: env.WINDSURF_PARENT_PROCESS ? "WINDSURF_PARENT_PROCESS" : "WINDSURF_EDITOR",
+        };
+    }
+    // JetBrains detection
+    // TERMINAL_EMULATOR contains "JetBrains" when in JB IDE terminal
+    // JETBRAINS_IDE is set by some JetBrains IDEs
+    if (env.TERMINAL_EMULATOR?.includes("JetBrains") || env.JETBRAINS_IDE) {
+        return {
+            type: "jetbrains",
+            name: env.JETBRAINS_IDE_NAME || "JetBrains IDE",
+            hasIntegratedTerminal: true,
+            canOpenInTerminal: true, // Can open in terminal, but no CLI for new window
+            canOpenInWindow: false, // JB IDEs don't have CLI window opening
+            detectionSource: env.JETBRAINS_IDE ? "JETBRAINS_IDE" : "TERMINAL_EMULATOR",
+        };
+    }
+    // Zed detection
+    // ZED_TERM is set by Zed's integrated terminal
+    // TERM_PROGRAM=zed in some Zed configurations
+    if (env.ZED_TERM || env.TERM_PROGRAM === "zed") {
+        return {
+            type: "zed",
+            name: "Zed",
+            hasIntegratedTerminal: true,
+            canOpenInTerminal: true,
+            canOpenInWindow: true,
+            detectionSource: env.ZED_TERM ? "ZED_TERM" : "TERM_PROGRAM",
+        };
+    }
+    // Terminal-only detection (fallback when no IDE detected)
+    // This means we're in a standalone terminal emulator
+    if (env.TERM_PROGRAM || env.TMUX || env.TERM) {
+        return {
+            type: "terminal",
+            name: env.TERM_PROGRAM || env.TERM || "Terminal",
+            hasIntegratedTerminal: false,
+            canOpenInTerminal: false,
+            canOpenInWindow: true,
+            detectionSource: env.TERM_PROGRAM ? "TERM_PROGRAM" :
+                env.TMUX ? "TMUX" : "TERM",
+        };
+    }
+    // Unknown environment
+    return {
+        type: "unknown",
+        name: "Unknown",
+        hasIntegratedTerminal: false,
+        canOpenInTerminal: false,
+        canOpenInWindow: true,
+        detectionSource: "none",
+    };
+}
+/**
+ * Get the command to open a worktree in the IDE's integrated terminal.
+ * Returns null if the IDE doesn't support CLI-based opening.
+ *
+ * Note: This function is currently unused but kept for future use.
+ * All inputs are escaped to prevent command injection.
+ */
+export function getIDEOpenCommand(ide, worktreePath) {
+    // Escape the path to prevent command injection
+    const safePath = shellEscape(worktreePath);
+    switch (ide.type) {
+        case "vscode":
+            // VS Code: use `code` CLI to open folder in new window
+            return `code --new-window "${safePath}"`;
+        case "cursor":
+            // Cursor: use `cursor` CLI
+            return `cursor --new-window "${safePath}"`;
+        case "windsurf":
+            // Windsurf: use `windsurf` CLI
+            return `windsurf "${safePath}"`;
+        case "zed":
+            // Zed: use `zed` CLI
+            return `zed "${safePath}"`;
+        case "jetbrains":
+            // JetBrains: requires manual opening or platform-specific CLI
+            // Common CLIs: idea, webstorm, pycharm, etc.
+            return null;
+        default:
+            return null;
+    }
+}
+/**
+ * Get the name of the CLI binary for the detected IDE.
+ * Returns null if no CLI is available or known.
+ */
+export function getIDECliBinary(ide) {
+    switch (ide.type) {
+        case "vscode":
+            return "code";
+        case "cursor":
+            return "cursor";
+        case "windsurf":
+            return "windsurf";
+        case "zed":
+            return "zed";
+        default:
+            return null;
+    }
+}
+/**
+ * Get a human-readable hint for installing an IDE's CLI binary.
+ * Each IDE has a different installation method.
+ */
+export function getInstallHint(type, binary) {
+    switch (type) {
+        case "vscode":
+            return "Cmd+Shift+P → 'Shell Command: Install code command in PATH'";
+        case "cursor":
+            return "Cmd+Shift+P → 'Shell Command: Install cursor command in PATH'";
+        case "windsurf":
+            return "Ensure Windsurf is installed and 'windsurf' is in PATH";
+        case "zed":
+            return "Ensure Zed is installed and 'zed' is in PATH";
+        default:
+            return `Ensure '${binary}' is in PATH`;
+    }
+}
+/**
+ * Async version of detectIDE() that also checks whether the IDE's CLI binary
+ * is actually available in PATH. Use this in tools where you need to verify
+ * runtime availability before offering IDE launch options.
+ *
+ * The sync detectIDE() is preserved for non-async contexts.
+ */
+export async function detectIDEWithCLICheck() {
+    const ide = detectIDE();
+    const cliBinary = getIDECliBinary(ide);
+    if (cliBinary) {
+        const available = await which(cliBinary);
+        ide.cliAvailable = !!available;
+        ide.cliBinary = cliBinary;
+        if (!available) {
+            ide.cliInstallHint = getInstallHint(ide.type, cliBinary);
+        }
+    }
+    else {
+        ide.cliAvailable = false;
+    }
+    return ide;
+}
+/**
+ * Check if we're already inside an IDE terminal.
+ * This helps determine if we should offer "stay here" as primary option.
+ */
+export function isInIDETerminal() {
+    const ide = detectIDE();
+    return ide.hasIntegratedTerminal && !!process.env.TERM;
+}
+/**
+ * Generate contextual recommendations based on detected environment.
+ * Used by agents to offer appropriate launch options to users.
+ */
+export function generateEnvironmentRecommendations(ide) {
+    const recommendations = [];
+    if (ide.hasIntegratedTerminal && ide.canOpenInTerminal && ide.cliAvailable !== false) {
+        // Only offer IDE option when CLI is confirmed available or hasn't been checked yet
+        recommendations.push({
+            option: `Open in ${ide.name} (Recommended)`,
+            priority: "high",
+            reason: `${ide.name} integrated terminal maintains context and is familiar`,
+            mode: "ide",
+        });
+    }
+    else if (ide.hasIntegratedTerminal && ide.cliAvailable === false) {
+        // IDE detected but CLI missing — note it but don't recommend
+        recommendations.push({
+            option: `Open in ${ide.name} (CLI not installed)`,
+            priority: "low",
+            reason: `${ide.cliBinary || "CLI"} not in PATH. ${ide.cliInstallHint || "Install the CLI to enable this option."}`,
+            mode: "ide",
+        });
+    }
+    recommendations.push({
+        option: "Open in new terminal tab",
+        priority: ide.cliAvailable === false ? "high" : "medium",
+        reason: "Open in your current terminal emulator as a new tab",
+        mode: "terminal",
+    });
+    recommendations.push({
+        option: "Open in-app PTY",
+        priority: "medium",
+        reason: "Embedded terminal within this OpenCode session",
+        mode: "pty",
+    });
+    recommendations.push({
+        option: "Run in background",
+        priority: "low",
+        reason: "AI implements headlessly while you keep working here",
+        mode: "background",
+    });
+    recommendations.push({
+        option: "Stay in current session",
+        priority: "low",
+        reason: "Continue working in this terminal session",
+        mode: "stay",
+    });
+    return recommendations;
+}
+/**
+ * Format environment detection as a human-readable report.
+ * Used by the detect_environment tool.
+ */
+export function formatEnvironmentReport(ide, terminalName) {
+    const lines = [
+        `## Environment Detection`,
+        ``,
+        `**IDE/Editor:** ${ide.name}`,
+        `**Detection Method:** ${ide.detectionSource}`,
+        `**Terminal:** ${terminalName}`,
+        `**Platform:** ${process.platform}`,
+        ``,
+    ];
+    if (ide.version) {
+        lines.push(`**Version:** ${ide.version}`, ``);
+    }
+    lines.push(`### Capabilities`, ``);
+    if (ide.hasIntegratedTerminal) {
+        lines.push(`- ✓ Has integrated terminal`);
+    }
+    else {
+        lines.push(`- ✗ No integrated terminal`);
+    }
+    if (ide.canOpenInWindow) {
+        if (ide.cliAvailable === false) {
+            lines.push(`- ⚠ Can open new window via CLI — but \`${ide.cliBinary || "cli"}\` NOT found in PATH`);
+            if (ide.cliInstallHint) {
+                lines.push(`  Fix: ${ide.cliInstallHint}`);
+            }
+        }
+        else if (ide.cliAvailable === true) {
+            lines.push(`- ✓ Can open new window via CLI (\`${ide.cliBinary}\` available)`);
+        }
+        else {
+            lines.push(`- ✓ Can open new window via CLI`);
+        }
+    }
+    else {
+        lines.push(`- ✗ Cannot open new window via CLI`);
+    }
+    lines.push(``, `### Recommended Launch Options`, ``);
+    const recommendations = generateEnvironmentRecommendations(ide);
+    for (const rec of recommendations) {
+        const priorityBadge = rec.priority === "high" ? " (Recommended)" :
+            rec.priority === "medium" ? "" : "";
+        lines.push(`- **${rec.option}${priorityBadge}** — ${rec.reason}`);
+    }
+    return lines.join("\n");
+}

package/dist/utils/plan-extract.d.ts

@@ -13,6 +13,13 @@ export interface PlanSections {
     /** The raw plan filename */
     filename: string;
 }
+/**
+ * Extract GitHub issue references from plan frontmatter.
+ *
+ * Looks for `issues: [42, 51]` in YAML frontmatter.
+ * Returns an array of issue numbers, or an empty array if none found.
+ */
+export declare function extractIssueRefs(planContent: string): number[];
 /**
  * Extract relevant sections from a plan markdown file for composing a PR body.
  *

package/dist/utils/plan-extract.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"plan-extract.d.ts","sourceRoot":"","sources":["../../src/utils/plan-extract.ts"],"names":[],"mappings":"AAMA;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,mDAAmD;IACnD,KAAK,EAAE,MAAM,CAAC;IACd,2BAA2B;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,4CAA4C;IAC5C,KAAK,EAAE,MAAM,CAAC;IACd,4BAA4B;IAC5B,SAAS,EAAE,MAAM,CAAC;IAClB,4BAA4B;IAC5B,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,WAAW,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,YAAY,CAuCvF;AAmCD;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,YAAY,GAAG,MAAM,CAwBlE;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,MAAM,EAChB,YAAY,CAAC,EAAE,MAAM,EACrB,UAAU,CAAC,EAAE,MAAM,GAClB;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAqC9C"}
+{"version":3,"file":"plan-extract.d.ts","sourceRoot":"","sources":["../../src/utils/plan-extract.ts"],"names":[],"mappings":"AAMA;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,mDAAmD;IACnD,KAAK,EAAE,MAAM,CAAC;IACd,2BAA2B;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,4CAA4C;IAC5C,KAAK,EAAE,MAAM,CAAC;IACd,4BAA4B;IAC5B,SAAS,EAAE,MAAM,CAAC;IAClB,4BAA4B;IAC5B,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,EAAE,CAY9D;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,WAAW,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,YAAY,CAuCvF;AAmCD;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,YAAY,GAAG,MAAM,CAwBlE;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,MAAM,EAChB,YAAY,CAAC,EAAE,MAAM,EACrB,UAAU,CAAC,EAAE,MAAM,GAClB;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CA0C9C"}