specrails-desktop 2.8.0 → 2.9.1

package/server/dist/ticket-store.js

@@ -340,11 +340,15 @@ function extractTicketIdsFromCommand(command) {
  * resolve to `title: null`. Returns `[]` when the command has no ticket
  * references.
  */
-function resolveTicketsFromCommand(projectPath, command) {
+function resolveTicketsFromCommand(projectPath, command, 
+/** Relocate-artifacts: when provided, read the store from this absolute path
+ *  (the workspace ticket store) instead of `resolveTicketStoragePath(
+ *  projectPath)`. Legacy callers omit it and behave byte-identically. */
+ticketsPathOverride) {
     const ids = extractTicketIdsFromCommand(command);
     if (ids.length === 0)
         return [];
-    const store = readStore(resolveTicketStoragePath(projectPath));
+    const store = readStore(ticketsPathOverride ?? resolveTicketStoragePath(projectPath));
     return ids.map((id) => ({
         id,
         title: store.tickets[String(id)]?.title ?? null,

package/server/dist/ticket-watcher.js

@@ -7,6 +7,7 @@ exports.TicketWatcher = void 0;
 const path_1 = __importDefault(require("path"));
 const fs_1 = __importDefault(require("fs"));
 const chokidar_1 = require("chokidar");
+const workspace_resolution_1 = require("./workspace-resolution");
 const TICKET_FILE = '.specrails/local-tickets.json';
 const DEBOUNCE_MS = 150;
 /**
@@ -33,7 +34,10 @@ class TicketWatcher {
     start() {
         if (this._closed)
             return;
-        const filePath = path_1.default.join(this._projectPath, TICKET_FILE);
+        // Relocate-artifacts gate: watch the workspace ticket file when relocated,
+        // else the repo-relative file (byte-identical for existing projects).
+        const exec = (0, workspace_resolution_1.resolveProjectExecution)({ path: this._projectPath });
+        const filePath = exec.relocated ? exec.ticketsPath : path_1.default.join(this._projectPath, TICKET_FILE);
         // Seed initial revision so we can detect external changes
         this._lastRevision = this._readRevision(filePath);
         this._watcher = new chokidar_1.FSWatcher({

package/server/dist/vitest-setup.js

@@ -0,0 +1,25 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const fs_1 = require("fs");
+const os_1 = __importDefault(require("os"));
+const path_1 = __importDefault(require("path"));
+/**
+ * Test safety net: NEVER let a test write the relocation registry into the
+ * developer's real `$HOME/.specrails/registry.json`.
+ *
+ * `ProjectRegistry.loadAll()` runs `reconcileFromProjects`, and `addProject`
+ * runs `mirrorProjectEntry`; both resolve the registry path from
+ * `resolveHome()`, which falls back to `os.homedir()` when neither a `home`
+ * arg nor `SPECRAILS_REGISTRY_HOME` is set. A test that constructs a
+ * `ProjectRegistry` without pinning a tmp home would then pollute the real
+ * registry. This setup file (run once per test file by vitest `setupFiles`)
+ * points `SPECRAILS_REGISTRY_HOME` at a throwaway tmp dir unless the test has
+ * already set its own, so the real home is unreachable from tests by
+ * construction. Tests that need a specific home still override it per-test.
+ */
+if (!process.env.SPECRAILS_REGISTRY_HOME) {
+    process.env.SPECRAILS_REGISTRY_HOME = (0, fs_1.mkdtempSync)(path_1.default.join(os_1.default.tmpdir(), 'specrails-desktop-test-home-'));
+}

package/server/dist/workspace-manager.js

@@ -0,0 +1,199 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.workspacePathFor = workspacePathFor;
+exports.ensureWorkspace = ensureWorkspace;
+exports.assembleWorkspaceFramework = assembleWorkspaceFramework;
+exports.removeWorkspace = removeWorkspace;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const os_1 = __importDefault(require("os"));
+const framework_manager_1 = require("./framework-manager");
+const framework_migration_1 = require("./framework-migration");
+/**
+ * WorkspaceManager — a reusable materializer for the per-project workspace dir
+ * under `~/.specrails/projects/<slug>/workspace`. This is the relocation target
+ * for a repo's artifacts (see `server/artifact-registry.ts` + the global-
+ * artifacts-alignment contract): the workspace holds the `./project` link back
+ * to the user's repo so tools spawned with the workspace as cwd can still reach
+ * the source.
+ *
+ * This generalizes the materialization logic of `explore-cwd-manager.ts`
+ * (the `ensureProjectLink` symlink/junction/fallback dance) without coupling to
+ * the Explore-specific embedded instructions file. Explore-cwd is intentionally
+ * left UNCHANGED (it keeps its own parallel copy); this module is the forward-
+ * looking home for workspace materialization.
+ *
+ * NOTE (this stage): nothing yet spawns from the workspace dir. This is the
+ * additive foundation — wiring spawn cwd/env to the workspace is a later stage.
+ */
+/** Base dir holding all per-project app data. Overridable for tests. */
+function projectsBaseDir(home) {
+    return path_1.default.join(home ?? os_1.default.homedir(), '.specrails', 'projects');
+}
+/**
+ * Compute the workspace path for a project without touching the filesystem.
+ * Mirrors `artifact-registry.workspaceLayout(...).workspaceDir`.
+ */
+function workspacePathFor(slug, home) {
+    return path_1.default.join(projectsBaseDir(home), slug, 'workspace');
+}
+/**
+ * Create or refresh the workspace dir for a project. Idempotent and cheap when
+ * already up-to-date. Creates the workspace directory and a `./project`
+ * symlink (junction on Windows) pointing at `projectPath`, with a
+ * `project-path.txt` fallback when symlink/junction creation fails. Returns the
+ * absolute workspace path.
+ */
+function ensureWorkspace(slug, projectPath, home) {
+    const ws = workspacePathFor(slug, home);
+    fs_1.default.mkdirSync(ws, { recursive: true });
+    ensureProjectLink(ws, projectPath);
+    return ws;
+}
+/**
+ * Ensure the workspace exists (with the `./project` link) AND assemble the
+ * framework into it by SYMLINK (offline) via the bundled specrails-core
+ * `assemble` subcommand. The providerDir static subtrees
+ * (`agents/`/`commands/`/`skills/`/`rules/`) become symlinks into
+ * `~/.specrails/framework/current/<provider>/`; `agent-memory/` stays a real
+ * writable dir (core's assemble handles that distinction).
+ *
+ * EXISTENCE-GATED: when no bundled core is present, `assembled` is false and the
+ * caller must fall back to the legacy `npx specrails-core init` assembly. The
+ * workspace + `./project` link are still ensured so the legacy path has a cwd.
+ */
+function assembleWorkspaceFramework(slug, projectPath, provider, opts = {}) {
+    const ws = ensureWorkspace(slug, projectPath, opts.home);
+    const fm = opts.framework ?? new framework_manager_1.FrameworkManager({ home: opts.home });
+    if (!fm.isAvailable()) {
+        return { assembled: false, workspace: ws };
+    }
+    // Lazy-on-first-touch migration: if this workspace still holds a per-workspace
+    // framework COPY (the pre-bundled relocate-core layout), convert it to symlinks
+    // into `framework/current` non-destructively BEFORE assembling. Idempotent +
+    // safe to run repeatedly; it no-ops once the workspace is symlinked. The
+    // migration re-enters this function with `_skipMigrate` to do the actual
+    // re-link, so we guard against infinite recursion here.
+    if (!opts._skipMigrate) {
+        try {
+            (0, framework_migration_1.migrateWorkspaceToSymlinks)(slug, projectPath, provider, {
+                home: opts.home,
+                framework: fm,
+                broadcast: opts.broadcast,
+            });
+        }
+        catch {
+            /* migration is best-effort; assemble below still produces a usable layout */
+        }
+    }
+    const res = fm.assembleWorkspace({
+        workspace: ws,
+        provider,
+        version: opts.version,
+        codeRoot: projectPath,
+    });
+    if (!res.ran)
+        return { assembled: false, workspace: ws };
+    return { assembled: true, workspace: ws, error: res.error };
+}
+/**
+ * Recursively remove the workspace dir for a project. The `project`
+ * symlink/junction is unlinked explicitly (never followed) so the user's repo
+ * is never touched. No-op when the dir does not exist.
+ */
+function removeWorkspace(slug, home) {
+    const ws = workspacePathFor(slug, home);
+    if (!fs_1.default.existsSync(ws))
+        return;
+    const linkPath = path_1.default.join(ws, 'project');
+    try {
+        const st = fs_1.default.lstatSync(linkPath);
+        if (st.isSymbolicLink() || (process.platform === 'win32' && st.isDirectory())) {
+            // unlink works on POSIX symlinks; rmdir on Windows junctions
+            try {
+                fs_1.default.unlinkSync(linkPath);
+            }
+            catch {
+                try {
+                    fs_1.default.rmdirSync(linkPath);
+                }
+                catch { /* best-effort */ }
+            }
+        }
+    }
+    catch {
+        /* link may not exist */
+    }
+    fs_1.default.rmSync(ws, { recursive: true, force: true });
+}
+/**
+ * Ensure `<ws>/project` resolves to `<projectPath>` (symlink on POSIX, junction
+ * on Windows). Recreated when the existing target differs. On both symlink and
+ * junction failure, writes a `project-path.txt` fallback. This is the EXACT
+ * logic from `explore-cwd-manager.ts`'s private `ensureProjectLink`.
+ */
+function ensureProjectLink(cwd, projectPath) {
+    const linkPath = path_1.default.join(cwd, 'project');
+    const fallbackPath = path_1.default.join(cwd, 'project-path.txt');
+    let needsCreate = true;
+    try {
+        const st = fs_1.default.lstatSync(linkPath);
+        if (st.isSymbolicLink()) {
+            const current = fs_1.default.readlinkSync(linkPath);
+            if (path_1.default.resolve(cwd, current) === path_1.default.resolve(projectPath)) {
+                needsCreate = false;
+            }
+            else {
+                fs_1.default.unlinkSync(linkPath);
+            }
+        }
+        else {
+            // existing non-symlink (e.g. Windows junction or stale dir) — replace
+            try {
+                fs_1.default.unlinkSync(linkPath);
+            }
+            catch {
+                try {
+                    fs_1.default.rmdirSync(linkPath);
+                }
+                catch { /* best-effort */ }
+            }
+        }
+    }
+    catch {
+        /* link does not exist — fall through to create */
+    }
+    if (needsCreate) {
+        let created = false;
+        if (process.platform === 'win32') {
+            try {
+                fs_1.default.symlinkSync(projectPath, linkPath, 'junction');
+                created = true;
+            }
+            catch { /* fall through to plain symlink */ }
+        }
+        if (!created) {
+            try {
+                fs_1.default.symlinkSync(projectPath, linkPath);
+                created = true;
+            }
+            catch { /* fall through to text fallback */ }
+        }
+        if (!created) {
+            // Final fallback: write the absolute path so the model can use it.
+            fs_1.default.writeFileSync(fallbackPath, projectPath, 'utf-8');
+            return;
+        }
+    }
+    // If we successfully created/verified the symlink, clean up any stale
+    // fallback file from a prior failed attempt.
+    if (fs_1.default.existsSync(fallbackPath)) {
+        try {
+            fs_1.default.unlinkSync(fallbackPath);
+        }
+        catch { /* ignore */ }
+    }
+}

package/server/dist/workspace-resolution.js

@@ -0,0 +1,147 @@
+"use strict";
+/**
+ * workspace-resolution — the SINGLE gate for the relocate-artifacts-to-home
+ * feature (DESKTOP STAGE 2). Every spawner cwd/env decision and every relocated
+ * artifact-read site funnels through `resolveProjectExecution(...)`.
+ *
+ * THE GATE — a project is "relocated" iff BOTH hold:
+ *   1. a registry entry exists for the repo (`resolveArtifacts(...).isLegacy ===
+ *      false`), AND
+ *   2. the workspace is actually populated by core — detected by the presence of
+ *      `<workspace>/.specrails/specrails-version` (core installed there).
+ *
+ * When NOT relocated (every existing in-repo project, or a relocated registry
+ * entry whose workspace core has not yet populated) the resolution is
+ * BYTE-IDENTICAL to pre-stage-2 behaviour: cwd = project.path, repo-relative
+ * artifact paths, empty env. This is what keeps stage 2 regression-safe for
+ * existing users — only relocated projects diverge.
+ *
+ * When relocated:
+ *   - cwd        = the workspace dir (core discovers sr-* agents there),
+ *   - repoDir    = project.path (the user's repo; source/git/openspec stay here),
+ *   - env        = { SPECRAILS_REPO_DIR: project.path, ... } so stage-3
+ *                  `${SPECRAILS_REPO_DIR:-.}` re-pointing drives source/openspec/
+ *                  git I/O back into the repo,
+ *   - artifact paths point at the workspace (from the registry entry),
+ *   - the `<workspace>/project` symlink is (re)created before returning so tools
+ *     spawned from the workspace can still reach the repo by relative path.
+ *
+ * The workspace path is ALWAYS read from the registry entry (an adopted repo's
+ * registry slug may differ from the desktop.sqlite slug); never recompute it
+ * from a desktop slug.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isWorkspacePopulated = isWorkspacePopulated;
+exports.resolveProjectExecution = resolveProjectExecution;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const artifact_registry_1 = require("./artifact-registry");
+const workspace_manager_1 = require("./workspace-manager");
+/** Marker file core writes into the workspace once it has installed there. The
+ *  presence of this file is the "populated" half of the gate. */
+const WORKSPACE_VERSION_MARKER = path_1.default.join('.specrails', 'specrails-version');
+/** True when `<workspaceDir>/.specrails/specrails-version` exists (core has
+ *  installed into the workspace). The legacy `.specrails-version` location is
+ *  NOT a workspace marker (a bare workspace dir never has the dot-file form).
+ *
+ *  Bundled-framework layout: `assemble` SYMLINKS the providerDir subtrees
+ *  (`agents/` per-file, `commands/`/`skills/`/`rules/` whole-dir) into the
+ *  workspace but writes the `.specrails/specrails-version` marker as a REAL file
+ *  (via core's `writeManifestFiles`). So "populated" depends only on the real
+ *  marker — it is agnostic to whether the providerDir is a real dir or a tree of
+ *  symlinks into `framework/current/<provider>/`. `fs.existsSync` resolves the
+ *  marker (and would also resolve it through a symlinked `.specrails`, though the
+ *  manifest layer is never linked). */
+function isWorkspacePopulated(workspaceDir) {
+    try {
+        return fs_1.default.existsSync(path_1.default.join(workspaceDir, WORKSPACE_VERSION_MARKER));
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * THE GATE. Resolve how a project's AI CLIs should be spawned and where its
+ * relocated artifacts live. Read-only with respect to the registry; the only
+ * side effect (when relocated) is (re)creating the workspace `./project` symlink
+ * via `ensureWorkspace`.
+ */
+function resolveProjectExecution(project, home) {
+    const repoDir = project.path;
+    let art;
+    try {
+        art = (0, artifact_registry_1.resolveArtifacts)(project.path, { allocate: false }, home);
+    }
+    catch {
+        // A registry read failure must never break a spawn — fall back to legacy.
+        return legacyExecution(repoDir);
+    }
+    // Gate part 1: no registry entry ⇒ legacy.
+    if (art.isLegacy) {
+        return legacyExecution(repoDir);
+    }
+    // Gate part 2: registry entry exists but the workspace is NOT yet populated by
+    // core ⇒ stay legacy (existing project that has a registry entry but whose
+    // core install still lives in-repo). This is what keeps every existing
+    // assertion valid: a registry entry alone never flips a project to relocated.
+    if (!isWorkspacePopulated(art.workspaceDir)) {
+        return legacyExecution(repoDir);
+    }
+    // Relocated. (Re)create the workspace `./project` symlink so tools spawned from
+    // the workspace can still reach the repo. ALWAYS use the REGISTRY entry's slug
+    // (an adopted repo's registry slug may differ from the desktop slug) so the
+    // symlink lands in the same workspace dir core populated. Best-effort — a
+    // symlink failure must not abort the spawn (ensureWorkspace falls back to
+    // project-path.txt internally).
+    const workspaceSlug = art.entry?.slug ?? project.slug;
+    try {
+        if (workspaceSlug)
+            (0, workspace_manager_1.ensureWorkspace)(workspaceSlug, repoDir, home);
+    }
+    catch {
+        /* non-fatal — ensureWorkspace already has its own fallbacks */
+    }
+    const env = {
+        SPECRAILS_REPO_DIR: repoDir,
+        SPECRAILS_WORKSPACE_DIR: art.workspaceDir,
+        SPECRAILS_TICKETS_PATH: art.ticketsPath,
+        SPECRAILS_STATE_DIR: art.stateDir,
+        SPECRAILS_BACKLOG_CONFIG_PATH: art.backlogConfigPath,
+        SPECRAILS_PROFILES_DIR: art.profilesDir,
+    };
+    return {
+        relocated: true,
+        cwd: art.workspaceDir,
+        repoDir,
+        workspaceDir: art.workspaceDir,
+        ticketsPath: art.ticketsPath,
+        backlogConfigPath: art.backlogConfigPath,
+        profilesDir: art.profilesDir,
+        pluginsStateDir: art.pluginsStateDir,
+        fileSummariesDir: art.fileSummariesDir,
+        specrailsDir: art.specrailsDir,
+        stateDir: art.stateDir,
+        env,
+    };
+}
+/** Build the legacy (in-repo, byte-identical-to-today) execution. */
+function legacyExecution(repoDir) {
+    const specrailsDir = path_1.default.join(repoDir, '.specrails');
+    return {
+        relocated: false,
+        cwd: repoDir,
+        repoDir,
+        workspaceDir: null,
+        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'),
+        specrailsDir,
+        stateDir: path_1.default.join(repoDir, '.claude'),
+        env: {},
+    };
+}