specrails-desktop 2.2.1 → 2.4.0

package/server/dist/code-explorer-router.js

@@ -539,6 +539,84 @@ function createCodeExplorerRouter(deps) {
             absolutePath: abs,
         });
     });
+    // In-app editing (v1): overwrite an existing text file with new content.
+    // Same guards as the read path — traversal, deny-list, gitignore, size, and
+    // binary refusal — so the editor can never write outside the tree, clobber a
+    // secret/lockfile, or corrupt a binary. Creating new files / renames is out of
+    // scope here. After a write the existing hash-gated `summaryStale` flag makes
+    // the next GET /file surface the summary as stale (regenerate via the existing
+    // POST /file/regenerate-summary).
+    router.put('/file', (req, res) => {
+        const body = (req.body ?? {});
+        const relRaw = typeof body.path === 'string' ? body.path : undefined;
+        const content = typeof body.content === 'string' ? body.content : undefined;
+        if (!relRaw || content === undefined) {
+            res.status(400).json({ error: 'path and content are required' });
+            return;
+        }
+        const guard = resolveSafePath(deps.projectPath, relRaw);
+        if (!guard) {
+            res.status(400).json({ error: 'path traversal not allowed' });
+            return;
+        }
+        if (isDeniedRelPath(relRaw)) {
+            res.status(403).json({ error: 'path is excluded by the code-explorer deny-list' });
+            return;
+        }
+        const rel = normalizeRel(relRaw);
+        if (isGitIgnored(deps.projectPath, rel)) {
+            res.status(403).json({ error: 'path is gitignored' });
+            return;
+        }
+        if (Buffer.byteLength(content, 'utf8') > MAX_FILE_BYTES) {
+            res.status(413).json({ error: 'file too large' });
+            return;
+        }
+        if (/[\x00-\x08\x0e-\x1f]/.test(content)) {
+            res.status(415).json({ error: 'binary content not allowed' });
+            return;
+        }
+        const abs = guard;
+        let stat;
+        try {
+            stat = fs_1.default.statSync(abs);
+        }
+        catch {
+            res.status(404).json({ error: 'file not found (in-app editing only overwrites existing files)' });
+            return;
+        }
+        if (!stat.isFile()) {
+            res.status(400).json({ error: 'path is not a regular file' });
+            return;
+        }
+        // Refuse to overwrite a binary file as text (would corrupt it).
+        try {
+            const fd = fs_1.default.openSync(abs, 'r');
+            try {
+                const head = Buffer.alloc(Math.min(BINARY_PROBE_BYTES, stat.size));
+                fs_1.default.readSync(fd, head, 0, head.length, 0);
+                if (head.includes(0)) {
+                    res.status(415).json({ error: 'cannot edit a binary file' });
+                    return;
+                }
+            }
+            finally {
+                fs_1.default.closeSync(fd);
+            }
+        }
+        catch {
+            res.status(500).json({ error: 'failed to read file' });
+            return;
+        }
+        try {
+            fs_1.default.writeFileSync(abs, content, 'utf8');
+        }
+        catch {
+            res.status(500).json({ error: 'failed to write file' });
+            return;
+        }
+        res.json({ ok: true, bytes: Buffer.byteLength(content, 'utf8'), path: rel });
+    });
     router.get('/summary', async (req, res) => {
         const relRaw = req.query.path;
         if (!relRaw || typeof relRaw !== 'string') {

package/server/dist/command-resolver.js

@@ -53,6 +53,16 @@ The user's idea follows below. Begin the Explore Spec conversation.
 
 ${commandArgs}`.trim();
 }
+/**
+ * A `:`-separated command segment is safe iff it is a plain identifier: no path
+ * separators, no `.`/`..`, no NUL. Anything else could escape the
+ * commands/skills directory once joined into the lookup path.
+ */
+function isSafeSegment(seg) {
+    if (seg.length === 0 || seg === '.' || seg === '..')
+        return false;
+    return !/[/\\\0]/.test(seg);
+}
 /**
  * Try to find a command/skill .md file for the given command path parts
  * within the given base directory. Returns the resolved path or null.
@@ -87,6 +97,13 @@ function resolveCommand(command, cwd) {
     const builtIn = builtInCommand(commandPath, commandArgs);
     if (builtIn)
         return builtIn;
+    // Path-traversal guard: each segment is joined verbatim into
+    // `<baseDir>/.claude/commands/<...parts>.md`, so a segment like `..`, one
+    // containing a path separator, or an absolute fragment would escape the
+    // commands/skills directory and read an arbitrary file. Reject and leave the
+    // command unresolved (defense-in-depth even though the input is user-typed).
+    if (!parts.every(isSafeSegment))
+        return command;
     // 1. Check the project directory
     let resolvedPath = findCommandFile(cwd, parts);
     // 2. Fallback: check the app's own directory

package/server/dist/contract-refine-runner.js

@@ -19,6 +19,8 @@ exports.runContractRefineForQuick = runContractRefineForQuick;
 const node_crypto_1 = require("node:crypto");
 const node_readline_1 = require("node:readline");
 const cli_prompt_1 = require("./util/cli-prompt");
+const spawn_lifecycle_1 = require("./spawn-lifecycle");
+const registry_1 = require("./providers/registry");
 const explore_contract_refine_1 = require("./explore-contract-refine");
 const db_1 = require("./db");
 const explore_cwd_manager_1 = require("./explore-cwd-manager");
@@ -242,15 +244,45 @@ async function runContractRefine(deps, conversationId, ticketId) {
         projectName: deps.projectName,
     }, conversation);
     const startedAt = now().toISOString();
-    let child;
-    try {
-        child = spawn('claude', args, {
-            env: process.env,
-            stdio: ['ignore', 'pipe', 'pipe'],
-            cwd,
-        });
-    }
-    catch (err) {
+    // Spawn/stream/timeout/settlement is owned by the shared spawn-lifecycle; the
+    // contract-refine-specific raw parse (fullText from assistant text blocks,
+    // the raw result event) and ALL finalize/record/broadcast logic stay here,
+    // byte-for-byte, so behaviour is unchanged (it still records via the legacy
+    // recordSafely path).
+    let fullText = '';
+    let resultEvent = null;
+    const run = await (0, spawn_lifecycle_1.runAiCliInvocation)({
+        adapter: (0, registry_1.getAdapter)('claude'),
+        binary: 'claude',
+        argv: args,
+        cwd,
+        env: process.env,
+        spawn,
+        timeoutMs,
+        onStdoutLine: (line) => {
+            let parsed = null;
+            try {
+                parsed = JSON.parse(line);
+            }
+            catch {
+                return;
+            }
+            if (!parsed)
+                return;
+            const type = parsed.type;
+            if (type === 'result') {
+                resultEvent = parsed;
+            }
+            else if (type === 'assistant') {
+                const message = parsed.message;
+                for (const b of (message?.content ?? [])) {
+                    if (b.type === 'text' && typeof b.text === 'string')
+                        fullText += b.text;
+                }
+            }
+        },
+    });
+    if (run.spawnFailed) {
         recordSafely(deps, conversationId, ticketId, conversation.model, startedAt, now().toISOString(), 'failed', null);
         deps.broadcast({
             type: 'explore.contract_refine_failed',
@@ -261,7 +293,7 @@ async function runContractRefine(deps, conversationId, ticketId) {
         });
         return { ok: false, reason: 'crashed', ticketId, conversationId };
     }
-    const result = await readRefineChildOutput(child, timeoutMs);
+    const result = { fullText, resultEvent, code: run.code, timedOut: run.timedOut };
     const finishedAt = now().toISOString();
     console.log(`[contract-refine-runner] spawn done code=${result.code} timedOut=${result.timedOut} hasResult=${!!result.resultEvent} textBytes=${result.fullText.length}`);
     if (result.timedOut) {

package/server/dist/db.js

@@ -559,6 +559,86 @@ 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.
+        }
+    },
 ];
 function applyMigrations(db) {
     // Ensure the migrations table exists (migration 1 creates it, but we need
@@ -600,6 +680,12 @@ function initDb(dbPath) {
     const db = new better_sqlite3_1.default(dbPath);
     db.pragma('journal_mode = WAL');
     db.pragma('foreign_keys = ON');
+    // Under load, QueueManager / ChatManager / FileSummaryManager write the same
+    // per-project DB concurrently with /analytics reads. Wait up to 5s on a lock
+    // instead of throwing SQLITE_BUSY, and cap the WAL so a long checkpoint can't
+    // grow it without bound.
+    db.pragma('busy_timeout = 5000');
+    db.pragma('journal_size_limit = 10000000'); // ~10 MB
     applyMigrations(db);
     // H-13: restrict the db + its WAL sidecars to 0600 (jobs.sqlite holds chat
     // transcripts and verbatim terminal command history). After migrations the

package/server/dist/desktop-db.js

@@ -315,6 +315,9 @@ function initDesktopDb(dbPath = getDesktopDbPath()) {
     const db = new better_sqlite3_1.default(dbPath);
     db.pragma('journal_mode = WAL');
     db.pragma('foreign_keys = ON');
+    // Wait up to 5s on a lock instead of throwing SQLITE_BUSY, and cap the WAL.
+    db.pragma('busy_timeout = 5000');
+    db.pragma('journal_size_limit = 10000000'); // ~10 MB
     applyDesktopMigrations(db);
     // H-13: desktop.sqlite stores webhook HMAC secrets in plaintext — restrict it
     // (and its WAL sidecars) to owner read/write.

package/server/dist/explore-stdin-session.js

@@ -0,0 +1,129 @@
+"use strict";
+// Persistent-stdin Explore transport (big bet #3).
+//
+// The default Explore turn spawns a fresh `claude` child per message (turns 2+
+// pay `--resume` session-rehydration latency). This module keeps ONE child
+// alive per conversation using claude's `--input-format stream-json` multi-turn
+// transport: each user turn is written as a newline-delimited JSON message to
+// the child's stdin, and the same long-lived child streams the response. The
+// child stays resident between turns, so turns 2+ skip spawn + rehydration.
+//
+// Transport only — it owns spawning, the persistent stdout/stderr fan-out, and
+// stdin framing. ChatManager drives per-turn rendering, persistence, and
+// lifecycle through the handler hooks. Default OFF behind a flag; claude-only
+// (gated by capabilities.persistentStdin); full fallback to the legacy
+// spawn-per-turn path means zero behaviour change when disabled.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ExploreStdinSessions = void 0;
+exports.isExplorePersistentStdinEnabled = isExplorePersistentStdinEnabled;
+exports.frameStreamJsonUserMessage = frameStreamJsonUserMessage;
+const node_readline_1 = require("node:readline");
+const cli_prompt_1 = require("./util/cli-prompt");
+/**
+ * Persistent-stdin Explore is opt-in. Default OFF — set
+ * `SPECRAILS_EXPLORE_PERSISTENT_STDIN=1` to enable. Any other value (or unset)
+ * keeps the legacy spawn-per-turn path, so this is also the escape hatch.
+ */
+function isExplorePersistentStdinEnabled() {
+    return process.env.SPECRAILS_EXPLORE_PERSISTENT_STDIN === '1';
+}
+/**
+ * Frame one user turn as a stream-json input line for claude's
+ * `--input-format stream-json` transport. Newline-terminated so the child reads
+ * exactly one message per turn. Content is sent as a plain string (claude
+ * accepts string content for user messages).
+ */
+function frameStreamJsonUserMessage(text) {
+    return JSON.stringify({ type: 'user', message: { role: 'user', content: text } }) + '\n';
+}
+/**
+ * Owns the long-lived claude children for persistent-stdin Explore. Keyed by
+ * conversation id. One child per conversation; a single stdout reader fans each
+ * line out to the conversation's currently-installed turn handler.
+ */
+class ExploreStdinSessions {
+    _sessions = new Map();
+    has(id) {
+        return this._sessions.has(id);
+    }
+    size() {
+        return this._sessions.size;
+    }
+    /**
+     * Return the live child for a conversation, spawning one in persistent mode
+     * if none exists. `isNew` is true only when a child was just spawned (the
+     * caller writes the first turn either way).
+     */
+    getOrSpawn(id, spec) {
+        const existing = this._sessions.get(id);
+        if (existing && existing.child.pid && !existing.child.killed) {
+            return { child: existing.child, isNew: false };
+        }
+        const spawn = spec.spawn ?? cli_prompt_1.spawnAiCli;
+        const child = 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,
+        });
+        const session = { child, reader: null, handlers: null };
+        if (child.stdout) {
+            session.reader = (0, node_readline_1.createInterface)({ input: child.stdout, crlfDelay: Infinity });
+            session.reader.on('line', (line) => session.handlers?.onLine(line));
+        }
+        if (child.stderr) {
+            child.stderr.on('data', (chunk) => session.handlers?.onStderr(chunk.toString()));
+        }
+        const onExit = (code) => {
+            // Evict first so a handler that re-spawns inside onClose sees a clean slot.
+            if (this._sessions.get(id) === session)
+                this._sessions.delete(id);
+            session.handlers?.onClose(code);
+        };
+        child.on('close', onExit);
+        child.on('error', () => onExit(null));
+        this._sessions.set(id, session);
+        return { child, isNew: true };
+    }
+    /** Install the handlers for the current turn (replaces any prior turn's). */
+    setHandlers(id, handlers) {
+        const s = this._sessions.get(id);
+        if (s)
+            s.handlers = handlers;
+    }
+    /** Detach the current turn's handlers (between turns stray lines are dropped). */
+    clearHandlers(id) {
+        const s = this._sessions.get(id);
+        if (s)
+            s.handlers = null;
+    }
+    /** Write one framed user turn to the persistent child's stdin. */
+    writeTurn(id, text) {
+        const s = this._sessions.get(id);
+        if (!s || !s.child.stdin || s.child.stdin.destroyed)
+            return false;
+        return s.child.stdin.write(frameStreamJsonUserMessage(text));
+    }
+    /** Kill and forget one conversation's persistent child (idempotent). */
+    kill(id) {
+        const s = this._sessions.get(id);
+        if (!s)
+            return;
+        this._sessions.delete(id);
+        try {
+            s.reader?.close();
+        }
+        catch { /* best-effort */ }
+        try {
+            if (s.child.pid && !s.child.killed)
+                s.child.kill('SIGTERM');
+        }
+        catch { /* already gone */ }
+    }
+    /** Kill every persistent child (shutdown / project removal). */
+    killAll() {
+        for (const id of Array.from(this._sessions.keys()))
+            this.kill(id);
+    }
+}
+exports.ExploreStdinSessions = ExploreStdinSessions;

package/server/dist/feature-flags.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.isCodeExplorerEnabled = isCodeExplorerEnabled;
 exports.isBrowserCaptureEnabled = isBrowserCaptureEnabled;
+exports.isJiraEnabled = isJiraEnabled;
 function isCodeExplorerEnabled() {
     return process.env.SPECRAILS_CODE_EXPLORER !== 'false';
 }
@@ -15,3 +16,13 @@ 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';
+}

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();
+}

package/server/dist/jira/jira-backlog-config.js

@@ -0,0 +1,58 @@
+"use strict";
+// Writes `.specrails/backlog-config.json` so specrails-core treats the
+// materialized `local-tickets.json` as a plain LOCAL backlog it READS but never
+// mutates. This is the mechanism that keeps core at ZERO changes:
+//   - provider:"local"  → core reads `.specrails/local-tickets.json` (the cache).
+//   - write_access:false → core's implement pipeline enters its read-only branch
+//     and never mutates ticket status nor talks to Jira; Desktop's
+//     applyJobOutcomeToTickets + the Jira outbox are the sole status authority.
+//
+// We deliberately write provider:"local" (NOT "jira") so core never authenticates
+// to Jira — Desktop is the only thing that holds the credential.
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.backlogConfigPath = backlogConfigPath;
+exports.readBacklogConfig = readBacklogConfig;
+exports.writeJiraBacklogConfig = writeJiraBacklogConfig;
+exports.writeLocalBacklogConfig = writeLocalBacklogConfig;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+function backlogConfigPath(projectPath) {
+    return path_1.default.join(projectPath, '.specrails', 'backlog-config.json');
+}
+function readBacklogConfig(projectPath) {
+    try {
+        const raw = fs_1.default.readFileSync(backlogConfigPath(projectPath), 'utf-8');
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+/** Idempotently write the Jira-mode backlog config (local provider, read-only). */
+function writeJiraBacklogConfig(projectPath) {
+    const target = backlogConfigPath(projectPath);
+    const desired = { provider: 'local', write_access: false, git_auto: false };
+    const existing = readBacklogConfig(projectPath);
+    if (existing && existing.provider === desired.provider && existing.write_access === desired.write_access) {
+        return;
+    }
+    fs_1.default.mkdirSync(path_1.default.dirname(target), { recursive: true });
+    const tmp = `${target}.tmp`;
+    fs_1.default.writeFileSync(tmp, JSON.stringify(desired, null, 2), 'utf-8');
+    fs_1.default.renameSync(tmp, target);
+}
+/**
+ * Restore write access (used when hot-swapping a project back to local specs, so
+ * core can manage the local backlog normally again).
+ */
+function writeLocalBacklogConfig(projectPath) {
+    const target = backlogConfigPath(projectPath);
+    const desired = { provider: 'local', write_access: true, git_auto: false };
+    fs_1.default.mkdirSync(path_1.default.dirname(target), { recursive: true });
+    const tmp = `${target}.tmp`;
+    fs_1.default.writeFileSync(tmp, JSON.stringify(desired, null, 2), 'utf-8');
+    fs_1.default.renameSync(tmp, target);
+}