specrails-desktop 2.3.0 → 2.5.0

package/server/dist/db.js

@@ -6,6 +6,8 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.DEFAULT_ULTRACODE_PRE_PROMPT = void 0;
 exports.initDb = initDb;
 exports.createJob = createJob;
+exports.accumulateInteractiveTurn = accumulateInteractiveTurn;
+exports.finalizeInteractiveJob = finalizeInteractiveJob;
 exports.finishJob = finishJob;
 exports.appendEvent = appendEvent;
 exports.upsertPhase = upsertPhase;
@@ -559,6 +561,98 @@ const MIGRATIONS = [
       );
     `);
     },
+    // Migration 29: Jira integration (per-project). Each project syncs with its
+    // own Jira board, so every Jira table lives here in the per-project jobs.sqlite
+    // and is keyed by nothing but its own rows. See docs/jira-integration-plan.md.
+    //   - jira_connection: one row, the connection config (token stored encrypted).
+    //   - jira_links: spec↔issue map keyed on the IMMUTABLE Jira numeric id.
+    //   - jira_outbox: durable transactional write-back queue (status + comments).
+    (db) => {
+        db.exec(`
+      CREATE TABLE IF NOT EXISTS jira_connection (
+        project_id        TEXT PRIMARY KEY,
+        base_url          TEXT NOT NULL,
+        deployment        TEXT NOT NULL,
+        api_version       TEXT NOT NULL,
+        auth_scheme       TEXT NOT NULL,
+        account_email     TEXT,
+        jira_project_key  TEXT NOT NULL,
+        jira_project_id   TEXT NOT NULL,
+        encrypted_token   TEXT,
+        enabled           INTEGER NOT NULL DEFAULT 1,
+        status_map        TEXT,
+        high_water_ms     INTEGER,
+        created_at        TEXT NOT NULL DEFAULT (datetime('now')),
+        updated_at        TEXT NOT NULL DEFAULT (datetime('now'))
+      );
+
+      CREATE TABLE IF NOT EXISTS jira_links (
+        local_id          INTEGER PRIMARY KEY,
+        jira_issue_id     TEXT NOT NULL UNIQUE,
+        jira_key          TEXT,
+        jira_project_id   TEXT NOT NULL,
+        deployment        TEXT NOT NULL,
+        status_category   TEXT,
+        state             TEXT NOT NULL DEFAULT 'linked',
+        tombstoned        INTEGER NOT NULL DEFAULT 0,
+        created_at        TEXT NOT NULL DEFAULT (datetime('now')),
+        updated_at        TEXT NOT NULL DEFAULT (datetime('now'))
+      );
+      CREATE INDEX IF NOT EXISTS idx_jira_links_issue ON jira_links(jira_issue_id);
+
+      CREATE TABLE IF NOT EXISTS jira_outbox (
+        id                INTEGER PRIMARY KEY AUTOINCREMENT,
+        jira_issue_id     TEXT NOT NULL,
+        op_type           TEXT NOT NULL,
+        idempotency_key   TEXT NOT NULL UNIQUE,
+        payload           TEXT NOT NULL,
+        state             TEXT NOT NULL DEFAULT 'pending',
+        attempts          INTEGER NOT NULL DEFAULT 0,
+        next_attempt_at   TEXT,
+        last_error        TEXT,
+        dead_reason       TEXT,
+        created_at        TEXT NOT NULL DEFAULT (datetime('now')),
+        updated_at        TEXT NOT NULL DEFAULT (datetime('now'))
+      );
+      CREATE INDEX IF NOT EXISTS idx_jira_outbox_state ON jira_outbox(state);
+      CREATE INDEX IF NOT EXISTS idx_jira_outbox_issue ON jira_outbox(jira_issue_id);
+    `);
+    },
+    // Migration 30: Jira sprint custom-field id. The field that holds an issue's
+    // sprint(s) is a custom field whose id varies per instance; we discover it
+    // (schema com.pyxis.greenhopper.jira:gh-sprint) and cache it here. NULL =
+    // not yet checked, 'none' = checked and no sprint field exists, '<id>' = found.
+    (db) => {
+        try {
+            db.exec(`ALTER TABLE jira_connection ADD COLUMN sprint_field_id TEXT`);
+        }
+        catch {
+            // Column may already exist on a partially-migrated DB — no-op.
+        }
+    },
+    // Migration 31: Jira discard target status. The user-configured status name to
+    // which a discarded spec's issue is transitioned (instead of being deleted) in
+    // a Jira-synced project. NULL/empty = not configured (delete behaves normally).
+    (db) => {
+        try {
+            db.exec(`ALTER TABLE jira_connection ADD COLUMN discard_status TEXT`);
+        }
+        catch {
+            // Column may already exist on a partially-migrated DB — no-op.
+        }
+    },
+    // Migration 32: jobs.interactive — 1 when the job is an interactive persistent
+    // ultracode session (the user sends multiple prompts across turns; the job
+    // stays 'running' until an explicit finalize, at which point every turn's real
+    // tokens/cost/num_turns are already summed into the row and status flips to
+    // 'completed'); 0 (default) for standard autonomous jobs. Additive + idempotent
+    // (guarded by PRAGMA table_info, mirroring migrations 18–26).
+    (db) => {
+        const cols = db.prepare(`PRAGMA table_info(jobs)`).all().map((r) => r.name);
+        if (!cols.includes('interactive')) {
+            db.exec(`ALTER TABLE jobs ADD COLUMN interactive INTEGER NOT NULL DEFAULT 0`);
+        }
+    },
 ];
 function applyMigrations(db) {
     // Ensure the migrations table exists (migration 1 creates it, but we need
@@ -620,8 +714,39 @@ function initDb(dbPath) {
 function createJob(db, job) {
     // INSERT OR IGNORE handles the case where the job row already exists (restored from DB
     // after server restart). The UPDATE that follows always sets status and started_at.
-    db.prepare('INSERT OR IGNORE INTO jobs (id, command, started_at, status, priority, depends_on_job_id, pipeline_id) VALUES (?, ?, ?, ?, ?, ?, ?)').run(job.id, job.command, job.started_at, 'running', job.priority ?? 'normal', job.depends_on_job_id ?? null, job.pipeline_id ?? null);
-    db.prepare('UPDATE jobs SET status = ?, started_at = ? WHERE id = ?').run('running', job.started_at, job.id);
+    db.prepare('INSERT OR IGNORE INTO jobs (id, command, started_at, status, priority, depends_on_job_id, pipeline_id, interactive) VALUES (?, ?, ?, ?, ?, ?, ?, ?)').run(job.id, job.command, job.started_at, 'running', job.priority ?? 'normal', job.depends_on_job_id ?? null, job.pipeline_id ?? null, job.interactive ? 1 : 0);
+    db.prepare('UPDATE jobs SET status = ?, started_at = ?, interactive = ? WHERE id = ?').run('running', job.started_at, job.interactive ? 1 : 0, job.id);
+}
+/**
+ * Add one completed interactive turn's REAL usage into the job row. Token/cost/
+ * turn columns accumulate (COALESCE so the first turn starts from a clean base);
+ * model + session_id are stamped from the first turn that reports them. The job
+ * stays 'running' — only finalizeInteractiveJob flips the terminal status. This
+ * keeps the live Job Detail totals honest (sum of completed turns, never an
+ * estimate) between turns.
+ */
+function accumulateInteractiveTurn(db, jobId, turn) {
+    db.prepare(`
+    UPDATE jobs SET
+      tokens_in           = COALESCE(tokens_in, 0) + ?,
+      tokens_out          = COALESCE(tokens_out, 0) + ?,
+      tokens_cache_read   = COALESCE(tokens_cache_read, 0) + ?,
+      tokens_cache_create = COALESCE(tokens_cache_create, 0) + ?,
+      total_cost_usd      = COALESCE(total_cost_usd, 0) + ?,
+      num_turns           = COALESCE(num_turns, 0) + ?,
+      total_cost_usd_estimated = 0,
+      model               = COALESCE(model, ?),
+      session_id          = COALESCE(?, session_id)
+    WHERE id = ?
+  `).run(turn.tokens_in, turn.tokens_out, turn.tokens_cache_read, turn.tokens_cache_create, turn.total_cost_usd, turn.num_turns, turn.model ?? null, turn.session_id ?? null, jobId);
+}
+/**
+ * Flip an interactive job to its terminal status (completed on finalize, failed
+ * on crash) and stamp finished_at. Token/cost/turn columns are left untouched —
+ * they were already accumulated turn-by-turn via accumulateInteractiveTurn.
+ */
+function finalizeInteractiveJob(db, jobId, status) {
+    db.prepare('UPDATE jobs SET status = ?, finished_at = ? WHERE id = ?').run(status, new Date().toISOString(), jobId);
 }
 function finishJob(db, jobId, result) {
     db.prepare(`

package/server/dist/feature-flags.js

@@ -2,6 +2,8 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.isCodeExplorerEnabled = isCodeExplorerEnabled;
 exports.isBrowserCaptureEnabled = isBrowserCaptureEnabled;
+exports.isJiraEnabled = isJiraEnabled;
+exports.isInteractiveJobsEnabled = isInteractiveJobsEnabled;
 function isCodeExplorerEnabled() {
     return process.env.SPECRAILS_CODE_EXPLORER !== 'false';
 }
@@ -15,3 +17,27 @@ function isCodeExplorerEnabled() {
 function isBrowserCaptureEnabled() {
     return process.env.SPECRAILS_BROWSER_CAPTURE !== 'false';
 }
+/**
+ * Jira integration ("spec = Jira issue", per-project hot-swap local↔Jira).
+ * Server-side default ON; set SPECRAILS_JIRA_SECTION="false" to 404 the routes
+ * and skip all sync (emergency rollback). The feature is inert until a project
+ * actually configures a Jira connection, so default-on is safe. The client gates
+ * separately on VITE_FEATURE_JIRA.
+ */
+function isJiraEnabled() {
+    return process.env.SPECRAILS_JIRA_SECTION !== 'false';
+}
+/**
+ * Interactive ultracode jobs: when launched with the rail's "Interactive"
+ * toggle, an ultracode (Claude-only) job becomes a persistent chat session —
+ * the user sends multiple prompts across turns, the job stays resident until an
+ * explicit "Finalize Job" action, and every turn's real token spend is summed
+ * into the single job row. Server-side default ON; set
+ * SPECRAILS_INTERACTIVE_JOBS="false" to reject the toggle + the per-job
+ * message/finalize routes (emergency rollback). Inert unless a launch actually
+ * sets interactive=true, so default-on is safe. The client gates separately on
+ * VITE_FEATURE_INTERACTIVE_JOBS.
+ */
+function isInteractiveJobsEnabled() {
+    return process.env.SPECRAILS_INTERACTIVE_JOBS !== 'false';
+}

package/server/dist/interactive-job-session.js

@@ -0,0 +1,363 @@
+"use strict";
+// Interactive ultracode job sessions (resident persistent-stdin transport).
+//
+// A standard ultracode job spawns `claude -p <prompt>` once and settles when the
+// child closes. An INTERACTIVE ultracode job instead keeps ONE `claude -p
+// --input-format stream-json` child resident across many user turns (the same
+// transport ExploreStdinSessions uses for Explore chat): each user prompt is a
+// newline-delimited stream-json message written to stdin, the agent works, and
+// the turn ends on a `result` event WITHOUT killing the child. The session stays
+// alive until the user finalizes (SIGTERM) — at which point QueueManager flips
+// the job to a terminal status. Every turn's REAL token usage is summed into the
+// job row as it completes, so the live Job Detail totals are honest (never an
+// estimate) and the finalized job carries the full conversation's spend.
+//
+// This module owns the transport + per-turn streaming/persistence/accounting.
+// QueueManager owns spawn-arg construction and the terminal settle (slot release,
+// rail/ticket completion, ai_invocations) via the onSettle callback.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InteractiveJobSession = void 0;
+const node_readline_1 = require("node:readline");
+const cli_prompt_1 = require("./util/cli-prompt");
+const explore_stdin_session_1 = require("./explore-stdin-session");
+const result_event_1 = require("./result-event");
+const db_1 = require("./db");
+const stream_display_1 = require("./util/stream-display");
+function zeroUsage() {
+    return {
+        tokens_in: 0,
+        tokens_out: 0,
+        tokens_cache_read: 0,
+        tokens_cache_create: 0,
+        total_cost_usd: 0,
+        num_turns: 0,
+    };
+}
+/** SIGTERM → SIGKILL escalation window on finalize (ms). */
+const FINALIZE_KILL_GRACE_MS = 2000;
+class InteractiveJobSession {
+    _jobId;
+    _projectId;
+    _db;
+    _adapter;
+    _broadcast;
+    _onSettle;
+    _spawn;
+    _child = null;
+    _stdoutReader = null;
+    _stderrReader = null;
+    _eventSeq = 0;
+    _streaming = false;
+    /** True between writing a turn to stdin and receiving its `result` event.
+     *  Guards _onTurnResult against double-counting a duplicate `result` frame. */
+    _awaitingResult = false;
+    _pending = [];
+    _turnEvents = [];
+    _accum = zeroUsage();
+    _model = null;
+    _sessionId = null;
+    _finalizing = false;
+    _settled = false;
+    _disposed = false;
+    _killTimer = null;
+    constructor(deps) {
+        this._jobId = deps.jobId;
+        this._projectId = deps.projectId;
+        this._db = deps.db;
+        this._adapter = deps.adapter;
+        this._broadcast = deps.broadcast;
+        this._onSettle = deps.onSettle;
+        this._spawn = deps.spawn ?? cli_prompt_1.spawnAiCli;
+    }
+    /** Spawn the resident child and run the first turn (the ultracode prompt). */
+    start(spec, firstPrompt) {
+        const child = this._spawn(spec.binary, spec.args, {
+            env: spec.env ?? process.env,
+            // stdin MUST be piped — it is the per-turn transport.
+            stdio: ['pipe', 'pipe', 'pipe'],
+            cwd: spec.cwd,
+        });
+        this._child = child;
+        // Absorb spawn 'error' (e.g. ENOENT) so it does not crash the process; the
+        // 'close' that follows settles the job as crashed through _handleClose.
+        child.on('error', (err) => {
+            console.error(`[interactive-job] spawn failed for ${this._jobId}: ${err.message}`);
+        });
+        if (child.stdout) {
+            this._stdoutReader = (0, node_readline_1.createInterface)({ input: child.stdout, crlfDelay: Infinity });
+            this._stdoutReader.on('line', (line) => this._handleStdoutLine(line));
+        }
+        if (child.stderr) {
+            this._stderrReader = (0, node_readline_1.createInterface)({ input: child.stderr, crlfDelay: Infinity });
+            this._stderrReader.on('line', (line) => this._handleStderrLine(line));
+        }
+        child.on('close', (code) => this._handleClose(code));
+        this.send(firstPrompt);
+    }
+    /** Accept a user prompt. Echoed immediately to the in-job chat; written to the
+     *  child now if idle, else queued and fed when the active turn's `result`
+     *  fires. Returns false if the session is gone. */
+    send(text) {
+        if (this._disposed || this._finalizing || !this._child)
+            return false;
+        const queued = this._streaming;
+        // Surface the user turn in the transcript via the existing `log` channel so
+        // it both renders live (the client's 'log' handler) and survives a reload
+        // (persisted as a log event, picked up by GET /jobs/:id). The 🧑 prefix marks
+        // it as the user's prompt amid the agent's streamed work.
+        const line = `🧑 ${text}`;
+        this._persistLog('stdout', line);
+        this._emitLog('stdout', line);
+        // Control signal for the in-job chat UI (streaming-state / queued hint).
+        this._broadcast({
+            type: 'job.turn_user',
+            projectId: this._projectId,
+            jobId: this._jobId,
+            text,
+            queued,
+            timestamp: new Date().toISOString(),
+        });
+        if (queued) {
+            this._pending.push(text);
+        }
+        else {
+            this._writeTurn(text);
+        }
+        return true;
+    }
+    isStreaming() {
+        return this._streaming;
+    }
+    getTotals() {
+        return { ...this._accum };
+    }
+    /** User-initiated end: SIGTERM the child (SIGKILL after a grace window). The
+     *  subsequent 'close' settles the job as 'finalized'. Idempotent. */
+    finalize() {
+        if (this._finalizing || this._settled)
+            return;
+        this._finalizing = true;
+        const child = this._child;
+        if (!child || child.killed || !child.pid) {
+            this._settle('finalized');
+            return;
+        }
+        try {
+            child.kill('SIGTERM');
+        }
+        catch { /* already gone */ }
+        this._killTimer = setTimeout(() => {
+            try {
+                if (this._child && !this._child.killed)
+                    this._child.kill('SIGKILL');
+            }
+            catch { /* gone */ }
+        }, FINALIZE_KILL_GRACE_MS);
+    }
+    /** Teardown without settling (project removal / shutdown). */
+    dispose() {
+        if (this._disposed)
+            return;
+        this._disposed = true;
+        this._clearKillTimer();
+        this._closeReaders();
+        try {
+            if (this._child && !this._child.killed)
+                this._child.kill('SIGTERM');
+        }
+        catch { /* gone */ }
+        this._child = null;
+    }
+    // ─── internals ─────────────────────────────────────────────────────────────
+    _writeTurn(text) {
+        this._streaming = true;
+        this._awaitingResult = true;
+        this._turnEvents = [];
+        const child = this._child;
+        if (!child || !child.stdin || child.stdin.destroyed)
+            return;
+        try {
+            child.stdin.write((0, explore_stdin_session_1.frameStreamJsonUserMessage)(text));
+        }
+        catch (err) {
+            console.error('[interactive-job] stdin write failed:', err);
+        }
+    }
+    _handleStdoutLine(line) {
+        let parsed = null;
+        try {
+            parsed = JSON.parse(line);
+        }
+        catch { /* plain text */ }
+        const adapterEv = this._adapter.parseStreamLine(line);
+        if (adapterEv)
+            this._turnEvents.push(adapterEv);
+        if (parsed) {
+            const eventType = parsed.type ?? 'unknown';
+            this._persistEvent(eventType, line);
+            this._broadcast({
+                type: 'event',
+                jobId: this._jobId,
+                event_type: eventType,
+                source: 'stdout',
+                payload: line,
+                timestamp: new Date().toISOString(),
+                seq: this._eventSeq - 1,
+            });
+            if (eventType === 'result') {
+                this._onTurnResult(parsed);
+            }
+            const displayText = (0, stream_display_1.extractDisplayText)(parsed);
+            if (displayText !== null) {
+                this._persistLog('stdout', displayText);
+                this._emitLog('stdout', displayText);
+            }
+        }
+        else {
+            this._persistLog('stdout', line);
+            if (adapterEv?.kind === 'text-delta') {
+                this._emitLog('stdout', adapterEv.text);
+            }
+            else {
+                this._emitLog('stdout', line);
+            }
+        }
+    }
+    _handleStderrLine(line) {
+        this._persistLog('stderr', line);
+        this._emitLog('stderr', line);
+    }
+    _onTurnResult(_parsed) {
+        // Guard against a duplicate `result` frame for the same turn — without it a
+        // second result would double-count this turn's tokens into _accum + the row.
+        if (!this._awaitingResult)
+            return;
+        this._awaitingResult = false;
+        this._streaming = false;
+        const { result: normalised } = (0, result_event_1.finaliseInvocationResult)(this._adapter, this._turnEvents, {});
+        this._accum.tokens_in += normalised.tokens_in ?? 0;
+        this._accum.tokens_out += normalised.tokens_out ?? 0;
+        this._accum.tokens_cache_read += normalised.tokens_cache_read ?? 0;
+        this._accum.tokens_cache_create += normalised.tokens_cache_create ?? 0;
+        this._accum.total_cost_usd += normalised.total_cost_usd ?? 0;
+        this._accum.num_turns += normalised.num_turns ?? 1;
+        if (!this._model && normalised.model)
+            this._model = normalised.model;
+        if (normalised.session_id)
+            this._sessionId = normalised.session_id;
+        if (this._db) {
+            try {
+                (0, db_1.accumulateInteractiveTurn)(this._db, this._jobId, {
+                    tokens_in: normalised.tokens_in ?? 0,
+                    tokens_out: normalised.tokens_out ?? 0,
+                    tokens_cache_read: normalised.tokens_cache_read ?? 0,
+                    tokens_cache_create: normalised.tokens_cache_create ?? 0,
+                    total_cost_usd: normalised.total_cost_usd ?? 0,
+                    num_turns: normalised.num_turns ?? 1,
+                    model: normalised.model,
+                    session_id: normalised.session_id,
+                });
+            }
+            catch (err) {
+                console.error('[interactive-job] accumulate turn failed:', err);
+            }
+        }
+        this._broadcast({
+            type: 'job.turn_done',
+            projectId: this._projectId,
+            jobId: this._jobId,
+            totals: { ...this._accum },
+            timestamp: new Date().toISOString(),
+        });
+        // Feed the next queued prompt (if any) now that the turn is idle.
+        if (!this._finalizing && this._pending.length > 0) {
+            const next = this._pending.shift();
+            this._writeTurn(next);
+        }
+    }
+    _persistEvent(eventType, payload) {
+        if (!this._db)
+            return;
+        try {
+            (0, db_1.appendEvent)(this._db, this._jobId, this._eventSeq++, {
+                event_type: eventType,
+                source: 'stdout',
+                payload,
+            });
+        }
+        catch (err) {
+            console.error('[interactive-job] persist event failed:', err);
+        }
+    }
+    _persistLog(source, line) {
+        if (!this._db)
+            return;
+        try {
+            (0, db_1.appendEvent)(this._db, this._jobId, this._eventSeq++, {
+                event_type: 'log',
+                source,
+                payload: JSON.stringify({ line }),
+            });
+        }
+        catch (err) {
+            console.error('[interactive-job] persist log failed:', err);
+        }
+    }
+    _emitLog(source, line) {
+        this._broadcast({
+            type: 'log',
+            source,
+            line,
+            timestamp: new Date().toISOString(),
+            processId: this._jobId,
+        });
+    }
+    _handleClose(_code) {
+        if (this._disposed || this._settled)
+            return;
+        this._settle(this._finalizing ? 'finalized' : 'crashed');
+    }
+    _settle(reason) {
+        if (this._settled)
+            return;
+        this._settled = true;
+        this._streaming = false;
+        this._awaitingResult = false;
+        this._clearKillTimer();
+        this._closeReaders();
+        // The child is gone — any prompts still queued (turn died without a `result`,
+        // or the user finalized mid-turn) can never run. Surface them in the
+        // transcript instead of dropping them silently.
+        if (this._pending.length > 0) {
+            const note = `⚠️ ${this._pending.length} queued prompt(s) were not sent — the session ended.`;
+            this._persistLog('stderr', note);
+            this._emitLog('stderr', note);
+            this._pending = [];
+        }
+        this._onSettle({
+            reason,
+            totals: { ...this._accum },
+            model: this._model,
+            sessionId: this._sessionId,
+        });
+    }
+    _clearKillTimer() {
+        if (this._killTimer !== null) {
+            clearTimeout(this._killTimer);
+            this._killTimer = null;
+        }
+    }
+    _closeReaders() {
+        try {
+            this._stdoutReader?.close();
+        }
+        catch { /* best-effort */ }
+        try {
+            this._stderrReader?.close();
+        }
+        catch { /* best-effort */ }
+        this._stdoutReader = null;
+        this._stderrReader = null;
+    }
+}
+exports.InteractiveJobSession = InteractiveJobSession;

package/server/dist/jira/jira-adf.js

@@ -0,0 +1,113 @@
+"use strict";
+// Atlassian Document Format (ADF) helpers.
+//
+// Jira Cloud (REST v3) requires comment/description bodies in ADF JSON. Jira
+// Server/Data Center (REST v2) expects a plain wiki-markup string. We keep a
+// single internal "text" model and render it to either format at the client
+// boundary (see jira-client.ts `bodyForDeployment`).
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SPECRAILS_COMMENT_PROP_KEY = void 0;
+exports.textToAdf = textToAdf;
+exports.bodyForDeployment = bodyForDeployment;
+exports.commentMarker = commentMarker;
+exports.discardCommentMarker = discardCommentMarker;
+exports.bodyContainsMarker = bodyContainsMarker;
+exports.commentHasMarker = commentHasMarker;
+exports.adfToText = adfToText;
+/** Build a minimal ADF document from plain text (newlines → paragraphs). */
+function textToAdf(text) {
+    const paragraphs = text.split('\n');
+    return {
+        type: 'doc',
+        version: 1,
+        content: paragraphs.map((line) => line.length === 0
+            ? { type: 'paragraph' }
+            : { type: 'paragraph', content: [{ type: 'text', text: line }] }),
+    };
+}
+/** Render a body for the target deployment: ADF for Cloud v3, plain for DC v2. */
+function bodyForDeployment(text, deployment) {
+    return deployment === 'cloud' ? textToAdf(text) : text;
+}
+/**
+ * Jira comment-property key under which we store the idempotency marker. Comment
+ * properties are metadata that NEVER render in the comment body, so the marker
+ * stays invisible to users while still letting us dedup on retry. Supported on
+ * both Cloud (v3) and Data Center (v2).
+ */
+exports.SPECRAILS_COMMENT_PROP_KEY = 'sh.specrails.marker';
+/**
+ * Deterministic idempotency marker. Jira has no native comment idempotency, so
+ * before re-posting on retry we GET the issue comments and skip if one already
+ * carries this marker (now via an invisible comment property — see
+ * SPECRAILS_COMMENT_PROP_KEY — with a legacy body-scan fallback).
+ */
+function commentMarker(jobId, ticketId) {
+    return `[specrails:job=${jobId}:ticket=${ticketId}]`;
+}
+/**
+ * Idempotency marker for a user-initiated "discard / move-to" comment. The
+ * `nonce` (captured at enqueue) makes each discard distinct so a later re-discard
+ * of the same spec posts a fresh comment instead of being deduped away.
+ */
+function discardCommentMarker(ticketId, nonce) {
+    return `[specrails:discard=${nonce}:ticket=${ticketId}]`;
+}
+/** True when an ADF doc or wiki string already contains the given marker. */
+function bodyContainsMarker(body, marker) {
+    if (typeof body === 'string')
+        return body.includes(marker);
+    try {
+        return JSON.stringify(body).includes(marker);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * True when a fetched comment already carries the marker — preferring the
+ * invisible comment property, with a fallback to a legacy body-embedded marker
+ * (comments posted before the property move). `comment.properties` comes from
+ * `GET …/comment?expand=properties`.
+ */
+function commentHasMarker(comment, marker) {
+    const prop = comment.properties?.find((p) => p.key === exports.SPECRAILS_COMMENT_PROP_KEY);
+    if (prop) {
+        try {
+            if (JSON.stringify(prop.value ?? '').includes(marker))
+                return true;
+        }
+        catch {
+            /* fall through to body scan */
+        }
+    }
+    return bodyContainsMarker(comment.body, marker);
+}
+/**
+ * Flatten an ADF document (or plain string) back to text — used to read inbound
+ * Jira descriptions/comments into the local cache.
+ */
+function adfToText(body) {
+    if (body == null)
+        return '';
+    if (typeof body === 'string')
+        return body;
+    const out = [];
+    const walk = (node) => {
+        if (!node || typeof node !== 'object')
+            return;
+        if (node.type === 'text' && typeof node.text === 'string')
+            out.push(node.text);
+        if (node.type === 'hardBreak')
+            out.push('\n');
+        if (Array.isArray(node.content)) {
+            for (const child of node.content)
+                walk(child);
+            // paragraph / block separators
+            if (node.type === 'paragraph' || node.type === 'heading')
+                out.push('\n');
+        }
+    };
+    walk(body);
+    return out.join('').replace(/\n{3,}/g, '\n\n').trim();
+}