@specship/specship-win32-arm64 0.13.0 → 0.14.0

package/lib/dist/jira/config.js

@@ -0,0 +1,178 @@
+"use strict";
+/**
+ * JIRA config load / resolve / save (REQ-JIRA-001, A2).
+ *
+ * Config lives at `~/.specship/jira.json` — **user-level only, never in
+ * the project tree** (not even a gitignored project file), because it
+ * holds a secret. The path is overridable via `SPECSHIP_JIRA_CONFIG`
+ * (mirrors `SPECSHIP_SERVER_CONFIG`) so tests never touch the real home.
+ */
+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.jiraConfigPath = jiraConfigPath;
+exports.loadJiraConfig = loadJiraConfig;
+exports.inferDeployment = inferDeployment;
+exports.resolveJiraCredentials = resolveJiraCredentials;
+exports.saveJiraConfig = saveJiraConfig;
+const fs = __importStar(require("fs"));
+const os = __importStar(require("os"));
+const path = __importStar(require("path"));
+const shared_1 = require("../installer/targets/shared");
+const types_1 = require("./types");
+/**
+ * Absolute path to the user-level JIRA config. Overridable via
+ * `SPECSHIP_JIRA_CONFIG` for tests. Never project-scoped.
+ */
+function jiraConfigPath() {
+    return (process.env.SPECSHIP_JIRA_CONFIG ??
+        path.join(os.homedir(), '.specship', 'jira.json'));
+}
+/**
+ * Read `~/.specship/jira.json`. Returns `null` when the file is absent.
+ * Throws `JiraConfigError` when it exists but is malformed — a corrupt
+ * secret file is a hard error, not a silent fall-through to `{}`.
+ */
+function loadJiraConfig() {
+    const file = jiraConfigPath();
+    let raw;
+    try {
+        raw = fs.readFileSync(file, 'utf-8');
+    }
+    catch {
+        return null; // absent → not configured
+    }
+    try {
+        const parsed = JSON.parse(raw);
+        if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+            throw new types_1.JiraConfigError(`JIRA config at ${file} is not a JSON object. Re-run "specship jira configure".`);
+        }
+        return parsed;
+    }
+    catch (err) {
+        if (err instanceof types_1.JiraConfigError)
+            throw err;
+        throw new types_1.JiraConfigError(`JIRA config at ${file} is not valid JSON. Re-run "specship jira configure".`);
+    }
+}
+/**
+ * Infer the deployment kind from which credentials are present. An
+ * explicit `deployment` field always wins. Otherwise: a PAT (with no
+ * email+token pair) ⇒ Data Center; an email+token pair ⇒ Cloud.
+ */
+function inferDeployment(creds) {
+    if (creds.deployment)
+        return creds.deployment;
+    const hasBasic = Boolean(creds.email && creds.apiToken);
+    const hasPat = Boolean(creds.pat);
+    if (hasPat && !hasBasic)
+        return 'datacenter';
+    if (hasBasic)
+        return 'cloud';
+    if (hasPat)
+        return 'datacenter';
+    throw new types_1.JiraConfigError('Cannot infer JIRA deployment: provide either an email + API token (Cloud) ' +
+        'or a personal access token (Data Center).');
+}
+/**
+ * Resolve effective credentials from environment (highest precedence,
+ * per-field) then the on-disk config. Throws `JiraConfigError` with an
+ * actionable message when required fields are missing or malformed.
+ *
+ * SECURITY: the thrown messages never include a token or PAT value.
+ */
+function resolveJiraCredentials() {
+    const file = loadJiraConfig(); // may throw on malformed
+    const baseUrl = process.env.SPECSHIP_JIRA_BASE_URL ?? file?.baseUrl;
+    const email = process.env.SPECSHIP_JIRA_EMAIL ?? file?.email;
+    const apiToken = process.env.SPECSHIP_JIRA_API_TOKEN ?? file?.apiToken;
+    const pat = process.env.SPECSHIP_JIRA_PAT ?? file?.pat;
+    const explicitDeployment = normalizeDeployment(process.env.SPECSHIP_JIRA_DEPLOYMENT ?? file?.deployment);
+    if (!baseUrl) {
+        throw new types_1.JiraConfigError('No JIRA base URL configured. Run "specship jira configure" or set ' +
+            'SPECSHIP_JIRA_BASE_URL.');
+    }
+    // Lifecycle transition names (REQ-JIRA-007): env overrides file, per field;
+    // an unconfigured project keeps the defaults so status-push still works.
+    const inProgress = process.env.SPECSHIP_JIRA_TRANSITION_IN_PROGRESS ??
+        file?.transitions?.inProgress ??
+        'In Progress';
+    const inReview = process.env.SPECSHIP_JIRA_TRANSITION_IN_REVIEW ??
+        file?.transitions?.inReview ??
+        'In Review';
+    const deployment = inferDeployment({
+        deployment: explicitDeployment,
+        email,
+        apiToken,
+        pat,
+    });
+    if (deployment === 'cloud' && !(email && apiToken)) {
+        throw new types_1.JiraConfigError('JIRA Cloud requires both an email and an API token. Run ' +
+            '"specship jira configure".');
+    }
+    if (deployment === 'datacenter' && !pat) {
+        throw new types_1.JiraConfigError('JIRA Data Center requires a personal access token. Run ' +
+            '"specship jira configure".');
+    }
+    return {
+        baseUrl,
+        deployment,
+        email,
+        apiToken,
+        pat,
+        transitions: { inProgress, inReview },
+    };
+}
+/**
+ * Persist config to `~/.specship/jira.json` with `0600` permissions —
+ * it holds a secret, so it must not be group/world readable.
+ */
+function saveJiraConfig(config) {
+    const file = jiraConfigPath();
+    (0, shared_1.writeJsonFile)(file, config);
+    try {
+        fs.chmodSync(file, 0o600);
+    }
+    catch {
+        /* best-effort on platforms without POSIX perms (Windows) */
+    }
+}
+function normalizeDeployment(value) {
+    if (value === undefined)
+        return undefined;
+    if (value === 'cloud' || value === 'datacenter')
+        return value;
+    throw new types_1.JiraConfigError(`Unknown JIRA deployment "${value}". Use "cloud" or "datacenter".`);
+}
+//# sourceMappingURL=config.js.map

package/lib/dist/jira/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../../src/jira/config.ts"],"names":[],"mappings":";AAAA;;;;;;;GAOG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAiBH,wCAKC;AAOD,wCAsBC;AAOD,0CAgBC;AASD,wDAyDC;AAMD,wCAQC;AAxJD,uCAAyB;AACzB,uCAAyB;AACzB,2CAA6B;AAC7B,wDAA4D;AAC5D,mCAKiB;AAEjB;;;GAGG;AACH,SAAgB,cAAc;IAC5B,OAAO,CACL,OAAO,CAAC,GAAG,CAAC,oBAAoB;QAChC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,EAAE,WAAW,EAAE,WAAW,CAAC,CAClD,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,SAAgB,cAAc;IAC5B,MAAM,IAAI,GAAG,cAAc,EAAE,CAAC;IAC9B,IAAI,GAAW,CAAC;IAChB,IAAI,CAAC;QACH,GAAG,GAAG,EAAE,CAAC,YAAY,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;IACvC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC,CAAC,0BAA0B;IACzC,CAAC;IACD,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QAC/B,IAAI,CAAC,MAAM,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;YACnE,MAAM,IAAI,uBAAe,CACvB,kBAAkB,IAAI,0DAA0D,CACjF,CAAC;QACJ,CAAC;QACD,OAAO,MAAoB,CAAC;IAC9B,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,IAAI,GAAG,YAAY,uBAAe;YAAE,MAAM,GAAG,CAAC;QAC9C,MAAM,IAAI,uBAAe,CACvB,kBAAkB,IAAI,uDAAuD,CAC9E,CAAC;IACJ,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,SAAgB,eAAe,CAAC,KAK/B;IACC,IAAI,KAAK,CAAC,UAAU;QAAE,OAAO,KAAK,CAAC,UAAU,CAAC;IAC9C,MAAM,QAAQ,GAAG,OAAO,CAAC,KAAK,CAAC,KAAK,IAAI,KAAK,CAAC,QAAQ,CAAC,CAAC;IACxD,MAAM,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAClC,IAAI,MAAM,IAAI,CAAC,QAAQ;QAAE,OAAO,YAAY,CAAC;IAC7C,IAAI,QAAQ;QAAE,OAAO,OAAO,CAAC;IAC7B,IAAI,MAAM;QAAE,OAAO,YAAY,CAAC;IAChC,MAAM,IAAI,uBAAe,CACvB,4EAA4E;QAC1E,2CAA2C,CAC9C,CAAC;AACJ,CAAC;AAED;;;;;;GAMG;AACH,SAAgB,sBAAsB;IACpC,MAAM,IAAI,GAAG,cAAc,EAAE,CAAC,CAAC,yBAAyB;IAExD,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,sBAAsB,IAAI,IAAI,EAAE,OAAO,CAAC;IACpE,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,mBAAmB,IAAI,IAAI,EAAE,KAAK,CAAC;IAC7D,MAAM,QAAQ,GAAG,OAAO,CAAC,GAAG,CAAC,uBAAuB,IAAI,IAAI,EAAE,QAAQ,CAAC;IACvE,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,iBAAiB,IAAI,IAAI,EAAE,GAAG,CAAC;IACvD,MAAM,kBAAkB,GAAG,mBAAmB,CAC5C,OAAO,CAAC,GAAG,CAAC,wBAAwB,IAAI,IAAI,EAAE,UAAU,CACzD,CAAC;IAEF,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,MAAM,IAAI,uBAAe,CACvB,oEAAoE;YAClE,yBAAyB,CAC5B,CAAC;IACJ,CAAC;IAED,4EAA4E;IAC5E,yEAAyE;IACzE,MAAM,UAAU,GACd,OAAO,CAAC,GAAG,CAAC,oCAAoC;QAChD,IAAI,EAAE,WAAW,EAAE,UAAU;QAC7B,aAAa,CAAC;IAChB,MAAM,QAAQ,GACZ,OAAO,CAAC,GAAG,CAAC,kCAAkC;QAC9C,IAAI,EAAE,WAAW,EAAE,QAAQ;QAC3B,WAAW,CAAC;IAEd,MAAM,UAAU,GAAG,eAAe,CAAC;QACjC,UAAU,EAAE,kBAAkB;QAC9B,KAAK;QACL,QAAQ;QACR,GAAG;KACJ,CAAC,CAAC;IAEH,IAAI,UAAU,KAAK,OAAO,IAAI,CAAC,CAAC,KAAK,IAAI,QAAQ,CAAC,EAAE,CAAC;QACnD,MAAM,IAAI,uBAAe,CACvB,0DAA0D;YACxD,4BAA4B,CAC/B,CAAC;IACJ,CAAC;IACD,IAAI,UAAU,KAAK,YAAY,IAAI,CAAC,GAAG,EAAE,CAAC;QACxC,MAAM,IAAI,uBAAe,CACvB,yDAAyD;YACvD,4BAA4B,CAC/B,CAAC;IACJ,CAAC;IAED,OAAO;QACL,OAAO;QACP,UAAU;QACV,KAAK;QACL,QAAQ;QACR,GAAG;QACH,WAAW,EAAE,EAAE,UAAU,EAAE,QAAQ,EAAE;KACtC,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,SAAgB,cAAc,CAAC,MAAkB;IAC/C,MAAM,IAAI,GAAG,cAAc,EAAE,CAAC;IAC9B,IAAA,sBAAa,EAAC,IAAI,EAAE,MAA4C,CAAC,CAAC;IAClE,IAAI,CAAC;QACH,EAAE,CAAC,SAAS,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;IAC5B,CAAC;IAAC,MAAM,CAAC;QACP,4DAA4D;IAC9D,CAAC;AACH,CAAC;AAED,SAAS,mBAAmB,CAC1B,KAAyB;IAEzB,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IAC1C,IAAI,KAAK,KAAK,OAAO,IAAI,KAAK,KAAK,YAAY;QAAE,OAAO,KAAK,CAAC;IAC9D,MAAM,IAAI,uBAAe,CACvB,4BAA4B,KAAK,iCAAiC,CACnE,CAAC;AACJ,CAAC"}

package/lib/dist/jira/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * JIRA connection module (REQ-JIRA-001). Barrel re-export.
+ */
+export * from './types';
+export * from './config';
+export * from './auth';
+export * from './client';
+//# sourceMappingURL=index.d.ts.map

package/lib/dist/jira/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/jira/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,cAAc,SAAS,CAAC;AACxB,cAAc,UAAU,CAAC;AACzB,cAAc,QAAQ,CAAC;AACvB,cAAc,UAAU,CAAC"}

package/lib/dist/jira/index.js

@@ -0,0 +1,24 @@
+"use strict";
+/**
+ * JIRA connection module (REQ-JIRA-001). Barrel re-export.
+ */
+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 __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./types"), exports);
+__exportStar(require("./config"), exports);
+__exportStar(require("./auth"), exports);
+__exportStar(require("./client"), exports);
+//# sourceMappingURL=index.js.map

package/lib/dist/jira/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/jira/index.ts"],"names":[],"mappings":";AAAA;;GAEG;;;;;;;;;;;;;;;;AAEH,0CAAwB;AACxB,2CAAyB;AACzB,yCAAuB;AACvB,2CAAyB"}

package/lib/dist/jira/pull-request.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Raise a pull request for a completed, verified JIRA implementation run
+ * (REQ-JIRA-006).
+ *
+ * The flow is driven entirely through the repo's EXISTING PR tooling — the
+ * GitHub CLI (`gh`) plus `git` — so SpecShip never re-implements auth or the
+ * host API. Every step goes through an injectable shell seam so the test suite
+ * can assert the command shapes WITHOUT ever running a real `git push` or
+ * `gh pr create` (which would push branches / open real PRs).
+ *
+ * Guarantees:
+ *   - A3: if `gh` is missing or unauthenticated, or the push fails, we return
+ *     the reason and DO NOTHING destructive — the caller leaves the branch +
+ *     worktree fully intact for a manual PR. This helper never removes a
+ *     worktree or deletes a branch.
+ *   - A1/A2: the PR title and body embed the issue key (also carried by the
+ *     branch name) so JIRA's development panel links the PR back to the ticket.
+ *   - REQ-JIRA-009: no credential/secret is handled or echoed here — only the
+ *     public issue key ever appears in the title/body.
+ */
+/** Result of a single shell invocation through the seam. */
+export interface ShellResult {
+    status: number | null;
+    stdout: string;
+    stderr: string;
+}
+/** Injectable shell runner — stubbed in tests, real `spawnSync` in prod. */
+export type ShellRunner = (command: string, args: string[], cwd?: string) => ShellResult;
+/** Discriminated outcome of a PR-raise attempt. */
+export type PullRequestOutcome = {
+    ok: true;
+    url: string;
+} | {
+    ok: false;
+    reason: 'gh-missing' | 'gh-unauthenticated' | 'push-failed' | 'create-failed';
+    message: string;
+};
+export interface RaisePullRequestOptions {
+    /** Project root (the git repo the worktree branches from). */
+    repoRoot: string;
+    /** The worktree branch carrying the implementation (and the issue key). */
+    branchName: string;
+    /** Filesystem path of the worktree the push/PR is created from. */
+    worktreePath: string;
+    /** The source JIRA issue key (for the caller's title/body; embedded already). */
+    issueKey: string;
+    /** PR title (build with `buildPrTitle`). */
+    title: string;
+    /** PR body (build with `buildPrBody`). */
+    body: string;
+    /** Shell seam override (default: `spawnSync`). Tests always pass a stub. */
+    shell?: ShellRunner;
+}
+/**
+ * The PR title (A1): `<ISSUE-KEY>: <spec title>`. The leading key makes the PR
+ * traceable to the ticket at a glance and is one of the three places JIRA's dev
+ * panel matches (branch name + PR title + PR body).
+ */
+export declare function buildPrTitle(issueKey: string, specTitle: string): string;
+/**
+ * The PR body (A2): the key sits on its OWN line (`Closes <KEY>` + `JIRA: <KEY>`)
+ * so JIRA's development panel links the PR back to the issue. No token/secret is
+ * ever embedded — only the public key (REQ-JIRA-009).
+ */
+export declare function buildPrBody(issueKey: string, specTitle: string): string;
+/**
+ * Raise a PR for a verified run. Probes `gh`, pushes the branch, then creates
+ * the PR — returning early with a reason on the first failure and NEVER
+ * touching the branch or worktree so the work is recoverable (A3).
+ */
+export declare function raisePullRequest(opts: RaisePullRequestOptions): Promise<PullRequestOutcome>;
+//# sourceMappingURL=pull-request.d.ts.map

package/lib/dist/jira/pull-request.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pull-request.d.ts","sourceRoot":"","sources":["../../src/jira/pull-request.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAIH,4DAA4D;AAC5D,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,4EAA4E;AAC5E,MAAM,MAAM,WAAW,GAAG,CACxB,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EAAE,EACd,GAAG,CAAC,EAAE,MAAM,KACT,WAAW,CAAC;AAEjB,mDAAmD;AACnD,MAAM,MAAM,kBAAkB,GAC1B;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GACzB;IACE,EAAE,EAAE,KAAK,CAAC;IACV,MAAM,EAAE,YAAY,GAAG,oBAAoB,GAAG,aAAa,GAAG,eAAe,CAAC;IAC9E,OAAO,EAAE,MAAM,CAAC;CACjB,CAAC;AAEN,MAAM,WAAW,uBAAuB;IACtC,8DAA8D;IAC9D,QAAQ,EAAE,MAAM,CAAC;IACjB,2EAA2E;IAC3E,UAAU,EAAE,MAAM,CAAC;IACnB,mEAAmE;IACnE,YAAY,EAAE,MAAM,CAAC;IACrB,iFAAiF;IACjF,QAAQ,EAAE,MAAM,CAAC;IACjB,4CAA4C;IAC5C,KAAK,EAAE,MAAM,CAAC;IACd,0CAA0C;IAC1C,IAAI,EAAE,MAAM,CAAC;IACb,4EAA4E;IAC5E,KAAK,CAAC,EAAE,WAAW,CAAC;CACrB;AAiBD;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAGxE;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAavE;AASD;;;;GAIG;AACH,wBAAsB,gBAAgB,CACpC,IAAI,EAAE,uBAAuB,GAC5B,OAAO,CAAC,kBAAkB,CAAC,CA0D7B"}

package/lib/dist/jira/pull-request.js

@@ -0,0 +1,127 @@
+"use strict";
+/**
+ * Raise a pull request for a completed, verified JIRA implementation run
+ * (REQ-JIRA-006).
+ *
+ * The flow is driven entirely through the repo's EXISTING PR tooling — the
+ * GitHub CLI (`gh`) plus `git` — so SpecShip never re-implements auth or the
+ * host API. Every step goes through an injectable shell seam so the test suite
+ * can assert the command shapes WITHOUT ever running a real `git push` or
+ * `gh pr create` (which would push branches / open real PRs).
+ *
+ * Guarantees:
+ *   - A3: if `gh` is missing or unauthenticated, or the push fails, we return
+ *     the reason and DO NOTHING destructive — the caller leaves the branch +
+ *     worktree fully intact for a manual PR. This helper never removes a
+ *     worktree or deletes a branch.
+ *   - A1/A2: the PR title and body embed the issue key (also carried by the
+ *     branch name) so JIRA's development panel links the PR back to the ticket.
+ *   - REQ-JIRA-009: no credential/secret is handled or echoed here — only the
+ *     public issue key ever appears in the title/body.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildPrTitle = buildPrTitle;
+exports.buildPrBody = buildPrBody;
+exports.raisePullRequest = raisePullRequest;
+const child_process_1 = require("child_process");
+/** The default shell runner — wraps `spawnSync`. Never used under test. */
+function defaultShell(command, args, cwd) {
+    const r = (0, child_process_1.spawnSync)(command, args, {
+        cwd,
+        encoding: 'utf-8',
+        windowsHide: true,
+    });
+    return {
+        // ENOENT (command not found) surfaces as a null status — treat as failure.
+        status: r.status,
+        stdout: (r.stdout ?? '').toString(),
+        stderr: (r.stderr ?? '').toString(),
+    };
+}
+/**
+ * The PR title (A1): `<ISSUE-KEY>: <spec title>`. The leading key makes the PR
+ * traceable to the ticket at a glance and is one of the three places JIRA's dev
+ * panel matches (branch name + PR title + PR body).
+ */
+function buildPrTitle(issueKey, specTitle) {
+    const title = specTitle.trim() || issueKey;
+    return `${issueKey}: ${title}`;
+}
+/**
+ * The PR body (A2): the key sits on its OWN line (`Closes <KEY>` + `JIRA: <KEY>`)
+ * so JIRA's development panel links the PR back to the issue. No token/secret is
+ * ever embedded — only the public key (REQ-JIRA-009).
+ */
+function buildPrBody(issueKey, specTitle) {
+    const title = specTitle.trim();
+    const lines = [
+        `Implements ${issueKey}${title ? `: ${title}` : ''}.`,
+        '',
+        'Raised automatically by SpecShip after the implementation completed and',
+        'its verification step passed.',
+        '',
+        // The key on its own line is what JIRA's dev panel matches on.
+        `Closes ${issueKey}`,
+        `JIRA: ${issueKey}`,
+    ];
+    return lines.join('\n');
+}
+/** Pull the created PR URL out of `gh pr create` stdout (it prints the URL). */
+function extractUrl(stdout) {
+    const match = stdout.match(/https?:\/\/\S+/);
+    if (match)
+        return match[0];
+    return stdout.trim();
+}
+/**
+ * Raise a PR for a verified run. Probes `gh`, pushes the branch, then creates
+ * the PR — returning early with a reason on the first failure and NEVER
+ * touching the branch or worktree so the work is recoverable (A3).
+ */
+async function raisePullRequest(opts) {
+    const shell = opts.shell ?? defaultShell;
+    const { branchName, worktreePath, title, body } = opts;
+    // A3: probe the PR tooling before we change anything.
+    const version = shell('gh', ['--version'], worktreePath);
+    if (version.status !== 0) {
+        return {
+            ok: false,
+            reason: 'gh-missing',
+            message: 'GitHub CLI (gh) is not installed, so no pull request was raised. ' +
+                'Install gh (https://cli.github.com) and re-run, or open a PR manually — ' +
+                `the branch "${branchName}" and its worktree are left intact.`,
+        };
+    }
+    const auth = shell('gh', ['auth', 'status'], worktreePath);
+    if (auth.status !== 0) {
+        return {
+            ok: false,
+            reason: 'gh-unauthenticated',
+            message: 'GitHub CLI (gh) is not authenticated, so no pull request was raised. ' +
+                'Run "gh auth login" and re-run, or open a PR manually — the branch ' +
+                `"${branchName}" and its worktree are left intact.`,
+        };
+    }
+    const push = shell('git', ['push', '-u', 'origin', branchName], worktreePath);
+    if (push.status !== 0) {
+        return {
+            ok: false,
+            reason: 'push-failed',
+            message: `Pushing branch "${branchName}" failed, so no pull request was raised: ` +
+                `${push.stderr.trim() || 'unknown error'}. The branch and its worktree ` +
+                'are left intact for a manual push/PR.',
+        };
+    }
+    const create = shell('gh', ['pr', 'create', '--title', title, '--body', body, '--head', branchName], worktreePath);
+    if (create.status !== 0) {
+        return {
+            ok: false,
+            reason: 'create-failed',
+            message: `"gh pr create" failed, so no pull request was raised: ` +
+                `${create.stderr.trim() || 'unknown error'}. The branch "${branchName}" ` +
+                'was pushed and its worktree is intact — open the PR manually.',
+        };
+    }
+    return { ok: true, url: extractUrl(create.stdout) };
+}
+//# sourceMappingURL=pull-request.js.map

package/lib/dist/jira/pull-request.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pull-request.js","sourceRoot":"","sources":["../../src/jira/pull-request.ts"],"names":[],"mappings":"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"}

package/lib/dist/jira/spec-generator.d.ts

@@ -0,0 +1,34 @@
+/**
+ * JIRA issue → SpecShip spec markdown (REQ-JIRA-004).
+ *
+ * A "pick" turns a fetched issue into a well-formed, low-ceremony spec:
+ * the summary becomes the title, the description becomes an RFC-2119
+ * requirement body, and each subtask becomes an acceptance bullet. The
+ * generated markdown mirrors the `MarkdownSpecExtractor` contract exactly
+ * (frontmatter, `<!-- id: -->` markers, `## Acceptance` container, id-marked
+ * bullets) so it indexes with zero `spec_missing_id`/error results (A2).
+ *
+ * SECURITY: the issue summary / description / subtask summaries are UNTRUSTED
+ * content being embedded into a spec file. A description that contains a
+ * literal `<!-- id: REQ-EVIL-001 -->` marker or a `## Acceptance` / `# ` heading
+ * must NOT be able to inject spec structure that corrupts the generated spec or,
+ * on index, collides with another spec. `neutralizeLine` defuses those
+ * sequences so the injected markers index as inert prose. This module is pure —
+ * no I/O — and never handles or echoes any credential (REQ-JIRA-009).
+ */
+import type { JiraIssue } from './types';
+/**
+ * Derive a stable, collision-safe requirement id from the FULL issue key
+ * (unique within the connected JIRA). `PROJ-123` → `REQ-PROJ-123`. The key is
+ * upper-cased and sanitized to `[A-Z0-9-]` so it is safe both as an id marker
+ * and as a filename slug. Drives the `<!-- id: -->` marker AND idempotency.
+ */
+export declare function reqIdForIssue(key: string): string;
+/**
+ * Generate a full, well-formed spec document from a JIRA issue. The frontmatter
+ * records the source key (`jira_issue:` — the A1 link + the idempotency key);
+ * the H1 carries the requirement id marker; the `## Acceptance` container holds
+ * one id-marked bullet per subtask.
+ */
+export declare function generateSpecMarkdown(issue: JiraIssue): string;
+//# sourceMappingURL=spec-generator.d.ts.map

package/lib/dist/jira/spec-generator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spec-generator.d.ts","sourceRoot":"","sources":["../../src/jira/spec-generator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAUzC;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAOjD;AAyED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,SAAS,GAAG,MAAM,CAuB7D"}

package/lib/dist/jira/spec-generator.js

@@ -0,0 +1,138 @@
+"use strict";
+/**
+ * JIRA issue → SpecShip spec markdown (REQ-JIRA-004).
+ *
+ * A "pick" turns a fetched issue into a well-formed, low-ceremony spec:
+ * the summary becomes the title, the description becomes an RFC-2119
+ * requirement body, and each subtask becomes an acceptance bullet. The
+ * generated markdown mirrors the `MarkdownSpecExtractor` contract exactly
+ * (frontmatter, `<!-- id: -->` markers, `## Acceptance` container, id-marked
+ * bullets) so it indexes with zero `spec_missing_id`/error results (A2).
+ *
+ * SECURITY: the issue summary / description / subtask summaries are UNTRUSTED
+ * content being embedded into a spec file. A description that contains a
+ * literal `<!-- id: REQ-EVIL-001 -->` marker or a `## Acceptance` / `# ` heading
+ * must NOT be able to inject spec structure that corrupts the generated spec or,
+ * on index, collides with another spec. `neutralizeLine` defuses those
+ * sequences so the injected markers index as inert prose. This module is pure —
+ * no I/O — and never handles or echoes any credential (REQ-JIRA-009).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.reqIdForIssue = reqIdForIssue;
+exports.generateSpecMarkdown = generateSpecMarkdown;
+/**
+ * RFC-2119 keyword set. If the derived body already carries one of these, we
+ * keep it as-is; otherwise we prefix a MUST sentence so the requirement is
+ * always normative (A2 — the pipeline expects RFC-2119 keywords).
+ */
+const RFC2119 = /\b(MUST|MUST NOT|SHALL|SHALL NOT|SHOULD|SHOULD NOT|REQUIRED|MAY)\b/;
+/**
+ * Derive a stable, collision-safe requirement id from the FULL issue key
+ * (unique within the connected JIRA). `PROJ-123` → `REQ-PROJ-123`. The key is
+ * upper-cased and sanitized to `[A-Z0-9-]` so it is safe both as an id marker
+ * and as a filename slug. Drives the `<!-- id: -->` marker AND idempotency.
+ */
+function reqIdForIssue(key) {
+    const sanitized = key
+        .toUpperCase()
+        .replace(/[^A-Z0-9-]/g, '-')
+        .replace(/-+/g, '-')
+        .replace(/^-|-$/g, '');
+    return `REQ-${sanitized || 'JIRA'}`;
+}
+/**
+ * Neutralize a single line of UNTRUSTED issue text so it can't inject spec
+ * structure when embedded in the generated markdown:
+ *   - break HTML-comment markers (`<!-- id: … -->`) so they never match the
+ *     extractor's `ID_COMMENT`, which would otherwise strand or re-parent nodes;
+ *   - escape a leading heading run (`#`..`######`) so it never opens a new
+ *     id-less section (which raises `spec_missing_id`) or a second `## Acceptance`
+ *     container.
+ * The line stays human-readable — the injected markers render as literal text.
+ */
+function neutralizeLine(line) {
+    let out = line.replace(/<!--/g, '&lt;!--').replace(/-->/g, '--&gt;');
+    // Escape a leading heading marker: `## Acceptance` → `\## Acceptance`.
+    out = out.replace(/^(\s*)(#{1,6})(\s+)/, '$1\\$2$3');
+    return out;
+}
+/** Neutralize a multi-line block line-by-line, preserving paragraph breaks. */
+function neutralizeBlock(text) {
+    return text.split(/\r?\n/).map(neutralizeLine).join('\n').trim();
+}
+/**
+ * Collapse UNTRUSTED text to a single neutralized line — for the H1 title and
+ * acceptance bullets, which must stay on one line. Newlines are folded to spaces
+ * (so a multi-line summary can't spill into the next markdown construct) and the
+ * result is neutralized. Returns `fallback` when the text is empty.
+ */
+function neutralizeInline(text, fallback) {
+    const collapsed = text.replace(/\s+/g, ' ').trim();
+    const safe = neutralizeLine(collapsed).trim();
+    return safe || fallback;
+}
+/**
+ * Derive the requirement body from the issue. If the (neutralized) description
+ * already carries an RFC-2119 keyword we use it verbatim; otherwise we prefix a
+ * MUST sentence built from the summary so the body is always normative and never
+ * empty (A2).
+ */
+function deriveBody(issue) {
+    const desc = neutralizeBlock(issue.description?.trim() ?? '');
+    if (desc && RFC2119.test(desc))
+        return desc;
+    const summary = neutralizeInline(issue.summary ?? '', issue.key);
+    const must = `The implementation MUST satisfy JIRA issue ${issue.key}: ${summary}.`;
+    return desc ? `${must}\n\n${desc}` : must;
+}
+/**
+ * Derive acceptance bullets — one per subtask, or a single derived bullet when
+ * the issue has none (never zero — A2). Each bullet id is `${reqId}.A<n>` so the
+ * extractor parents it to the requirement by id suffix.
+ */
+function deriveAcceptance(issue) {
+    const reqId = reqIdForIssue(issue.key);
+    const subs = issue.subtasks ?? [];
+    if (subs.length > 0) {
+        return subs.map((st, i) => ({
+            id: `${reqId}.A${i + 1}`,
+            text: neutralizeInline(st.summary ?? '', st.key || `Subtask ${i + 1}`),
+        }));
+    }
+    return [
+        {
+            id: `${reqId}.A1`,
+            text: `The behaviour described by ${issue.key} is implemented and verified against the issue.`,
+        },
+    ];
+}
+/**
+ * Generate a full, well-formed spec document from a JIRA issue. The frontmatter
+ * records the source key (`jira_issue:` — the A1 link + the idempotency key);
+ * the H1 carries the requirement id marker; the `## Acceptance` container holds
+ * one id-marked bullet per subtask.
+ */
+function generateSpecMarkdown(issue) {
+    const reqId = reqIdForIssue(issue.key);
+    const title = neutralizeInline(issue.summary ?? '', issue.key);
+    const body = deriveBody(issue);
+    const acceptance = deriveAcceptance(issue);
+    const lines = [
+        '---',
+        'format: markdown',
+        `jira_issue: ${issue.key}`,
+        '---',
+        `<!-- id: ${reqId} -->`,
+        `# ${title}`,
+        '',
+        body,
+        '',
+        '## Acceptance',
+    ];
+    for (const bullet of acceptance) {
+        lines.push(`<!-- id: ${bullet.id} -->`);
+        lines.push(`- ${bullet.text}`);
+    }
+    return lines.join('\n') + '\n';
+}
+//# sourceMappingURL=spec-generator.js.map

package/lib/dist/jira/spec-generator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"spec-generator.js","sourceRoot":"","sources":["../../src/jira/spec-generator.ts"],"names":[],"mappings":"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"}

package/lib/dist/jira/spec-writer.d.ts

@@ -0,0 +1,36 @@
+/**
+ * JIRA issue → spec file on disk (REQ-JIRA-004).
+ *
+ * `writeSpecFromIssue` resolves the project's `specs/` directory, generates the
+ * spec markdown from the issue, and writes it idempotently (A3). Idempotency is
+ * keyed on the frontmatter `jira_issue:` value — parsed from a real frontmatter
+ * block, NOT grepped from the body (which could match the key in prose) — so a
+ * re-pick of the same issue overwrites the existing file even if it was renamed,
+ * and never leaves a duplicate. Pure filesystem side of the feature; it handles
+ * no credential (REQ-JIRA-009).
+ */
+import type { JiraIssue } from './types';
+export interface WriteSpecResult {
+    /** Absolute path of the written spec file. */
+    path: string;
+    /** True when a new file was created; false when an existing one was updated. */
+    created: boolean;
+}
+/**
+ * Find the spec file (if any) whose frontmatter records `issueKey`, scanning
+ * `<projectRoot>/specs/`. Returns the absolute path, or `null` when no spec for
+ * the key exists. Keyed on the parsed `jira_issue:` frontmatter value — never a
+ * body match — so it locates the exact file a pick wrote even if it was renamed.
+ * Shared by `writeSpecFromIssue` (idempotent overwrite) and `specship_jira_start`
+ * (does a spec for this key exist yet?).
+ */
+export declare function findSpecForIssueKey(issueKey: string, projectRoot: string): string | null;
+/**
+ * Generate and write a spec for `issue` under `<projectRoot>/specs/`, creating
+ * the directory if needed. If an existing spec already records this issue key in
+ * its frontmatter, that file is overwritten (keyed on the key, not the filename,
+ * so a renamed file still updates); otherwise a new `specs/jira-<slug>.md` is
+ * created.
+ */
+export declare function writeSpecFromIssue(issue: JiraIssue, projectRoot: string): WriteSpecResult;
+//# sourceMappingURL=spec-writer.d.ts.map