specrails-desktop 2.8.0 → 2.9.0

package/server/dist/artifact-registry.js

@@ -0,0 +1,468 @@
+"use strict";
+/**
+ * Shared artifact registry — the cross-tool contract that lets specrails-core
+ * place, and specrails-desktop write/read, a repo's relocated artifacts OUTSIDE
+ * the repo, under `$HOME/.specrails/projects/<slug>/workspace`.
+ *
+ * Single source of truth: `$HOME/.specrails/registry.json`, an inspectable,
+ * schema-versioned JSON file keyed by the **canonical realpath of the repo**.
+ * specrails-desktop is the PRIMARY writer (a projection of its `desktop.sqlite`);
+ * specrails-core reads it and, when run standalone, allocates its own entry.
+ *
+ * This module is a port of specrails-core's `src/installer/util/registry.ts`.
+ * The slug algorithm, canonical-key rule, atomic-write rule, lock protocol and
+ * workspace layout here MUST stay byte-identical to core — the correctness of
+ * the cross-tool contract depends on both tools resolving the same repo to the
+ * same paths. Everything is synchronous to match the installer's sync flow and
+ * to keep desktop's startup reconcile cheap.
+ *
+ * Beyond the ported core surface, this module adds the desktop-only writers that
+ * project `desktop.sqlite` into the registry: `mirrorProjectEntry`,
+ * `removeRegistryEntry`, and `reconcileFromProjects`.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.REGISTRY_SCHEMA_VERSION = void 0;
+exports.slugify = slugify;
+exports.resolveHome = resolveHome;
+exports.registryPath = registryPath;
+exports.lockPath = lockPath;
+exports.realpathSafe = realpathSafe;
+exports.normalizeKey = normalizeKey;
+exports.canonicalizeRepoPath = canonicalizeRepoPath;
+exports.workspaceLayout = workspaceLayout;
+exports.isCompleteEntry = isCompleteEntry;
+exports.readRegistryOrEmpty = readRegistryOrEmpty;
+exports.atomicWrite = atomicWrite;
+exports.withFileLock = withFileLock;
+exports.mirrorProjectEntry = mirrorProjectEntry;
+exports.resolveArtifacts = resolveArtifacts;
+exports.removeRegistryEntry = removeRegistryEntry;
+exports.reconcileFromProjects = reconcileFromProjects;
+const fs_1 = require("fs");
+const os_1 = __importDefault(require("os"));
+const path_1 = __importDefault(require("path"));
+/** Registry schema version. A reader that sees a higher value MUST treat all
+ *  entries as absent (legacy fallback), never mis-parse. */
+exports.REGISTRY_SCHEMA_VERSION = 1;
+/**
+ * Slug derivation — byte-identical to `slugify` in `server/desktop-router.ts`
+ * (and to specrails-core's port). Do NOT "improve" it; parity is the contract.
+ */
+function slugify(name) {
+    return name.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '');
+}
+/** `$HOME` for the registry, overridable for tests. Honors the
+ *  `SPECRAILS_REGISTRY_HOME` env var (mirrors core) when no explicit override
+ *  is passed, so the desktop-side wiring can be redirected in tests without
+ *  threading a `home` argument through every call site. */
+function resolveHome(home) {
+    return home ?? process.env.SPECRAILS_REGISTRY_HOME ?? os_1.default.homedir();
+}
+/** Absolute path to `registry.json`. */
+function registryPath(home) {
+    return path_1.default.join(resolveHome(home), '.specrails', 'registry.json');
+}
+/** Absolute path to the advisory lock file. */
+function lockPath(home) {
+    return registryPath(home) + '.lock';
+}
+/** `fs.realpathSync` that falls back to the resolved-but-unreal path on error
+ *  (the path may not exist yet, or be on a volume that rejects realpath). */
+function realpathSafe(abs) {
+    try {
+        return (0, fs_1.realpathSync)(abs);
+    }
+    catch {
+        return abs;
+    }
+}
+/** Case-fold the key on case-insensitive platforms (macOS, Windows) so two
+ *  spellings of the same path map to one entry. The stored `repoPath` keeps
+ *  its canonical case; only the index key is folded. */
+function normalizeKey(canon) {
+    if (process.platform === 'darwin' || process.platform === 'win32') {
+        return canon.toLowerCase();
+    }
+    return canon;
+}
+/** Canonical repo path: resolve to absolute, then realpath (collapses symlinks). */
+function canonicalizeRepoPath(repoPathInput) {
+    return realpathSafe(path_1.default.resolve(repoPathInput));
+}
+/** The per-project sub-path layout under a workspace dir. Single source of the
+ *  layout so writer and (allocation) reader never disagree. */
+function workspaceLayout(home, slug, canon) {
+    const workspaceDir = path_1.default.join(resolveHome(home), '.specrails', 'projects', slug, 'workspace');
+    const specrailsDir = path_1.default.join(workspaceDir, '.specrails');
+    return {
+        repoPath: canon,
+        slug,
+        workspaceDir,
+        artifactRoot: workspaceDir,
+        codeRoot: canon,
+        stateDir: path_1.default.join(workspaceDir, '.claude'),
+        ticketsPath: path_1.default.join(specrailsDir, 'local-tickets.json'),
+        backlogConfigPath: path_1.default.join(specrailsDir, 'backlog-config.json'),
+        profilesDir: path_1.default.join(specrailsDir, 'profiles'),
+        pluginsStateDir: path_1.default.join(specrailsDir, 'plugins'),
+        fileSummariesDir: path_1.default.join(specrailsDir, 'file-summaries'),
+    };
+}
+/** The path/identity fields a usable entry MUST carry. A hand-edited or
+ *  partially-written entry missing ANY of these is treated as ABSENT (legacy
+ *  fallback) rather than returned with `undefined` path fields that would crash
+ *  a downstream `fs` call or silently point at `undefined/...`. */
+const REQUIRED_ENTRY_FIELDS = [
+    'repoPath',
+    'slug',
+    'workspaceDir',
+    'artifactRoot',
+    'codeRoot',
+    'stateDir',
+    'ticketsPath',
+    'backlogConfigPath',
+    'profilesDir',
+    'pluginsStateDir',
+    'fileSummariesDir',
+];
+/**
+ * True only when `entry` carries every required path/identity field as a
+ * non-empty string. Guards against a hand-edited registry.json with a missing
+ * key (which would otherwise surface as `ticketsPath: undefined`).
+ */
+function isCompleteEntry(entry) {
+    if (!entry || typeof entry !== 'object')
+        return false;
+    const e = entry;
+    for (const f of REQUIRED_ENTRY_FIELDS) {
+        const v = e[f];
+        if (typeof v !== 'string' || v.length === 0)
+            return false;
+    }
+    return true;
+}
+/**
+ * Total, fail-open read. A missing file, a parse error, or a `schemaVersion`
+ * greater than we understand all yield an empty registry, so a caller treats
+ * it as "no entry" and (if writing) writes a fresh, understood entry rather
+ * than crashing. Biases toward availability over strict consistency — correct
+ * for a local, inspectable file.
+ */
+function readRegistryOrEmpty(home) {
+    const empty = { schemaVersion: exports.REGISTRY_SCHEMA_VERSION, projects: {} };
+    const p = registryPath(home);
+    if (!(0, fs_1.existsSync)(p))
+        return empty;
+    try {
+        const parsed = JSON.parse((0, fs_1.readFileSync)(p, 'utf8'));
+        if (!parsed ||
+            typeof parsed !== 'object' ||
+            typeof parsed.schemaVersion !== 'number' ||
+            parsed.schemaVersion > exports.REGISTRY_SCHEMA_VERSION ||
+            typeof parsed.projects !== 'object' ||
+            parsed.projects === null) {
+            return empty;
+        }
+        return parsed;
+    }
+    catch {
+        return empty;
+    }
+}
+/** Write `data` to `filePath` atomically: temp file in the same dir, fsync,
+ *  rename. A reader (even without the lock) only ever sees a complete old or
+ *  new file — the lock serialises writers, the rename protects readers. */
+function atomicWrite(filePath, data) {
+    const dir = path_1.default.dirname(filePath);
+    (0, fs_1.mkdirSync)(dir, { recursive: true });
+    // Deterministic-but-unique temp name (no Math.random/Date dependency for the
+    // name itself); collisions are impossible because the lock serialises writers.
+    const tmp = path_1.default.join(dir, `.${path_1.default.basename(filePath)}.tmp-${process.pid}`);
+    const fd = (0, fs_1.openSync)(tmp, 'w');
+    try {
+        (0, fs_1.writeFileSync)(fd, data);
+        (0, fs_1.fsyncSync)(fd);
+    }
+    finally {
+        (0, fs_1.closeSync)(fd);
+    }
+    (0, fs_1.renameSync)(tmp, filePath);
+}
+/** Synchronous sleep without busy-spinning the CPU. */
+function syncSleep(ms) {
+    const shared = new Int32Array(new SharedArrayBuffer(4));
+    Atomics.wait(shared, 0, 0, ms);
+}
+const LOCK_STALE_MS = 30_000;
+const LOCK_SPIN_MS = 50;
+const LOCK_MAX_WAIT_MS = 2_000;
+/**
+ * Run `fn` while holding an advisory lock over the registry. Mutual exclusion
+ * is an exclusive-create lock file (`open(..., 'wx')`) with bounded spin-retry
+ * and stale-lock breaking (a lock whose mtime exceeds the TTL is reclaimed —
+ * covers a crashed writer). Read-only callers never take the lock.
+ */
+function withFileLock(home, fn) {
+    const lp = lockPath(home);
+    (0, fs_1.mkdirSync)(path_1.default.dirname(lp), { recursive: true });
+    let fd;
+    // Unique per-acquisition token written INTO the lock file. On release we
+    // re-read the file and only unlink it when the token still matches OURS — so a
+    // writer whose lock was stale-broken (TTL-reclaimed) by another writer never
+    // deletes the NEW owner's lock out from under it (which would let a third
+    // writer acquire concurrently and race the read-modify-write).
+    const ourToken = `${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2)}`;
+    const deadline = Date.now() + LOCK_MAX_WAIT_MS;
+    for (;;) {
+        try {
+            fd = (0, fs_1.openSync)(lp, 'wx');
+            // Write our token + fsync so a concurrent reader sees a complete token.
+            try {
+                (0, fs_1.writeFileSync)(fd, ourToken);
+                (0, fs_1.fsyncSync)(fd);
+            }
+            catch {
+                /* best-effort — the lock still serialises via exclusive-create */
+            }
+            break;
+        }
+        catch {
+            // Lock held — break it if stale, otherwise spin until the deadline.
+            try {
+                const age = Date.now() - (0, fs_1.statSync)(lp).mtimeMs;
+                if (age > LOCK_STALE_MS) {
+                    (0, fs_1.unlinkSync)(lp);
+                    continue;
+                }
+            }
+            catch {
+                // lock vanished between open and stat — retry immediately
+                continue;
+            }
+            if (Date.now() >= deadline) {
+                // FAIL-CLOSED (parity with specrails-core): rather than proceed WITHOUT
+                // the lock — which would let two writers race a read-modify-write and
+                // clobber each other's entries — throw. Every caller wraps this in a
+                // non-fatal try/catch (a missing/un-updated entry is recreated on the
+                // next reconcile), so failing closed loses nothing while preserving the
+                // single-writer invariant.
+                throw new Error(`artifact-registry: could not acquire lock ${lp} within ${LOCK_MAX_WAIT_MS}ms`);
+            }
+            syncSleep(LOCK_SPIN_MS);
+        }
+    }
+    try {
+        return fn();
+    }
+    finally {
+        if (fd !== undefined) {
+            try {
+                (0, fs_1.closeSync)(fd);
+            }
+            catch {
+                /* already closed */
+            }
+            // Only unlink the lock when it still carries OUR token. If we were
+            // stale-broken and another writer now owns the file, its token differs and
+            // we leave it alone (a missing/unreadable file ⇒ already gone ⇒ no-op).
+            try {
+                const onDisk = (0, fs_1.readFileSync)(lp, 'utf8');
+                if (onDisk === ourToken) {
+                    (0, fs_1.unlinkSync)(lp);
+                }
+            }
+            catch {
+                /* already removed / unreadable — nothing to clean up */
+            }
+        }
+    }
+}
+function normalizeProviders(providers, primary) {
+    let list = providers && providers.length > 0 ? providers.slice() : undefined;
+    if (!list || list.length === 0) {
+        list = [primary && primary.length > 0 ? primary : 'claude'];
+    }
+    const primaryProvider = primary && primary.length > 0 ? primary : list[0];
+    return { providers: list, primaryProvider };
+}
+/**
+ * Build (or refresh) a desktop-owned entry for a repo, preserving artifact-
+ * location identity.
+ *
+ * INVARIANT: a `slug` + `workspaceDir` are **immutable once an entry exists**
+ * (the contract's "el slug queda congelado para siempre"). When ANY entry
+ * already exists for this repo — whether a prior desktop entry OR a
+ * `core-standalone` entry being adopted (possibly under a core-allocated slug
+ * that differs from desktop's) — we preserve EVERY path field verbatim and
+ * refresh only the mutable projection fields (providers, coreVersion, source,
+ * timestamps, desktopProjectId). Re-deriving the layout from `desiredSlug`
+ * would re-home an adopted/renamed entry and STRAND its on-disk artifacts.
+ *
+ * Only when no entry exists do we allocate fresh paths from `desiredSlug`.
+ *
+ * `touchInstall` = true for an install event (addProject) ⇒ bump
+ * `lastInstallAt`; false for a startup reconcile ⇒ leave it.
+ */
+function buildMirroredEntry(existing, canon, desiredSlug, input, now, touchInstall, home) {
+    let entry;
+    if (existing) {
+        entry = {
+            ...existing,
+            providers: input.providers,
+            primaryProvider: input.primaryProvider,
+            coreVersion: input.coreVersion ?? existing.coreVersion,
+            source: 'desktop',
+            createdAt: existing.createdAt ?? now,
+            lastInstallAt: touchInstall ? now : (existing.lastInstallAt ?? now),
+            updatedAt: now,
+        };
+    }
+    else {
+        const layout = workspaceLayout(home ?? resolveHome(home), desiredSlug, canon);
+        entry = {
+            ...layout,
+            providers: input.providers,
+            primaryProvider: input.primaryProvider,
+            coreVersion: input.coreVersion,
+            source: 'desktop',
+            createdAt: now,
+            lastInstallAt: now,
+            updatedAt: now,
+        };
+    }
+    if (input.desktopProjectId)
+        entry.desktopProjectId = input.desktopProjectId;
+    return entry;
+}
+/**
+ * Upsert a desktop-owned entry for a repo, keyed by the canonical repo path.
+ *
+ * Behaviour:
+ *  - new key ⇒ insert a fresh `source:'desktop'` entry, computing every sub-path
+ *    from `workspaceLayout` with the desktop slug.
+ *  - existing `source:'desktop'` entry ⇒ update providers/coreVersion/paths,
+ *    preserve `createdAt`, refresh `lastInstallAt`/`updatedAt`.
+ *  - existing `source:'core-standalone'` entry ⇒ ADOPT it: keep its slug +
+ *    workspaceDir (core already materialised artifacts there), flip
+ *    `source:'desktop'`, attach `desktopProjectId`. The workspace location is
+ *    immutable post-adoption so we never strand on-disk artifacts.
+ *
+ * Runs under the file lock with a re-read so concurrent writers serialise.
+ */
+function mirrorProjectEntry(input, home) {
+    const canon = canonicalizeRepoPath(input.repoPath);
+    const key = normalizeKey(canon);
+    const { providers, primaryProvider } = normalizeProviders(input.providers, input.primaryProvider);
+    return withFileLock(home, () => {
+        const reg = readRegistryOrEmpty(home);
+        const now = new Date().toISOString();
+        const existing = reg.projects[key];
+        const entry = buildMirroredEntry(existing, canon, input.slug, { providers, primaryProvider, coreVersion: input.coreVersion, desktopProjectId: input.desktopProjectId }, now, true, home);
+        reg.projects[key] = entry;
+        reg.schemaVersion = exports.REGISTRY_SCHEMA_VERSION;
+        reg.generator = 'specrails-desktop';
+        reg.updatedAt = now;
+        atomicWrite(registryPath(home), JSON.stringify(reg, null, 2) + '\n');
+        return entry;
+    });
+}
+/**
+ * Resolve a repo's artifact locations from the registry (read-only). Returns a
+ * legacy (repo-relative) resolution when no entry exists, so callers can treat
+ * the result uniformly. NEVER mutates the registry.
+ */
+function resolveArtifacts(repoPath, _options, home) {
+    const canon = canonicalizeRepoPath(repoPath);
+    const key = normalizeKey(canon);
+    const reg = readRegistryOrEmpty(home);
+    const rawEntry = reg.projects[key];
+    // A hand-edited / partially-written entry missing a path field must fall back
+    // to legacy (repo-relative) — never return `ticketsPath: undefined`.
+    const entry = isCompleteEntry(rawEntry) ? rawEntry : undefined;
+    if (!entry) {
+        // Legacy: every artifact lives under the repo's own `.specrails`.
+        const specrailsDir = path_1.default.join(canon, '.specrails');
+        return {
+            isLegacy: true,
+            repoPath: canon,
+            workspaceDir: canon,
+            specrailsDir,
+            ticketsPath: path_1.default.join(specrailsDir, 'local-tickets.json'),
+            backlogConfigPath: path_1.default.join(specrailsDir, 'backlog-config.json'),
+            profilesDir: path_1.default.join(specrailsDir, 'profiles'),
+            pluginsStateDir: path_1.default.join(specrailsDir, 'plugins'),
+            fileSummariesDir: path_1.default.join(specrailsDir, 'file-summaries'),
+            stateDir: path_1.default.join(canon, '.claude'),
+        };
+    }
+    return {
+        isLegacy: false,
+        repoPath: entry.codeRoot || canon,
+        workspaceDir: entry.workspaceDir,
+        specrailsDir: path_1.default.join(entry.workspaceDir, '.specrails'),
+        ticketsPath: entry.ticketsPath,
+        backlogConfigPath: entry.backlogConfigPath,
+        profilesDir: entry.profilesDir,
+        pluginsStateDir: entry.pluginsStateDir,
+        fileSummariesDir: entry.fileSummariesDir,
+        stateDir: entry.stateDir,
+        entry,
+    };
+}
+/** Delete a repo's registry entry (no-op if absent). Keyed by canonical path. */
+function removeRegistryEntry(repoPath, home) {
+    const canon = canonicalizeRepoPath(repoPath);
+    const key = normalizeKey(canon);
+    withFileLock(home, () => {
+        const reg = readRegistryOrEmpty(home);
+        if (!reg.projects[key])
+            return;
+        delete reg.projects[key];
+        reg.schemaVersion = exports.REGISTRY_SCHEMA_VERSION;
+        reg.generator = 'specrails-desktop';
+        reg.updatedAt = new Date().toISOString();
+        atomicWrite(registryPath(home), JSON.stringify(reg, null, 2) + '\n');
+    });
+}
+/**
+ * MERGE-upsert one entry per desktop project, leaving entries NOT owned by
+ * desktop (`source:'core-standalone'` for repos desktop doesn't track)
+ * UNTOUCHED. Never wholesale-wipes the registry. Run once at startup to
+ * self-heal a hand-edited / partially-written registry, and to backfill
+ * entries for projects added before the mirror existed.
+ *
+ * Adoption of a core-standalone entry happens exactly as in `mirrorProjectEntry`
+ * when a desktop project's canonical repo path matches a core-standalone key.
+ *
+ * All upserts happen under a single lock so the file is read + rewritten once.
+ */
+function reconcileFromProjects(projects, home) {
+    if (projects.length === 0)
+        return;
+    withFileLock(home, () => {
+        const reg = readRegistryOrEmpty(home);
+        const now = new Date().toISOString();
+        let changed = false;
+        for (const p of projects) {
+            const canon = canonicalizeRepoPath(p.repoPath);
+            const key = normalizeKey(canon);
+            const { providers, primaryProvider } = normalizeProviders(p.providers, p.primaryProvider);
+            const existing = reg.projects[key];
+            // Startup reconcile (touchInstall=false): preserve the immutable
+            // slug/workspace of any existing entry — never re-home an adopted or
+            // prior-desktop entry (that would strand on-disk artifacts every boot).
+            const entry = buildMirroredEntry(existing, canon, p.slug, { providers, primaryProvider, coreVersion: p.coreVersion, desktopProjectId: p.desktopProjectId }, now, false, home);
+            reg.projects[key] = entry;
+            changed = true;
+        }
+        if (!changed)
+            return;
+        reg.schemaVersion = exports.REGISTRY_SCHEMA_VERSION;
+        reg.generator = 'specrails-desktop';
+        reg.updatedAt = now;
+        atomicWrite(registryPath(home), JSON.stringify(reg, null, 2) + '\n');
+    });
+}

package/server/dist/attachment-manager.js

@@ -110,9 +110,8 @@ class AttachmentManager {
         fs_1.default.mkdirSync(dir, { recursive: true });
         fs_1.default.writeFileSync(path_1.default.join(dir, storedName), opts.file.buffer);
         fs_1.default.writeFileSync(this.sidecarPath(opts.slug, opts.ticketKey, id), JSON.stringify(attachment, null, 2), 'utf-8');
-        if (opts.projectPath) {
-            const ticketFile = (0, ticket_store_1.resolveTicketStoragePath)(opts.projectPath);
-            (0, ticket_store_1.mutateStore)(ticketFile, (store) => {
+        if (opts.ticketStorePath) {
+            (0, ticket_store_1.mutateStore)(opts.ticketStorePath, (store) => {
                 const ticket = store.tickets[String(opts.ticketKey)];
                 if (ticket) {
                     ticket.attachments = [...(ticket.attachments ?? []), attachment];
@@ -160,9 +159,8 @@ class AttachmentManager {
         const side = this.sidecarPath(opts.slug, opts.ticketKey, opts.attachmentId);
         if (fs_1.default.existsSync(side))
             fs_1.default.unlinkSync(side);
-        if (opts.projectPath) {
-            const ticketFile = (0, ticket_store_1.resolveTicketStoragePath)(opts.projectPath);
-            (0, ticket_store_1.mutateStore)(ticketFile, (store) => {
+        if (opts.ticketStorePath) {
+            (0, ticket_store_1.mutateStore)(opts.ticketStorePath, (store) => {
                 const ticket = store.tickets[String(opts.ticketKey)];
                 if (ticket?.attachments) {
                     ticket.attachments = ticket.attachments.filter((a) => a.id !== opts.attachmentId);
@@ -189,8 +187,7 @@ class AttachmentManager {
         fs_1.default.mkdirSync(path_1.default.dirname(dst), { recursive: true });
         fs_1.default.renameSync(src, dst);
         const list = this.list(opts.slug, opts.realTicketId);
-        const ticketFile = (0, ticket_store_1.resolveTicketStoragePath)(opts.projectPath);
-        (0, ticket_store_1.mutateStore)(ticketFile, (store) => {
+        (0, ticket_store_1.mutateStore)(opts.ticketStorePath, (store) => {
             const ticket = store.tickets[String(opts.realTicketId)];
             if (ticket) {
                 const existing = ticket.attachments ?? [];

package/server/dist/browser-capture-manager.js

@@ -340,7 +340,7 @@ class BrowserCaptureManager {
         const screenshot = await this.attachments.upload({
             slug: this.projectSlug,
             ticketKey: pendingSpecId,
-            projectPath: null,
+            ticketStorePath: null,
             file: {
                 buffer: png,
                 originalname: `screen-capture-${stamp}.png`,
@@ -352,7 +352,7 @@ class BrowserCaptureManager {
         const domAttachment = await this.attachments.upload({
             slug: this.projectSlug,
             ticketKey: pendingSpecId,
-            projectPath: null,
+            ticketStorePath: null,
             file: {
                 buffer: domJson,
                 originalname: `page-dom-${stamp}.json`,
@@ -471,7 +471,7 @@ class BrowserCaptureManager {
             const attachment = await this.attachments.upload({
                 slug: this.projectSlug,
                 ticketKey: pendingSpecId,
-                projectPath: null,
+                ticketStorePath: null,
                 file: { buffer: png, originalname: `screen-capture-${key}-${stamp}.png`, mimetype: 'image/png', size: png.length },
             });
             breakpoints[key] = { attachment, dataUrl: `data:image/png;base64,${png.toString('base64')}`, viewport: dims[key] };
@@ -484,7 +484,7 @@ class BrowserCaptureManager {
         const domAttachment = await this.attachments.upload({
             slug: this.projectSlug,
             ticketKey: pendingSpecId,
-            projectPath: null,
+            ticketStorePath: null,
             file: { buffer: domJson, originalname: `page-dom-${stamp}.json`, mimetype: 'application/json', size: domJson.length },
         });
         return {

package/server/dist/bundled-core.js

@@ -0,0 +1,72 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getBundledCoreRoot = getBundledCoreRoot;
+exports.getBundledCoreCli = getBundledCoreCli;
+exports.getBundledCoreVersion = getBundledCoreVersion;
+exports.hasBundledCore = hasBundledCore;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+/**
+ * Bundled specrails-core resolution.
+ *
+ * The Tauri host (src-tauri/src/lib.rs) sets `SPECRAILS_BUNDLED_CORE_PATH` to
+ * `<resource_dir>/core` — but ONLY when the compiled CLI actually exists on disk
+ * (existence-gated, mirroring `SPECRAILS_BUNDLED_RUNTIMES_PATH`). When the env is
+ * absent (a build that shipped no core, a partial extraction, or any non-desktop
+ * mode like `npm run dev:server`) these helpers return null and EVERY caller
+ * falls back to the legacy `npx specrails-core` path — byte-identical to today.
+ *
+ * This is the single chokepoint: do NOT read `SPECRAILS_BUNDLED_CORE_PATH`
+ * anywhere else; resolve through `getBundledCoreCli()` / `getBundledCoreRoot()`.
+ */
+/** The bundled core package root (`<resource_dir>/core`) or null when absent. */
+function getBundledCoreRoot() {
+    const p = process.env.SPECRAILS_BUNDLED_CORE_PATH;
+    if (!p || p.length === 0)
+        return null;
+    // Existence-gate (defence-in-depth — lib.rs already gates, but a stale env
+    // from a partial uninstall must never make us shell out to a missing file).
+    if (!fs_1.default.existsSync(p))
+        return null;
+    return p;
+}
+/**
+ * Absolute path to the bundled core CLI entry
+ * (`<core>/dist/installer/cli.js`), or null when no bundled core is present (→
+ * caller falls back to `npx specrails-core`).
+ */
+function getBundledCoreCli() {
+    const root = getBundledCoreRoot();
+    if (!root)
+        return null;
+    const cli = path_1.default.join(root, 'dist', 'installer', 'cli.js');
+    if (!fs_1.default.existsSync(cli))
+        return null;
+    return cli;
+}
+/**
+ * The version of the bundled core (from `<core>/package.json`), or null when no
+ * bundled core / unreadable. FrameworkManager.versionCheck compares this against
+ * the materialized `framework/current` to decide whether to re-materialize.
+ */
+function getBundledCoreVersion() {
+    const root = getBundledCoreRoot();
+    if (!root)
+        return null;
+    const pkgPath = path_1.default.join(root, 'package.json');
+    try {
+        const pkg = JSON.parse(fs_1.default.readFileSync(pkgPath, 'utf8'));
+        const v = pkg.version?.trim();
+        return v && v.length > 0 ? v : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** True when a usable bundled core (env + CLI on disk) is present. */
+function hasBundledCore() {
+    return getBundledCoreCli() !== null;
+}

package/server/dist/bundled-openspec.js

@@ -0,0 +1,58 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getBundledOpenspecCli = getBundledOpenspecCli;
+exports.hasBundledOpenspec = hasBundledOpenspec;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+/**
+ * Bundled `@fission-ai/openspec` resolution.
+ *
+ * The Tauri host (src-tauri/src/lib.rs) sets `SPECRAILS_BUNDLED_OPENSPEC_PATH` to
+ * `<resource_dir>/openspec` — but ONLY when the openspec CLI entry actually
+ * exists on disk (existence-gated, mirroring `SPECRAILS_BUNDLED_CORE_PATH`).
+ * When the env is absent (a build that shipped no openspec, a partial
+ * extraction, or any non-desktop mode like `npm run dev:server`) these helpers
+ * return null and the bundled-core init falls back to the legacy
+ * `npx @fission-ai/openspec` path — byte-identical to today.
+ *
+ * openspec is bundled as a `npm install`ed tree (it has runtime deps), so the
+ * CLI lives at:
+ *   <openspec>/node_modules/@fission-ai/openspec/bin/openspec.js
+ *
+ * This is the single chokepoint: do NOT read `SPECRAILS_BUNDLED_OPENSPEC_PATH`
+ * anywhere else; resolve through `getBundledOpenspecCli()`.
+ */
+/** Relative path (from the bundle root) to the openspec CLI node entry. */
+const OPENSPEC_CLI_REL = path_1.default.join('node_modules', '@fission-ai', 'openspec', 'bin', 'openspec.js');
+/** The bundled openspec root (`<resource_dir>/openspec`) or null when absent. */
+function getBundledOpenspecRoot() {
+    const p = process.env.SPECRAILS_BUNDLED_OPENSPEC_PATH;
+    if (!p || p.length === 0)
+        return null;
+    // Existence-gate (defence-in-depth — lib.rs already gates, but a stale env
+    // from a partial uninstall must never make us point at a missing file).
+    if (!fs_1.default.existsSync(p))
+        return null;
+    return p;
+}
+/**
+ * Absolute path to the bundled openspec CLI node entry
+ * (`<openspec>/node_modules/@fission-ai/openspec/bin/openspec.js`), or null when
+ * no bundled openspec is present (→ bundled-core init falls back to npx openspec).
+ */
+function getBundledOpenspecCli() {
+    const root = getBundledOpenspecRoot();
+    if (!root)
+        return null;
+    const cli = path_1.default.join(root, OPENSPEC_CLI_REL);
+    if (!fs_1.default.existsSync(cli))
+        return null;
+    return cli;
+}
+/** True when a usable bundled openspec (env + CLI on disk) is present. */
+function hasBundledOpenspec() {
+    return getBundledOpenspecCli() !== null;
+}