specrails-desktop 2.36.0 → 2.42.2

package/server/dist/core-compat.js

@@ -15,6 +15,7 @@ const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
 const setup_manager_1 = require("./setup-manager");
 const bundled_core_1 = require("./bundled-core");
+const core_runtime_1 = require("./core-runtime");
 // Windows has no `which`; probe PATH via `where` instead.
 const WHICH_CMD = process.platform === 'win32' ? 'where' : 'which';
 // These must mirror KNOWN_VERBS in cli/specrails-desktop.ts
@@ -43,6 +44,21 @@ function isStringArray(value) {
 function isRenderedProviderContract(provider, value) {
     if (!isRecord(value))
         return false;
+    // Core 5 has a deterministic installer. Enrichment no longer exists and is
+    // therefore not evidence of provider availability on this contract shape.
+    if (value.initCommand === 'init' && value.updateCommand === 'update') {
+        if (!isRecord(value.cli) || !isRecord(value.workflows))
+            return false;
+        if (!isStringArray(value.cli.initArgs) || !isStringArray(value.cli.updateArgs)
+            || !value.cli.initArgs.includes('init') || !value.cli.updateArgs.includes('update'))
+            return false;
+        const workflows = value.workflows;
+        if (!['implement', 'batch-implement', 'retry'].every(name => typeof workflows[name] === 'string' && workflows[name]))
+            return false;
+        return provider !== 'kimi' || (value.cli.providerBinary === 'kimi'
+            && value.cli.skillRunner === '.kimi-code/specrails/run-skill.mjs'
+            && isStringArray(value.cli.workflowArgs) && value.cli.workflowArgs.includes(value.cli.skillRunner));
+    }
     if (typeof value.enrichCommand !== 'string' ||
         value.enrichCommand.length === 0 ||
         !isStringArray(value.enrichArgs) ||
@@ -63,6 +79,14 @@ function isRenderedProviderContract(provider, value) {
         cli.enrichArgs.includes(skillRunner);
 }
 async function findCoreContract() {
+    const selected = (0, core_runtime_1.getCoreRuntimeStatus)();
+    if (selected.runtime) {
+        const contract = path_1.default.join(selected.runtime.root, 'integration-contract.json');
+        return fs_1.default.existsSync(contract) ? contract : null;
+    }
+    // A broken selected runtime must not advertise a different package's contract.
+    if (selected.error)
+        return null;
     // Strategy 1: the packaged Desktop's bundled Core is authoritative.
     const bundledRoot = (0, bundled_core_1.getBundledCoreRoot)();
     if (bundledRoot) {
@@ -208,7 +232,10 @@ async function checkCoreCompat() {
             ? Object.keys(contract.checkpoints)
             : []);
     const missingCheckpoints = contractCheckpoints.filter((c) => !desktopCheckpointKeys.includes(c));
-    const extraCheckpoints = desktopCheckpointKeys.filter((k) => !contractCheckpoints.includes(k));
+    const deterministic = contract.lifecycle?.mode === 'deterministic' && contract.lifecycle.requiresEnrich === false;
+    // Supporting legacy installation checkpoints is compatible with Core 5;
+    // demanding them from a deterministic installer would recreate enrich.
+    const extraCheckpoints = deterministic ? [] : desktopCheckpointKeys.filter((k) => !contractCheckpoints.includes(k));
     // v3 dropped the `commands` field from the contract — when absent, the
     // command-set check is a no-op (cannot prove drift either way).
     const contractCommands = Array.isArray(contract.commands) ? contract.commands : [];

package/server/dist/core-execution.js

@@ -0,0 +1,111 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.prepareCoreExecution = prepareCoreExecution;
+exports.coreVerificationContext = coreVerificationContext;
+const node_child_process_1 = require("node:child_process");
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const path_resolver_1 = require("./path-resolver");
+const core_update_state_1 = require("./core-update-state");
+const SAFE_ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+// Resolve existing ancestors too: the tickets file may not exist yet, and macOS
+// exposes temporary directories through both /var and /private/var.
+function canonicalPath(path) {
+    try {
+        return (0, node_fs_1.realpathSync)(path);
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+        const parent = (0, node_path_1.dirname)(path);
+        if (parent === path)
+            throw error;
+        return (0, node_path_1.join)(canonicalPath(parent), (0, node_path_1.basename)(path));
+    }
+}
+/** Stable run identity and frozen inputs are shared by every provider and retry.
+ * No cwd/global singleton: two rails in the same workspace get separate files.
+ */
+function prepareCoreExecution(input) {
+    const { run, manifest } = input;
+    if (!SAFE_ID.test(run.runId))
+        throw new Error('Invalid Core execution run id');
+    const cwd = (0, node_fs_1.realpathSync)(input.cwd);
+    (0, core_update_state_1.assertWorkspaceCoreReady)(cwd);
+    const repositories = manifest
+        ? manifest.repositories.map(repo => ({ id: repo.repositoryId, name: repo.name, path: (0, node_fs_1.realpathSync)(repo.worktreePath), baseSha: repo.baseSha }))
+        : [{ id: run.repositoryId ?? (run.spec?.repositoryIds?.length === 1 ? run.spec.repositoryIds[0] : 'primary'), name: (0, node_path_1.basename)(input.repoDir ?? cwd), path: (0, node_fs_1.realpathSync)(input.repoDir ?? cwd) }];
+    if (!repositories.length || repositories.some(repo => !SAFE_ID.test(repo.id)))
+        throw new Error('Invalid Core repository scope');
+    const artifactRepositoryId = manifest?.artifactRepositoryId ?? repositories[0].id;
+    const artifactRepo = repositories.find(repo => repo.id === artifactRepositoryId);
+    if (!artifactRepo)
+        throw new Error('Core artifact repository is outside the run scope');
+    const rawTickets = run.spec?.tickets?.length ? run.spec.tickets : run.spec ? [{
+            id: run.spec.id ?? run.spec.ticketIds?.[0] ?? 'goal', title: run.spec.title,
+            description: run.spec.description, repositoryIds: run.spec.repositoryIds,
+        }] : run.goal ? [{ id: 'goal', title: 'Loop goal', description: run.goal }] : [];
+    const specs = rawTickets.map(ticket => ({
+        id: ticket.id, title: ticket.title ?? '', description: ticket.description ?? '',
+        ...(ticket.repositoryIds ? { repositoryIds: [...ticket.repositoryIds] } : {}),
+    }));
+    if (specs.some(spec => spec.repositoryIds?.some(id => !repositories.some(repo => repo.id === id)))) {
+        throw new Error('Frozen spec selects a repository outside the execution scope');
+    }
+    const backlogPath = canonicalPath(input.env.SPECRAILS_TICKETS_PATH
+        ? (0, node_path_1.resolve)(input.env.SPECRAILS_TICKETS_PATH) : (0, node_path_1.join)(cwd, '.specrails', 'local-tickets.json'));
+    const backlogRoot = (0, node_fs_1.realpathSync)((0, node_path_1.dirname)((0, node_path_1.dirname)(backlogPath)));
+    const context = {
+        schemaVersion: 1, runId: run.runId, backlogRoot,
+        backlogPath, artifactRoot: artifactRepo.path,
+        artifactRepositoryId, repositories,
+        ownership: { git: input.env.SPECRAILS_GIT_AUTO === 'false' ? 'host' : 'core', backlog: 'host', worktrees: 'host' }, specs,
+    };
+    const directory = (0, node_path_1.join)(backlogRoot, '.specrails', 'pipeline', run.runId);
+    (0, node_fs_1.mkdirSync)(directory, { recursive: true, mode: 0o700 });
+    // Core owns context.json and may normalize/add fields there. Keep Desktop's
+    // immutable admission snapshot separate so the next rail step can reuse it.
+    const contextPath = (0, node_path_1.join)(directory, 'desktop-context.json');
+    const serialized = JSON.stringify(context, null, 2) + '\n';
+    try {
+        (0, node_fs_1.writeFileSync)(contextPath, serialized, { flag: 'wx', mode: 0o600 });
+    }
+    catch (error) {
+        if (error.code !== 'EEXIST')
+            throw error;
+        if ((0, node_fs_1.readFileSync)(contextPath, 'utf8') !== serialized)
+            throw new Error('Core execution context changed during an active run; start a new run for changed scope');
+    }
+    const env = { ...input.env, SPECRAILS_EXECUTION_CONTEXT: contextPath };
+    const promptPrefix = run.verificationStep ? coreVerificationContext(contextPath, cwd, env, run.runId) : '';
+    return { env, contextPath, promptPrefix };
+}
+/** Ask the installed Core runtime to validate its own receipts. Desktop never
+ * treats an agent-authored summary or a JSON 'pass' field as verification.
+ * Missing/old runtimes simply leave the normal verification path enabled.
+ */
+function coreVerificationContext(contextPath, cwd, env, runId) {
+    const helper = (0, node_path_1.join)(cwd, '.specrails', 'runtime', 'pipeline.mjs');
+    if (!(0, node_fs_1.existsSync)(helper))
+        return '';
+    try {
+        const stdout = (0, node_child_process_1.execFileSync)((0, path_resolver_1.resolveBundledNodeExe)() ?? process.execPath, [helper, 'status', '--context', contextPath], {
+            cwd, env, encoding: 'utf8', timeout: 15_000, maxBuffer: 4 * 1024 * 1024, stdio: ['ignore', 'pipe', 'pipe'],
+        });
+        const status = JSON.parse(stdout);
+        if (status.schemaVersion !== 1 || status.runId !== runId || status.verification?.valid !== true
+            || status.verification.receipt?.kind !== 'full' || status.phases?.reviewer?.status !== 'done')
+            return '';
+        const commands = status.verification.receipt.commands;
+        if (!commands?.length || commands.some(command => command.exitCode !== 0))
+            return '';
+        return [
+            'Core verified evidence for this exact run (validated by its installed runtime at step start):',
+            JSON.stringify({ receiptId: status.verification.receipt.id, commands: commands.map(({ repositoryId, command, args, cwd }) => ({ repositoryId, command, args, cwd })) }),
+            'You may reuse these successful commands while inspecting every acceptance criterion and cross-repository contract. Before reporting PASS, validate again with the installed pipeline runtime status using SPECRAILS_EXECUTION_CONTEXT. If you edit files, change configuration/environment, need uncovered behavioral checks, or the receipt is no longer valid, run the affected checks and refresh the full receipt. Do not repeat an unchanged complete verification merely because a new loop step started.',
+        ].join('\n');
+    }
+    catch {
+        return '';
+    }
+}

package/server/dist/core-package.js

@@ -1,19 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.CORE_PACKAGE_SPEC = void 0;
-/**
- * Single source of truth for the specrails-core npm package spec the app
- * installs and probes (H5). Pinned to the current major range so a future
- * specrails-core 5.x with breaking changes never lands on every user the
- * minute it is published — adopting a new major is a deliberate one-line
- * bump here, shipped through the app's own release pipeline.
- *
- * Floor bumped to 4.12.0 — the version that ships the Kimi provider target
- * (`.kimi-code/` skills + roles). It also changes the `npx` package-spec string,
- * which invalidates any stale `_npx` exec cache that npx would otherwise reuse
- * for the old `^4.6.0` range (so users actually resolve the newer core).
- *
- * `SPECRAILS_CORE_BIN` remains the escape hatch for local/linked builds
- * (see getCoreCommand in setup-manager.ts).
- */
-exports.CORE_PACKAGE_SPEC = 'specrails-core@^4.12.0';
+/** Online fallback selects the supported Core 5 lifecycle. Bundled Core 4 remains
+ * readable for installed apps; the runtime resolver selects the newest usable
+ * compatible package and never downgrades a newer activated framework. */
+exports.CORE_PACKAGE_SPEC = 'specrails-core@^5.0.0';

package/server/dist/core-runtime.js

@@ -0,0 +1,202 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.managedCoreRoot = managedCoreRoot;
+exports.frameworkRoot = frameworkRoot;
+exports.readCurrentFrameworkVersion = readCurrentFrameworkVersion;
+exports.readCoreRuntime = readCoreRuntime;
+exports.discoverExternalCoreRuntimes = discoverExternalCoreRuntimes;
+exports.resolveCoreRuntime = resolveCoreRuntime;
+exports.getCoreRuntimeStatus = getCoreRuntimeStatus;
+exports.readProjectCoreVersion = readProjectCoreVersion;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const artifact_registry_1 = require("./artifact-registry");
+const bundled_core_1 = require("./bundled-core");
+const semver_lite_1 = require("./semver-lite");
+const VERSION = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/;
+function managedCoreRoot(home) {
+    return path_1.default.join((0, artifact_registry_1.resolveHome)(home), '.specrails', 'core');
+}
+function frameworkRoot(home) {
+    return path_1.default.join((0, artifact_registry_1.resolveHome)(home), '.specrails', 'framework');
+}
+function readCurrentFrameworkVersion(home) {
+    const current = path_1.default.join(frameworkRoot(home), 'current');
+    try {
+        // realpath also rejects dangling pointers; a pathname alone is not an install.
+        const link = fs_1.default.lstatSync(current);
+        const target = link.isSymbolicLink() ? fs_1.default.readlinkSync(current) : current;
+        const resolved = fs_1.default.realpathSync(path_1.default.isAbsolute(target) ? target : path_1.default.resolve(frameworkRoot(home), target));
+        const name = path_1.default.basename(resolved);
+        if (VERSION.test(name))
+            return name;
+        const versions = new Set();
+        for (const file of fs_1.default.readdirSync(resolved)) {
+            if (!/^\.framework-stamp.*\.json$/.test(file))
+                continue;
+            const value = JSON.parse(fs_1.default.readFileSync(path_1.default.join(resolved, file), 'utf8')).version;
+            if (typeof value === 'string' && VERSION.test(value))
+                versions.add(value);
+        }
+        return versions.size === 1 ? [...versions][0] : null;
+    }
+    catch {
+        return null;
+    }
+}
+function readCoreRuntime(root, source) {
+    try {
+        const realRoot = fs_1.default.realpathSync(root);
+        const pkg = JSON.parse(fs_1.default.readFileSync(path_1.default.join(realRoot, 'package.json'), 'utf8'));
+        if (pkg.name && pkg.name !== 'specrails-core')
+            return null;
+        if (typeof pkg.version !== 'string' || !VERSION.test(pkg.version))
+            return null;
+        const cli = fs_1.default.realpathSync(path_1.default.join(realRoot, 'dist', 'installer', 'cli.js'));
+        if (!fs_1.default.statSync(cli).isFile())
+            return null;
+        return { root: realRoot, cli, version: pkg.version, source };
+    }
+    catch {
+        return null;
+    }
+}
+function packageForBinary(binary, source) {
+    const candidates = path_1.default.isAbsolute(binary) || /[/\\]/.test(binary)
+        ? [path_1.default.resolve(binary)]
+        : (process.env.PATH ?? '').split(path_1.default.delimiter).filter(Boolean).flatMap(dir => process.platform === 'win32'
+            ? ['', '.cmd', '.exe', '.bat'].map(ext => path_1.default.join(dir, binary + ext))
+            : [path_1.default.join(dir, binary)]);
+    for (const candidate of candidates) {
+        try {
+            let directory = path_1.default.dirname(fs_1.default.realpathSync(candidate));
+            // npm's Windows shim is beside node_modules, not inside the package.
+            const adjacent = readCoreRuntime(path_1.default.join(directory, 'node_modules', 'specrails-core'), source);
+            if (adjacent)
+                return adjacent;
+            for (let depth = 0; depth < 6; depth++) {
+                const runtime = readCoreRuntime(directory, source);
+                if (runtime)
+                    return runtime;
+                const parent = path_1.default.dirname(directory);
+                if (directory === parent)
+                    break;
+                directory = parent;
+            }
+        }
+        catch { /* missing PATH entry */ }
+    }
+    return null;
+}
+/** Read-only package discovery. No npm downloads and no execution of a PATH shim. */
+function discoverExternalCoreRuntimes() {
+    const result = [];
+    try {
+        const pkg = require.resolve('specrails-core/package.json');
+        const local = readCoreRuntime(path_1.default.dirname(pkg), 'local');
+        if (local)
+            result.push(local);
+    }
+    catch { /* not a local dependency */ }
+    const global = packageForBinary('specrails-core', 'global');
+    if (global)
+        result.push(global);
+    return result;
+}
+/** A caller supplying an isolated home can also supply its isolated external inventory. */
+function resolveCoreRuntime(home, external) {
+    const current = readCurrentFrameworkVersion(home);
+    const override = process.env.SPECRAILS_CORE_BIN;
+    if (override) {
+        const runtime = packageForBinary(override, 'override');
+        if (!runtime)
+            throw new Error('SPECRAILS_CORE_BIN does not resolve to a usable specrails-core package.');
+        if (![4, 5].includes(Number(runtime.version.split('.')[0])))
+            throw new Error('The explicit Core package is not compatible with this Desktop. Supported Core majors: 4 and 5.');
+        if (current && (0, semver_lite_1.compareVersions)(runtime.version, current) < 0)
+            throw new Error(`The explicit Core ${runtime.version} is older than active framework ${current}; Desktop will not downgrade it.`);
+        return runtime;
+    }
+    const candidates = [];
+    const bundled = (0, bundled_core_1.getBundledCoreRoot)();
+    if (bundled) {
+        const runtime = readCoreRuntime(bundled, 'bundled');
+        if (runtime)
+            candidates.push(runtime);
+    }
+    // Only activated managed packages are candidates. Failed staged updates must
+    // not become active simply because their directory exists after a restart.
+    if (current) {
+        const managed = readCoreRuntime(path_1.default.join(managedCoreRoot(home), current, 'node_modules', 'specrails-core'), 'managed');
+        if (managed && managed.version === current)
+            candidates.push(managed);
+    }
+    candidates.push(...(external ?? (home === undefined ? discoverExternalCoreRuntimes() : [])));
+    const compatible = candidates.filter(candidate => {
+        const major = Number(candidate.version.split('.')[0]);
+        return major >= 4 && major <= 5;
+    }).sort((a, b) => (0, semver_lite_1.compareVersions)(b.version, a.version));
+    const selected = compatible[0] ?? null;
+    if (current && (!selected || (0, semver_lite_1.compareVersions)(selected.version, current) < 0)) {
+        throw new Error(`Core framework ${current} is installed, but its runtime package is unavailable. Reinstall Core ${current} or a newer compatible version; Desktop will not downgrade it.`);
+    }
+    return selected;
+}
+function getCoreRuntimeStatus(home) {
+    try {
+        return { runtime: resolveCoreRuntime(home), error: null };
+    }
+    catch (error) {
+        return { runtime: null, error: error instanceof Error ? error.message : String(error) };
+    }
+}
+/** Actual provider links outrank an old workspace seed marker. Never attribute
+ * global current to a copied or deliberately pinned project. */
+function readProjectCoreVersion(root, repoPath, home) {
+    const providerVersions = {};
+    let recordedVersion = null;
+    for (const marker of [path_1.default.join(root, '.specrails', 'specrails-version'), path_1.default.join(repoPath, '.specrails-version')]) {
+        try {
+            const value = fs_1.default.readFileSync(marker, 'utf8').trim();
+            if (VERSION.test(value)) {
+                recordedVersion = value;
+                break;
+            }
+        }
+        catch { /* no legacy marker */ }
+    }
+    let framework = frameworkRoot(home);
+    try {
+        framework = fs_1.default.realpathSync(framework);
+    }
+    catch { /* no managed framework */ }
+    for (const [provider, directory] of Object.entries({ claude: '.claude', codex: '.codex', gemini: '.gemini', kimi: '.kimi-code' })) {
+        const versions = new Set();
+        const inspect = (entry, depth) => {
+            try {
+                const resolved = fs_1.default.realpathSync(entry);
+                const relative = path_1.default.relative(framework, resolved);
+                const version = relative.split(path_1.default.sep)[0];
+                if (!path_1.default.isAbsolute(relative) && !relative.startsWith('..') && VERSION.test(version)) {
+                    versions.add(version);
+                    return;
+                }
+                if (depth > 0 && fs_1.default.statSync(entry).isDirectory()) {
+                    for (const child of fs_1.default.readdirSync(entry))
+                        inspect(path_1.default.join(entry, child), depth - 1);
+                }
+            }
+            catch { /* provider absent or dangling */ }
+        };
+        inspect(path_1.default.join(root, directory), 2);
+        if (versions.size === 1)
+            providerVersions[provider] = [...versions][0];
+    }
+    const versions = new Set(Object.values(providerVersions));
+    const linked = versions.size === 1 ? [...versions][0] : null;
+    const mixed = fs_1.default.existsSync(path_1.default.join(root, '.specrails', 'core-update-pending.json')) || versions.size > 1 || Boolean(linked && recordedVersion && linked !== recordedVersion);
+    return { version: mixed ? null : linked ?? recordedVersion, providerVersions, recordedVersion, mixed };
+}