@specship/specship-win32-arm64 0.13.0 → 0.14.0

package/lib/dist/mcp/jira-tools.js

@@ -0,0 +1,787 @@
+"use strict";
+/**
+ * JIRA MCP tools (REQ-JIRA-002, REQ-JIRA-003, REQ-JIRA-004).
+ *
+ * `specship_jira_issues` lists the issues assigned to the authenticated user
+ * (identity resolved from the token, never a typed name), optionally narrowed
+ * to a project. `specship_jira_issue` fetches a single issue by key with its
+ * full detail (description + subtasks). `specship_jira_pick` fetches an issue
+ * and authors a well-formed SpecShip spec from it under `specs/` (idempotent on
+ * the issue key). All read the user-level config, resolve credentials, and
+ * drive `JiraClient`.
+ *
+ * SECURITY (REQ-JIRA-009): the token is never surfaced. Every error path
+ * returns only the JiraError's own message — which by construction contains
+ * no credential — and the "not configured" path returns a plain pointer to
+ * `specship jira configure`, never a partial or fabricated result.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.jiraToolDefinitions = void 0;
+exports.handleSpecshipJiraIssues = handleSpecshipJiraIssues;
+exports.handleSpecshipJiraIssue = handleSpecshipJiraIssue;
+exports.handleSpecshipJiraPick = handleSpecshipJiraPick;
+exports.handleJiraRunCompletion = handleJiraRunCompletion;
+exports.handleSpecshipJiraStart = handleSpecshipJiraStart;
+exports.deriveWorkState = deriveWorkState;
+exports.handleSpecshipJiraTrack = handleSpecshipJiraTrack;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const crypto_1 = require("crypto");
+const config_1 = require("../jira/config");
+const client_1 = require("../jira/client");
+const types_1 = require("../jira/types");
+const spec_writer_1 = require("../jira/spec-writer");
+const spec_generator_1 = require("../jira/spec-generator");
+const pull_request_1 = require("../jira/pull-request");
+function textResult(text) {
+    return { content: [{ type: 'text', text }] };
+}
+function errorResult(message) {
+    return { content: [{ type: 'text', text: message }], isError: true };
+}
+/**
+ * Factory seam that resolves credentials and builds a live `JiraClient` for the
+ * status-push paths. The default resolves the user-level config; tests pass a
+ * `makeJiraClient` dep returning a fake so no host is contacted. Throws only if
+ * credentials are unresolvable — callers wrap it and degrade to a note, never a
+ * blocked workflow (REQ-JIRA-007, degrade-gracefully).
+ */
+function defaultMakeJiraClient() {
+    const creds = (0, config_1.resolveJiraCredentials)();
+    return {
+        client: new client_1.JiraClient(creds),
+        transitions: creds.transitions ?? {},
+    };
+}
+/**
+ * Push the "start" status to JIRA (REQ-JIRA-007.A1): assign the issue to the
+ * authenticated user and transition it toward "in progress". Returns a short
+ * human note describing what happened (assigned, moved, or skipped) — or `null`
+ * when there's nothing to say. NEVER throws: a JIRA hiccup (auth, network, a
+ * missing transition) must not block the local workflow from starting — the
+ * note simply reports the skip (reinforcement 4).
+ */
+async function pushJiraStartStatus(key, make) {
+    let ctx;
+    try {
+        ctx = make();
+    }
+    catch (err) {
+        return `Note: couldn't push start status to JIRA — ${errMsg(err)}`;
+    }
+    const notes = [];
+    // Assign to the authenticated user (identity resolved from the token).
+    try {
+        const conn = await ctx.client.testConnection();
+        if (conn.accountId) {
+            await ctx.client.assignIssue(key, conn.accountId);
+            notes.push(`assigned ${key} to you`);
+        }
+    }
+    catch (err) {
+        notes.push(`couldn't assign ${key} (${errMsg(err)})`);
+    }
+    // Transition toward "in progress" — a missing transition is a skip, not a
+    // failure (A3), and never blocks the run.
+    try {
+        const target = ctx.transitions.inProgress ?? 'In Progress';
+        const res = await ctx.client.transitionIssue(key, target);
+        if ('transitioned' in res) {
+            notes.push(`moved ${key} to "${res.transitioned}"`);
+        }
+        else {
+            notes.push(`didn't transition ${key} — ${res.reason}`);
+        }
+    }
+    catch (err) {
+        notes.push(`couldn't transition ${key} (${errMsg(err)})`);
+    }
+    return notes.length ? `JIRA: ${notes.join('; ')}.` : null;
+}
+/**
+ * Push the "PR raised" status to JIRA (REQ-JIRA-007.A2): transition the issue
+ * toward "in review" and comment the PR link on it. When the configured
+ * transition doesn't exist for this workflow, it still comments the PR link and
+ * reports the skip (A3) rather than erroring. Returns a human note. NEVER
+ * throws — a JIRA-side failure must not undo the raised PR.
+ *
+ * SECURITY: only the public PR URL + issue key are sent (REQ-JIRA-009).
+ */
+async function pushJiraReviewStatus(key, prUrl, make) {
+    let ctx;
+    try {
+        ctx = make();
+    }
+    catch (err) {
+        return `Note: couldn't push review status to JIRA — ${errMsg(err)}`;
+    }
+    const notes = [];
+    try {
+        const target = ctx.transitions.inReview ?? 'In Review';
+        const res = await ctx.client.transitionIssue(key, target);
+        if ('transitioned' in res) {
+            notes.push(`moved ${key} to "${res.transitioned}"`);
+        }
+        else {
+            // A3: the transition is unavailable — still comment, report the skip.
+            notes.push(`didn't transition ${key} — ${res.reason}`);
+        }
+    }
+    catch (err) {
+        notes.push(`couldn't transition ${key} (${errMsg(err)})`);
+    }
+    // The PR-link comment is posted regardless of the transition outcome (A3).
+    try {
+        await ctx.client.addComment(key, `SpecShip raised a pull request: ${prUrl}`);
+        notes.push(`commented the PR link on ${key}`);
+    }
+    catch (err) {
+        notes.push(`couldn't comment the PR link on ${key} (${errMsg(err)})`);
+    }
+    return notes.length ? `JIRA: ${notes.join('; ')}.` : null;
+}
+/** Extract a credential-free message from an unknown error (REQ-JIRA-009). */
+function errMsg(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+exports.jiraToolDefinitions = [
+    {
+        name: 'specship_jira_issues',
+        description: 'List the JIRA issues assigned to you (resolved from your configured ' +
+            'token — you never type your own name). Optionally narrow to a project.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                project: {
+                    type: 'string',
+                    description: 'Optional project key to narrow the list (e.g., "PROJ"). Omit to list all your assigned issues.',
+                },
+            },
+        },
+    },
+    {
+        name: 'specship_jira_issue',
+        description: 'Fetch a single JIRA issue by key (e.g., "PROJ-123") with its full ' +
+            'detail — summary, status, type, description, and any subtasks.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                key: {
+                    type: 'string',
+                    description: 'The issue key to fetch, e.g., "PROJ-123". Required.',
+                },
+            },
+            required: ['key'],
+        },
+    },
+    {
+        name: 'specship_jira_pick',
+        description: 'Pick a JIRA issue by key (e.g., "PROJ-123") and author a SpecShip spec ' +
+            'from it under specs/ — summary becomes the title, description the ' +
+            'requirement body, subtasks the acceptance criteria. Re-picking the same ' +
+            'issue updates its spec in place rather than creating a duplicate.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                key: {
+                    type: 'string',
+                    description: 'The issue key to pick, e.g., "PROJ-123". Required.',
+                },
+            },
+            required: ['key'],
+        },
+    },
+    {
+        name: 'specship_jira_start',
+        description: 'Start implementing a picked JIRA issue: run the bundled spec-implement ' +
+            'workflow on the spec that specship_jira_pick authored for the key, in an ' +
+            'isolated worktree. Runs to the plan/approve gate and stops there — review ' +
+            'the plan, then approve to proceed. Pick the issue first if no spec exists.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                key: {
+                    type: 'string',
+                    description: 'The issue key to start, e.g., "PROJ-123". Required. A spec for it ' +
+                        'must already exist (run specship_jira_pick first).',
+                },
+            },
+            required: ['key'],
+        },
+    },
+    {
+        name: 'specship_jira_track',
+        description: 'Show a read-only tracking view of every JIRA issue you have brought into ' +
+            "SpecShip: each row joins the issue's SpecShip work-state (spec authored → " +
+            'implementing → PR raised → verified) with its LIVE JIRA status (a fresh ' +
+            'read at track time, so an issue moved outside SpecShip reflects its current ' +
+            'status). Read-only — it never re-picks or re-starts anything. Optionally ' +
+            'narrow the JIRA read to a project.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                project: {
+                    type: 'string',
+                    description: 'Optional project key to narrow the live JIRA read (e.g., "PROJ"). Omit to read all your assigned issues.',
+                },
+            },
+        },
+    },
+];
+/** Render the issue list as compact markdown, or an explicit empty line. */
+function formatIssues(issues) {
+    if (issues.length === 0) {
+        return 'No issues assigned to you.';
+    }
+    const lines = issues.map(i => `- **${i.key}** — ${i.summary} — ${i.status} — ${i.issueType}`);
+    return `Issues assigned to you (${issues.length}):\n\n${lines.join('\n')}`;
+}
+/** Render a single issue's full detail as markdown. */
+function formatIssue(issue) {
+    const parts = [
+        `## ${issue.key} — ${issue.summary}`,
+        '',
+        `- **Status:** ${issue.status}`,
+        `- **Type:** ${issue.issueType}`,
+    ];
+    const description = issue.description?.trim();
+    parts.push('', '### Description', '', description || '_No description._');
+    if (issue.subtasks && issue.subtasks.length > 0) {
+        parts.push('', `### Subtasks (${issue.subtasks.length})`, '');
+        for (const st of issue.subtasks) {
+            parts.push(`- **${st.key}** — ${st.summary} — ${st.status}`);
+        }
+    }
+    return parts.join('\n');
+}
+/**
+ * The shared "not configured → clear pointer" gate for the JIRA tools. Returns
+ * a pointer `ToolResult` when neither a config file nor env credentials are
+ * present, or `null` when configured (the caller proceeds). Never an error
+ * stack or a fabricated result.
+ */
+function notConfiguredResult() {
+    let hasConfig = false;
+    try {
+        hasConfig = (0, config_1.loadJiraConfig)() !== null;
+    }
+    catch {
+        // A malformed config file still means "configured but broken" — fall
+        // through to resolveJiraCredentials, which surfaces the actionable message.
+        hasConfig = true;
+    }
+    const hasEnv = Boolean(process.env.SPECSHIP_JIRA_BASE_URL);
+    if (!hasConfig && !hasEnv) {
+        return textResult('JIRA is not configured. Run "specship jira configure" to connect a ' +
+            'JIRA Cloud or Data Center instance, then try again.');
+    }
+    return null;
+}
+/**
+ * Handle `specship_jira_issues`. Independent of the code graph — talks only
+ * to the configured JIRA host through the stored credentials.
+ */
+async function handleSpecshipJiraIssues(args) {
+    // Not configured → a clear pointer, never an error stack or a fabricated list.
+    const notConfigured = notConfiguredResult();
+    if (notConfigured)
+        return notConfigured;
+    const project = typeof args.project === 'string' && args.project.trim()
+        ? args.project.trim()
+        : undefined;
+    try {
+        const creds = (0, config_1.resolveJiraCredentials)();
+        const client = new client_1.JiraClient(creds);
+        const result = await client.listMyIssues({ project });
+        return textResult(formatIssues(result.issues));
+    }
+    catch (err) {
+        // JiraError messages are credential-free by construction (REQ-JIRA-009).
+        if (err instanceof types_1.JiraError) {
+            return errorResult(err.message);
+        }
+        // Defensive: never let an unexpected error leak internals.
+        return errorResult('Failed to list JIRA issues.');
+    }
+}
+/**
+ * Handle `specship_jira_issue` (REQ-JIRA-003). Fetches a single issue by key
+ * and renders its full detail. Independent of the code graph — talks only to
+ * the configured JIRA host. A missing/no-access key surfaces as an explicit
+ * tool error (A2), never a silent empty result.
+ */
+async function handleSpecshipJiraIssue(args) {
+    // Not configured → a clear pointer, never an error stack or a fabricated issue.
+    const notConfigured = notConfiguredResult();
+    if (notConfigured)
+        return notConfigured;
+    // A missing/blank key is a user mistake, not an internal fault — a clear
+    // message, not a stack.
+    const key = typeof args.key === 'string' && args.key.trim() ? args.key.trim() : undefined;
+    if (!key) {
+        return textResult('An issue key is required (e.g., "PROJ-123"). Pass it as the "key" argument.');
+    }
+    try {
+        const creds = (0, config_1.resolveJiraCredentials)();
+        const client = new client_1.JiraClient(creds);
+        const result = await client.getIssue(key);
+        return textResult(formatIssue(result.issue));
+    }
+    catch (err) {
+        // JiraError messages (incl. JiraNotFoundError for a missing/no-access key)
+        // are credential-free by construction (REQ-JIRA-009).
+        if (err instanceof types_1.JiraError) {
+            return errorResult(err.message);
+        }
+        // Defensive: never let an unexpected error leak internals.
+        return errorResult('Failed to fetch the JIRA issue.');
+    }
+}
+/**
+ * Handle `specship_jira_pick` (REQ-JIRA-004). Fetches a single issue by key
+ * (reusing the REQ-JIRA-003 path) and authors a well-formed SpecShip spec from
+ * it under `specs/`, idempotent on the issue key (A3). Independent of the code
+ * graph — talks only to the configured JIRA host. A missing/no-access key
+ * surfaces as a `JiraNotFoundError` → tool error, never a written empty spec.
+ *
+ * SECURITY: the issue summary/description/subtasks are untrusted content; the
+ * generator neutralizes any injected spec structure before embedding. No token
+ * appears in any output or error (REQ-JIRA-009).
+ */
+async function handleSpecshipJiraPick(args) {
+    // Not configured → a clear pointer, never an error stack or a written spec.
+    const notConfigured = notConfiguredResult();
+    if (notConfigured)
+        return notConfigured;
+    // A missing/blank key is a user mistake, not an internal fault.
+    const key = typeof args.key === 'string' && args.key.trim() ? args.key.trim() : undefined;
+    if (!key) {
+        return textResult('An issue key is required (e.g., "PROJ-123"). Pass it as the "key" argument.');
+    }
+    // The project whose specs/ directory receives the spec. Threaded through the
+    // handler args like the other tools' context, falling back to the cwd.
+    const projectRoot = typeof args.projectPath === 'string' && args.projectPath.trim()
+        ? args.projectPath.trim()
+        : process.cwd();
+    try {
+        const creds = (0, config_1.resolveJiraCredentials)();
+        const client = new client_1.JiraClient(creds);
+        const result = await client.getIssue(key);
+        const written = (0, spec_writer_1.writeSpecFromIssue)(result.issue, projectRoot);
+        const verb = written.created ? 'Created' : 'Updated';
+        return textResult(`${verb} spec for ${result.issue.key} at ${written.path}. ` +
+            'Run "specship sync" (or let the watcher pick it up) to index it, then ' +
+            `run specship_jira_start for ${result.issue.key} to implement it.`);
+    }
+    catch (err) {
+        // JiraError messages (incl. JiraNotFoundError for a missing/no-access key)
+        // are credential-free by construction (REQ-JIRA-009).
+        if (err instanceof types_1.JiraError) {
+            return errorResult(err.message);
+        }
+        // Defensive: never let an unexpected error leak internals.
+        return errorResult('Failed to pick the JIRA issue.');
+    }
+}
+/** Read `metadata.approval.message` off a run, tolerating any metadata shape. */
+function approvalMessageOf(run) {
+    const approval = run.metadata
+        ?.approval;
+    return typeof approval?.message === 'string' ? approval.message : undefined;
+}
+/**
+ * Re-read the persisted run so we see the settled status + approval metadata.
+ * `executor.start` returns the pre-finalize in-memory run whose status still
+ * reads "running" even after it paused at the approval gate; the DB row carries
+ * the real "paused" status + the approval message. Falls back to the returned
+ * run when the handle can't look it up (e.g. a stubbed executor in tests).
+ */
+function reloadRun(specQueries, run) {
+    const getById = specQueries?.getWorkflowRunById;
+    if (typeof getById !== 'function')
+        return run;
+    try {
+        return getById.call(specQueries, run.id) ?? run;
+    }
+    catch {
+        return run;
+    }
+}
+/** Read the H1 title out of a spec file, falling back to `fallback`. */
+function readSpecTitle(specPath, fallback) {
+    if (!specPath)
+        return fallback;
+    try {
+        const content = fs.readFileSync(specPath, 'utf8');
+        for (const raw of content.split(/\r?\n/)) {
+            const line = raw.trim();
+            const m = line.match(/^#\s+(.+)$/);
+            if (m)
+                return m[1].trim() || fallback;
+        }
+    }
+    catch {
+        /* fall through to the fallback */
+    }
+    return fallback;
+}
+/** Recover the `jira` metadata block off a run, tolerating any metadata shape. */
+function jiraMetaOf(run) {
+    const jira = run.metadata?.jira;
+    return jira && typeof jira === 'object' ? jira : undefined;
+}
+/**
+ * True when the run's verify leg RAN AND PASSED — the only state that raises a
+ * PR (REQ-JIRA-006.A1; aligns with REQ-JIRA-005.A2). A verify that FAILED halts
+ * the run before completion (status `failed`), and a SKIPPED verify
+ * (`VERIFY_RESULT=skipped`) completes the run but must NOT raise a PR — tests
+ * that did not run are never treated as a pass.
+ */
+function verifyPassed(run) {
+    const meta = run.metadata ?? {};
+    const states = meta.nodeStates;
+    if (states && states.verify && states.verify !== 'completed')
+        return false;
+    const outputs = meta.outputs;
+    const verifyText = outputs?.verify?.text ?? '';
+    return /VERIFY_RESULT=ran-and-passed/.test(verifyText);
+}
+/**
+ * Completion hook for a JIRA-started run (REQ-JIRA-006). Fires only once the
+ * run has settled to `completed`. Raises a PR — traceable to the issue via the
+ * key in the branch name, PR title, AND body — ONLY when the run's verify leg
+ * ran and passed. On any PR-tooling failure it surfaces the reason and leaves
+ * the branch + worktree fully intact for a manual PR (A3); it NEVER auto-merges
+ * or closes the PR (the human owns "done"). A non-JIRA run is a silent no-op.
+ *
+ * SECURITY: no JIRA token/secret appears in the PR title/body/logs — only the
+ * public issue key (REQ-JIRA-009).
+ */
+async function handleJiraRunCompletion(run, deps) {
+    const jira = jiraMetaOf(run);
+    const issueKey = jira?.issueKey;
+    if (!issueKey)
+        return null; // not a JIRA-started run — nothing to do.
+    const log = deps.log ?? ((m) => {
+        // eslint-disable-next-line no-console
+        console.log(m);
+    });
+    // A1: a completed-but-unverified run (verify skipped) raises NO PR.
+    if (!verifyPassed(run)) {
+        log(`Run for ${issueKey} completed but its verification did not pass — no ` +
+            'pull request was raised.');
+        return null;
+    }
+    if (!run.isolationEnvId) {
+        log(`Run for ${issueKey} completed but has no worktree on record — no pull ` +
+            'request was raised.');
+        return null;
+    }
+    const env = deps.getIsolationEnvById(run.isolationEnvId);
+    if (!env) {
+        log(`Run for ${issueKey} completed but its worktree could not be resolved — ` +
+            'no pull request was raised.');
+        return null;
+    }
+    const meta = env.metadata ?? {};
+    const repoRoot = (typeof meta.repoRoot === 'string' ? meta.repoRoot : undefined) ??
+        deps.projectRoot ??
+        process.cwd();
+    const specTitle = jira.title ?? jira.specId ?? issueKey;
+    const raise = deps.raisePullRequest ?? pull_request_1.raisePullRequest;
+    const outcome = await raise({
+        repoRoot,
+        branchName: env.branchName,
+        worktreePath: env.workingPath,
+        issueKey,
+        title: (0, pull_request_1.buildPrTitle)(issueKey, specTitle),
+        body: (0, pull_request_1.buildPrBody)(issueKey, specTitle),
+    });
+    if (outcome.ok) {
+        log(`Raised pull request for ${issueKey}: ${outcome.url}`);
+        // A2: PR raised → transition toward "in review" and comment the PR link.
+        // Only on a raised PR — a failed raise never advances the issue (below),
+        // matching REQ-JIRA-005.A2 (leave it in-progress). Never throws.
+        const make = deps.makeJiraClient ?? defaultMakeJiraClient;
+        const note = await pushJiraReviewStatus(issueKey, outcome.url, make);
+        if (note)
+            log(note);
+    }
+    else {
+        // A3 (of REQ-JIRA-006) / A2 (of REQ-JIRA-005): report the reason; the
+        // branch + worktree are left intact upstream and the issue is NOT
+        // transitioned (it stays in-progress).
+        log(outcome.message);
+    }
+    return outcome;
+}
+/**
+ * Handle `specship_jira_start` (REQ-JIRA-005). Drives the bundled
+ * `spec-implement` workflow on the spec `specship_jira_pick` authored for the
+ * issue key, in an isolated worktree, and runs it to the first pause — the
+ * plan/approve gate (A1). It does NOT block for the full implementation.
+ *
+ * On the non-failed path it pushes the "start" status back to JIRA
+ * (REQ-JIRA-007.A1): assigns the issue and transitions it toward "in progress".
+ * That push NEVER blocks the workflow — a JIRA hiccup (auth, network, a missing
+ * transition) is surfaced as a note, not an error. A failed/rejected run
+ * (REQ-JIRA-005.A2) raises no PR and is never advanced past "in progress"; the
+ * "in review" transition + PR comment (REQ-JIRA-007.A2) fire only once the run
+ * reaches `completed` with a verified, raised PR.
+ *
+ * SECURITY: the credential is handled only inside `JiraClient` and never
+ * echoed (REQ-JIRA-009); only the public issue key / PR URL are surfaced.
+ */
+async function handleSpecshipJiraStart(args, deps) {
+    // Not configured → a clear pointer, never an error stack or a started run.
+    const notConfigured = notConfiguredResult();
+    if (notConfigured)
+        return notConfigured;
+    // A missing/blank key is a user mistake, not an internal fault.
+    const key = typeof args.key === 'string' && args.key.trim() ? args.key.trim() : undefined;
+    if (!key) {
+        return textResult('An issue key is required (e.g., "PROJ-123"). Pass it as the "key" argument.');
+    }
+    const projectRoot = deps.projectRoot;
+    const specId = (0, spec_generator_1.reqIdForIssue)(key);
+    // The spec must already exist — start never silently authors one. If it's
+    // absent, point the caller at specship_jira_pick (which writes the spec keyed
+    // on this exact issue key, so start then targets the same SPEC_ID).
+    const specPath = (0, spec_writer_1.findSpecForIssueKey)(key, projectRoot);
+    if (!specPath) {
+        return textResult(`No spec for ${key} was found under specs/. Run specship_jira_pick for ` +
+            `${key} first to author it, then run specship_jira_start again.`);
+    }
+    const specTitle = readSpecTitle(specPath, specId);
+    try {
+        const loadWorkflowByName = deps.loadWorkflowByName ??
+            (await Promise.resolve().then(() => __importStar(require('../workflows/discovery')))).loadWorkflowByName;
+        const WorktreeProvider = deps.WorktreeProvider ??
+            (await Promise.resolve().then(() => __importStar(require('../isolation/worktree')))).WorktreeProvider;
+        const WorkflowExecutor = deps.WorkflowExecutor ??
+            (await Promise.resolve().then(() => __importStar(require('../workflows/executor')))).WorkflowExecutor;
+        const getSpecShipDir = deps.getSpecShipDir ?? (await Promise.resolve().then(() => __importStar(require('../directory')))).getSpecShipDir;
+        const loaded = loadWorkflowByName(projectRoot, 'spec-implement');
+        if (!loaded) {
+            return errorResult('The bundled "spec-implement" workflow was not found. Reinstall ' +
+                'SpecShip or check `specship workflow list`.');
+        }
+        // Carry the issue key in the branch name too (specship/<key>-<shortRunId>)
+        // so JIRA's dev panel matches on branch + PR title + PR body (REQ-JIRA-006).
+        const runId = (0, crypto_1.randomUUID)();
+        const shortRunId = runId.substring(0, 8);
+        const branchSlug = key.replace(/[^A-Za-z0-9._/-]/g, '-').replace(/-+/g, '-');
+        const branchName = `specship/${branchSlug}-${shortRunId}`;
+        // Completion deps: the PR is raised only when the run later resumes to
+        // `completed` with a passing verify. Non-JIRA runs no-op this hook.
+        const completionDeps = {
+            getIsolationEnvById: deps.getIsolationEnvById ??
+                ((id) => deps.specQueries.getIsolationEnvById?.(id)),
+            raisePullRequest: deps.raisePullRequest,
+            projectRoot,
+            makeJiraClient: deps.makeJiraClient,
+        };
+        const worktrees = new WorktreeProvider(deps.specQueries);
+        const executor = new WorkflowExecutor(deps.specQueries, worktrees, projectRoot, async (completedRun) => {
+            await handleJiraRunCompletion(completedRun, completionDeps);
+        });
+        const started = await executor.start(loaded.workflow, {
+            runId,
+            branchName,
+            projectRoot,
+            inputs: { SPEC_ID: specId },
+            variables: {
+                ARTIFACTS_DIR: path.join(getSpecShipDir(projectRoot), 'artifacts'),
+                CONTEXT: projectRoot,
+            },
+            runMetadata: { jira: { issueKey: key, specId, title: specTitle } },
+        });
+        const run = reloadRun(deps.specQueries, started.run);
+        if (run.status === 'failed') {
+            // A2: a failed run raises no PR and never advances the issue past
+            // "in progress" — the issue is not transitioned by this handler.
+            const why = run.errorMessage ? ` ${run.errorMessage}` : '';
+            return errorResult(`Implementation run for ${key} (${specId}) failed and no pull request ` +
+                `was raised.${why}`);
+        }
+        // A1 (REQ-JIRA-007): the run started, so push the "start" status —
+        // assign the issue + transition it toward "in progress". This runs only on
+        // the non-failed path (the run reached the gate); a JIRA hiccup here NEVER
+        // blocks the workflow — pushJiraStartStatus never throws and its note is
+        // surfaced in the returned text (reinforcement 4).
+        const startNote = await pushJiraStartStatus(key, deps.makeJiraClient ?? defaultMakeJiraClient);
+        // A1: the run reached the plan/approve gate and paused. Surface the
+        // approval message + runId; the caller approves (or rejects) to continue.
+        const gate = approvalMessageOf(run);
+        return textResult(`Started spec-implement for ${key} (${specId}). Run ${run.id} is paused ` +
+            `at the plan/approve gate — review the plan and approve to proceed.` +
+            (startNote ? `\n\n${startNote}` : '') +
+            (gate ? `\n\n${gate}` : '') +
+            `\n\nApprove with: specship workflow approve ${run.id}` +
+            `\nOr reject with feedback: specship workflow reject ${run.id} --comment "…"` +
+            `\n\nOnce approved and the implementation completes and verifies, a pull ` +
+            `request for ${key} is raised automatically (its key is carried on the ` +
+            `branch, PR title, and body so JIRA links it back).`);
+    }
+    catch (err) {
+        // Defensive: never let an unexpected error leak internals.
+        return errorResult(`Failed to start implementation for ${key}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+/**
+ * Map a workflow run to its SpecShip lifecycle work-state (REQ-JIRA-008). Pure
+ * — reads only the run's status + metadata, most-advanced stage first:
+ *   - verify ran and passed → `verified` (the terminal success),
+ *   - a raised-PR marker on the run → `PR raised`,
+ *   - running/paused → `implementing`,
+ *   - anything else (pending/failed/cancelled/completed-without-markers) → the
+ *     spec exists but no implementation has landed → `spec authored`.
+ */
+function deriveWorkState(run) {
+    if (verifyPassed(run))
+        return 'verified';
+    const jira = jiraMetaOf(run);
+    if (jira && typeof jira.prUrl === 'string' && jira.prUrl.trim()) {
+        return 'PR raised';
+    }
+    const status = run.status;
+    if (status === 'running' || status === 'paused')
+        return 'implementing';
+    return 'spec authored';
+}
+/** Factory seam that builds a live track client from the resolved credentials. */
+function defaultMakeTrackClient() {
+    const creds = (0, config_1.resolveJiraCredentials)();
+    return new client_1.JiraClient(creds);
+}
+const JIRA_UNREACHABLE = '— (JIRA unreachable)';
+/** Render the tracking rows as a compact markdown table (REQ-JIRA-008). */
+function formatTrack(rows) {
+    if (rows.length === 0) {
+        return 'No picked issues yet — run specship_jira_pick first.';
+    }
+    const lines = [
+        '| Issue | SpecShip | JIRA |',
+        '| --- | --- | --- |',
+        ...rows.map((r) => `| **${r.issueKey}** — ${r.title} | ${r.workState} | ${r.jiraStatus} |`),
+    ];
+    return `Tracking ${rows.length} picked issue${rows.length === 1 ? '' : 's'}:\n\n${lines.join('\n')}`;
+}
+/**
+ * Handle `specship_jira_track` (REQ-JIRA-008). A read-only view joining each
+ * picked issue's SpecShip work-state (from its workflow run) with its LIVE JIRA
+ * status (a fresh read at track time — never the pick-time cached metadata, so
+ * an issue moved outside SpecShip shows its current status). It never re-picks
+ * or re-starts anything.
+ *
+ * Runs are enumerated newest-first and deduped by issue key keeping the
+ * most-recent run. A JIRA read failure degrades PER ROW to a clear "unreachable"
+ * marker and never fails the whole view (degrade-gracefully, matching the
+ * sibling status tools).
+ *
+ * SECURITY: no token appears in any output or error (REQ-JIRA-009) — only public
+ * issue keys, titles, and statuses.
+ */
+async function handleSpecshipJiraTrack(args, deps) {
+    // Not configured → a clear pointer, never an error stack or a fabricated view.
+    const notConfigured = notConfiguredResult();
+    if (notConfigured)
+        return notConfigured;
+    const project = typeof args.project === 'string' && args.project.trim()
+        ? args.project.trim()
+        : undefined;
+    // Enumerate the runs that record which issues entered the SpecShip pipeline,
+    // keeping only JIRA-started runs and deduping by key (newest-first, so the
+    // first occurrence is the most-recent run — reinforcement 3).
+    const limit = typeof deps.limit === 'number' && deps.limit > 0 ? deps.limit : 200;
+    const getAll = deps.specQueries.getAllWorkflowRuns;
+    const runs = typeof getAll === 'function' ? getAll.call(deps.specQueries, limit) ?? [] : [];
+    const picked = [];
+    const seen = new Set();
+    for (const run of runs) {
+        const jira = jiraMetaOf(run);
+        const issueKey = jira?.issueKey;
+        if (!issueKey || seen.has(issueKey))
+            continue;
+        seen.add(issueKey);
+        picked.push({
+            issueKey,
+            title: jira?.title?.trim() || issueKey,
+            workState: deriveWorkState(run),
+        });
+    }
+    if (picked.length === 0) {
+        return textResult(formatTrack([]));
+    }
+    // Fresh JIRA read (reinforcement 1: the JIRA column is ALWAYS from this live
+    // read, never the pick-time cached metadata). A whole-read failure degrades
+    // every row; a per-key fallback failure degrades only that row.
+    const make = deps.makeJiraClient ?? defaultMakeTrackClient;
+    let client;
+    let listStatuses;
+    try {
+        client = make();
+        const listed = await client.listMyIssues({ project });
+        listStatuses = new Map(listed.issues.map((i) => [i.key, i.status]));
+    }
+    catch {
+        // The assigned-issues read failed entirely — every row degrades (per-row).
+        listStatuses = undefined;
+    }
+    const rows = [];
+    for (const p of picked) {
+        let jiraStatus = JIRA_UNREACHABLE;
+        if (listStatuses) {
+            const live = listStatuses.get(p.issueKey);
+            if (live !== undefined) {
+                jiraStatus = live;
+            }
+            else if (client) {
+                // No longer in the assigned list — a single live read still tracks it.
+                try {
+                    const single = await client.getIssue(p.issueKey);
+                    jiraStatus = single.issue.status;
+                }
+                catch {
+                    jiraStatus = JIRA_UNREACHABLE;
+                }
+            }
+        }
+        rows.push({ ...p, jiraStatus });
+    }
+    return textResult(formatTrack(rows));
+}
+//# sourceMappingURL=jira-tools.js.map