spexcode 0.6.1 → 0.6.5

package/node_modules/@spexcode/spec-core/dist/process-identity.js

@@ -0,0 +1,214 @@
+import { randomUUID } from 'node:crypto';
+import { execFileSync } from 'node:child_process';
+import { mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { platform } from 'node:os';
+import { dirname, join } from 'node:path';
+export function parseProcStat(text) {
+    const end = text.lastIndexOf(')');
+    if (end < 0)
+        throw new Error('malformed proc stat');
+    const fields = text.slice(end + 2).trim().split(/\s+/);
+    if (fields.length < 22)
+        throw new Error('short proc stat');
+    return {
+        ppid: Number(fields[1]),
+        processGroupId: Number(fields[2]),
+        sessionId: Number(fields[3]),
+        ticks: Number(fields[11]) + Number(fields[12]),
+        startToken: fields[19],
+        rssPages: Number(fields[21]),
+    };
+}
+export function processStartToken(pid, procRoot = '/proc') {
+    if (platform() === 'linux' || procRoot !== '/proc') {
+        try {
+            return parseProcStat(readFileSync(join(procRoot, String(pid), 'stat'), 'utf8')).startToken;
+        }
+        catch {
+            return null;
+        }
+    }
+    try {
+        const started = execFileSync('ps', ['-o', 'lstart=', '-p', String(pid)], { encoding: 'utf8' }).trim();
+        return started || null;
+    }
+    catch {
+        return null;
+    }
+}
+const procField = (pid, field) => {
+    try {
+        const stat = parseProcStat(readFileSync(join('/proc', String(pid), 'stat'), 'utf8'));
+        return stat[field];
+    }
+    catch {
+        return null;
+    }
+};
+const psProcessGroupId = (pid) => {
+    try {
+        const value = Number(execFileSync('ps', ['-o', 'pgid=', '-p', String(pid)], { encoding: 'utf8' }).trim());
+        return Number.isInteger(value) && value > 0 ? value : null;
+    }
+    catch {
+        return null;
+    }
+};
+export const hostProcessAdapter = Object.freeze({
+    platform: platform(),
+    startToken: (pid) => processStartToken(pid),
+    processGroupId: (pid) => platform() === 'linux' ? procField(pid, 'processGroupId') : psProcessGroupId(pid),
+    linuxSessionId: (pid) => platform() === 'linux' ? procField(pid, 'sessionId') : null,
+});
+const exactKeys = (value, expected) => {
+    const actual = Object.keys(value).sort();
+    return actual.length === expected.length && actual.every((key, index) => key === expected[index]);
+};
+const parseDetachedLaunchReceipt = (text, hostPlatform) => {
+    let value;
+    try {
+        value = JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return null;
+    const receipt = value;
+    const keys = ['kind', 'pid', 'processGroupId', 'startToken', 'version', ...(hostPlatform === 'linux' ? ['linuxSessionId'] : [])].sort();
+    if (!exactKeys(receipt, keys) || receipt.version !== 4 || receipt.kind !== 'spexcode-detached-runtime' ||
+        !Number.isInteger(receipt.pid) || Number(receipt.pid) <= 0 || typeof receipt.startToken !== 'string' || !receipt.startToken ||
+        !Number.isInteger(receipt.processGroupId) || Number(receipt.processGroupId) <= 0 ||
+        (hostPlatform === 'linux' && (!Number.isInteger(receipt.linuxSessionId) || Number(receipt.linuxSessionId) <= 0)))
+        return null;
+    return receipt;
+};
+const observeDetachedRuntime = (pid, adapter) => {
+    if (adapter.platform === 'win32')
+        return { ok: false, reason: 'detached runtime identity is unsupported on win32' };
+    const startBefore = adapter.startToken(pid);
+    if (!startBefore)
+        return { ok: false, reason: `PID ${pid} has no readable process-start identity` };
+    const processGroupId = adapter.processGroupId(pid);
+    if (processGroupId !== pid)
+        return { ok: false, reason: `PID ${pid} is not its own process-group leader (pgrp=${processGroupId ?? 'unknown'})` };
+    let linuxSessionId;
+    if (adapter.platform === 'linux') {
+        const sessionId = adapter.linuxSessionId(pid);
+        if (sessionId !== pid)
+            return { ok: false, reason: `Linux PID ${pid} is not its own session leader (session=${sessionId ?? 'unknown'})` };
+        linuxSessionId = sessionId;
+    }
+    const startAfter = adapter.startToken(pid);
+    if (!startAfter || startAfter !== startBefore)
+        return { ok: false, reason: `PID ${pid} process-start identity changed during detached-boundary verification` };
+    return {
+        ok: true,
+        identity: Object.freeze({
+            pid,
+            startToken: startAfter,
+            receiptVersion: 4,
+            processGroupId,
+            ...(linuxSessionId === undefined ? {} : { linuxSessionId }),
+        }),
+    };
+};
+export function verifyDetachedRuntime(pid, receiptFile, adapter = hostProcessAdapter) {
+    let text;
+    try {
+        text = readFileSync(receiptFile, 'utf8');
+    }
+    catch {
+        return { ok: false, reason: 'detached launch receipt is missing or unreadable' };
+    }
+    const receipt = parseDetachedLaunchReceipt(text, adapter.platform);
+    if (!receipt)
+        return { ok: false, reason: 'detached launch receipt has the wrong version or shape' };
+    if (receipt.pid !== pid)
+        return { ok: false, reason: `detached launch receipt names PID ${receipt.pid}, not ${pid}` };
+    if (receipt.processGroupId !== pid)
+        return { ok: false, reason: `detached launch receipt has wrong process group ${receipt.processGroupId} for PID ${pid}` };
+    if (adapter.platform === 'linux' && receipt.linuxSessionId !== pid)
+        return { ok: false, reason: `detached launch receipt has wrong Linux session ${receipt.linuxSessionId ?? 'missing'} for PID ${pid}` };
+    const live = observeDetachedRuntime(pid, adapter);
+    if (!live.ok)
+        return live;
+    if (live.identity.startToken !== receipt.startToken)
+        return { ok: false, reason: `PID ${pid} process-start identity does not match its detached launch receipt` };
+    return live;
+}
+// The inverse question of verifyDetachedRuntime: not "is the recorded process running right now" but "is it
+// provably GONE". The two are not complements — a missing receipt, an unreadable identity, or a PID we never
+// recorded answers neither, and a caller that treats "unproven" as "dead" would retire a live runtime it can
+// simply no longer address. Only a recorded start identity that the live PID no longer matches (including a
+// PID that is not running at all) is proof of death.
+export function detachedRuntimeIsGone(pid, receiptFile, adapter = hostProcessAdapter) {
+    let receipt;
+    try {
+        receipt = parseDetachedLaunchReceipt(readFileSync(receiptFile, 'utf8'), adapter.platform);
+    }
+    catch {
+        return false;
+    }
+    if (!receipt || receipt.pid !== pid)
+        return false;
+    return adapter.startToken(pid) !== receipt.startToken;
+}
+// A v3 scope is only a migration witness when every recorded and live Linux identity agrees. Readers never
+// call this: minting a v4 receipt belongs to the write admission path that needs the shared runtime.
+export function migrateLegacyDetachedRuntimeReceipt(pid, legacyScopeFile, receiptFile, adapter = hostProcessAdapter) {
+    if (adapter.platform !== 'linux' || verifyDetachedRuntime(pid, receiptFile, adapter).ok)
+        return false;
+    let fields;
+    try {
+        fields = readFileSync(legacyScopeFile, 'utf8').trim().split(/\s+/);
+    }
+    catch {
+        return false;
+    }
+    const observed = observeDetachedRuntime(pid, adapter);
+    if (!observed.ok || observed.identity.linuxSessionId === undefined)
+        return false;
+    const expected = ['detached-v3', String(pid), observed.identity.startToken, String(observed.identity.processGroupId), String(observed.identity.linuxSessionId)];
+    if (fields.length !== expected.length || fields.some((field, index) => field !== expected[index]))
+        return false;
+    try {
+        writeDetachedRuntimeReceipt(pid, receiptFile, adapter);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function writeDetachedRuntimeReceipt(pid, receiptFile, adapter = hostProcessAdapter) {
+    const observed = observeDetachedRuntime(pid, adapter);
+    if (!observed.ok)
+        throw new Error(`cannot prove detached shared runtime: ${observed.reason}`);
+    const receipt = {
+        version: 4,
+        kind: 'spexcode-detached-runtime',
+        pid,
+        startToken: observed.identity.startToken,
+        processGroupId: observed.identity.processGroupId,
+        ...(observed.identity.linuxSessionId === undefined ? {} : { linuxSessionId: observed.identity.linuxSessionId }),
+    };
+    mkdirSync(dirname(receiptFile), { recursive: true });
+    const tmp = `${receiptFile}.${process.pid}.${randomUUID()}.tmp`;
+    let published = false;
+    try {
+        writeFileSync(tmp, `${JSON.stringify(receipt)}\n`, { mode: 0o600 });
+        renameSync(tmp, receiptFile);
+        published = true;
+        const verified = verifyDetachedRuntime(pid, receiptFile, adapter);
+        if (!verified.ok)
+            throw new Error(`cannot verify detached shared runtime receipt: ${verified.reason}`);
+        return verified.identity;
+    }
+    catch (error) {
+        rmSync(tmp, { force: true });
+        if (published)
+            rmSync(receiptFile, { force: true });
+        throw error;
+    }
+}
+export const detachedRuntimeGenerationToken = (identity) => `detached-v4|${identity.pid}|${identity.startToken}|${identity.processGroupId}|${identity.linuxSessionId ?? '-'}`;

package/node_modules/@spexcode/spec-core/dist/project-identity.d.ts

@@ -0,0 +1,12 @@
+export type ResolvedIdentity = {
+    title: string;
+    icon: string;
+};
+export type GatewayIdentitySource = {
+    identity: ResolvedIdentity;
+    revision: string;
+};
+export declare function resolveProjectIdentity(configRoot: string, canonicalRoot?: string): ResolvedIdentity;
+export declare const hostConfigPath: () => string;
+export declare function readGatewayIdentity(): GatewayIdentitySource;
+export declare function writeGatewayIcon(icon: unknown, revision: string): GatewayIdentitySource;

package/node_modules/@spexcode/spec-core/dist/project-identity.js

@@ -0,0 +1,71 @@
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { basename, dirname, join } from 'node:path';
+import { spexcodeHome } from './project-store.js';
+import { resolvedIdentityIcon, DEFAULT_GATEWAY_ICON, DEFAULT_PROJECT_ICON, requireIdentityChoice, } from './identity-presets.js';
+const revisionOf = (raw) => createHash('sha256').update(raw === null ? 'missing' : `present\0${raw}`).digest('hex');
+function readObject(file) {
+    if (!existsSync(file))
+        return { value: {}, raw: null };
+    const raw = readFileSync(file, 'utf8');
+    let value;
+    try {
+        value = JSON.parse(raw);
+    }
+    catch (e) {
+        throw new Error(`malformed ${file}: ${e.message}`);
+    }
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw new Error(`${file} must contain one top-level JSON object`);
+    return { value: value, raw };
+}
+export function resolveProjectIdentity(configRoot, canonicalRoot = configRoot) {
+    const { value } = readObject(join(configRoot, 'spexcode.json'));
+    const dashboard = value.dashboard && typeof value.dashboard === 'object' && !Array.isArray(value.dashboard)
+        ? value.dashboard
+        : {};
+    const configuredTitle = typeof dashboard.title === 'string' ? dashboard.title.trim() : '';
+    return {
+        title: configuredTitle || basename(canonicalRoot),
+        icon: resolvedIdentityIcon(dashboard.icon, DEFAULT_PROJECT_ICON),
+    };
+}
+export const hostConfigPath = () => join(spexcodeHome(), 'config.json');
+export function readGatewayIdentity() {
+    const { value, raw } = readObject(hostConfigPath());
+    const gateway = value.gateway && typeof value.gateway === 'object' && !Array.isArray(value.gateway)
+        ? value.gateway
+        : {};
+    return {
+        identity: { title: 'Projects', icon: resolvedIdentityIcon(gateway.icon, DEFAULT_GATEWAY_ICON) },
+        revision: revisionOf(raw),
+    };
+}
+export function writeGatewayIcon(icon, revision) {
+    const canonical = requireIdentityChoice(icon);
+    const file = hostConfigPath();
+    const current = readObject(file);
+    if (revision !== revisionOf(current.raw)) {
+        const error = new Error('host config changed on disk — reload before saving');
+        error.status = 409;
+        throw error;
+    }
+    const gateway = current.value.gateway && typeof current.value.gateway === 'object' && !Array.isArray(current.value.gateway)
+        ? current.value.gateway
+        : {};
+    const next = { ...current.value, gateway: { ...gateway, icon: canonical } };
+    const raw = `${JSON.stringify(next, null, 2)}\n`;
+    mkdirSync(dirname(file), { recursive: true, mode: 0o700 });
+    const tmp = `${file}.${process.pid}.tmp`;
+    try {
+        writeFileSync(tmp, raw, { mode: 0o600 });
+        renameSync(tmp, file);
+    }
+    finally {
+        try {
+            rmSync(tmp);
+        }
+        catch { /* rename consumed it / write never created it */ }
+    }
+    return { identity: { title: 'Projects', icon: canonical }, revision: revisionOf(raw) };
+}

package/node_modules/@spexcode/spec-core/dist/project-store.d.ts

@@ -0,0 +1,3 @@
+export declare function spexcodeHome(): string;
+export declare function encodeProject(root: string): string;
+export declare function projectRuntimeRoot(commonDir: string): string;

package/node_modules/@spexcode/spec-core/dist/project-store.js

@@ -0,0 +1,14 @@
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+// One pure identity seam for every project-scoped runtime consumer. Git discovery stays with callers;
+// once they have the shared common dir, sessions, materialize, history indexes, backends, and uninstall
+// all resolve the same top-level store.
+export function spexcodeHome() {
+    return process.env.SPEXCODE_HOME || join(homedir(), '.spexcode');
+}
+export function encodeProject(root) {
+    return root.replace(/[/.]/g, '-');
+}
+export function projectRuntimeRoot(commonDir) {
+    return join(spexcodeHome(), 'projects', encodeProject(dirname(commonDir)));
+}

package/node_modules/@spexcode/spec-core/dist/resilience.d.ts

@@ -0,0 +1,2 @@
+export declare function guardWorktree<T>(dir: string, fn: () => T | Promise<T>, degraded: () => T): Promise<T | null>;
+export declare function installProcessGuards(): void;

package/node_modules/@spexcode/spec-core/dist/resilience.js

@@ -0,0 +1,40 @@
+import { existsSync } from 'node:fs';
+function describe(e) {
+    return e instanceof Error ? e.message : String(e);
+}
+// run a per-worktree DETAIL read; on a throw, branch on whether the worktree DIRECTORY still exists.
+//   dir gone   → the worktree was genuinely removed mid-read → return null so the caller omits it.
+//   dir present → a flaky detail read (ENOENT race on a sibling file, or a git index/ref lock under a
+//                 concurrent merge) → return the caller's `degraded` row so an EXISTING worktree is NEVER
+//                 dropped from the board. read-failure != non-existence.
+// `dir` is the worktree path (the existence fact). Accepts a sync OR async fn — resolveLayout's overlay
+// read is async, listSessions' row read is sync; `degraded` is a sync raw-facts fallback.
+export async function guardWorktree(dir, fn, degraded) {
+    try {
+        return await fn();
+    }
+    catch (e) {
+        if (!existsSync(dir)) {
+            console.warn(`spec-cli: worktree ${dir} gone from disk (removed mid-read), omitting: ${describe(e)}`);
+            return null;
+        }
+        console.warn(`spec-cli: worktree ${dir} detail-read failed (transient/lock); serving degraded row: ${describe(e)}`);
+        return degraded();
+    }
+}
+// the last-resort process net: log an otherwise-fatal async throw and KEEP SERVING. Registering these
+// handlers is itself what overrides Node's default "print the stack and exit" — so the backend rides out
+// a transient race it didn't anticipate instead of dropping the public port. Idempotent (guarded) so a
+// double-install in one process can't stack duplicate handlers.
+let guardsInstalled = false;
+export function installProcessGuards() {
+    if (guardsInstalled)
+        return;
+    guardsInstalled = true;
+    process.on('unhandledRejection', (reason) => {
+        console.error(`spec-cli: unhandledRejection kept the server alive (investigate): ${reason instanceof Error ? reason.stack : describe(reason)}`);
+    });
+    process.on('uncaughtException', (err) => {
+        console.error(`spec-cli: uncaughtException kept the server alive (investigate): ${err?.stack || describe(err)}`);
+    });
+}

package/node_modules/@spexcode/spec-core/dist/review/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./reviewFilters.js";
+export * from "./reviewQuery.js";
+export * from "./session.js";

package/node_modules/@spexcode/spec-core/dist/review/index.js

@@ -0,0 +1,5 @@
+// @@@ review-domain - browser/server boundary; keep this entry free of Node,
+// React, store, endpoint, and service dependencies.
+export * from './reviewFilters.js';
+export * from './reviewQuery.js';
+export * from './session.js';

package/node_modules/@spexcode/spec-core/dist/review/reviewFilters.d.ts

@@ -0,0 +1,77 @@
+export function filterReviewItems(items: any, state: any, config: any, context?: {}): {
+    state: any;
+    faceted: any;
+    shown: any;
+    sections: {
+        [k: string]: any;
+    };
+    facets: {
+        [k: string]: any;
+    };
+};
+export function issueFilterState(raw?: {}, { defaultSection }?: {
+    defaultSection?: string | undefined;
+}): {
+    q: any;
+    state: any;
+    impossible: boolean;
+    author: any;
+    store: any;
+    node: any;
+    label: any;
+    session: any;
+};
+export function issueFilterModel(items: any, raw?: {}, context?: {}): {
+    state: any;
+    faceted: any;
+    shown: any;
+    sections: {
+        [k: string]: any;
+    };
+    facets: {
+        [k: string]: any;
+    };
+};
+export function evalFilterState(raw?: {}, { defaultKind, defaultSection }?: {
+    defaultKind?: string | undefined;
+    defaultSection?: string | undefined;
+}): {
+    q: any;
+    kind: any;
+    impossible: boolean;
+    verdict: any;
+    freshness: any;
+    node: any;
+    filer: any;
+    session: any;
+    review: any;
+};
+export function evalFilterModel(items: any, raw?: {}, context?: {}): {
+    state: any;
+    faceted: any;
+    shown: any;
+    sections: {
+        [k: string]: any;
+    };
+    facets: {
+        [k: string]: any;
+    };
+};
+export function filterMenuGroups(model: any, onChange: any, keys: any): any;
+export function tokenFilterState(text: any, domain: any): {
+    q: never[];
+} | {
+    impossible: boolean;
+    q: never[];
+};
+export const EVAL_FILTER_KIND: Readonly<{
+    RESULT: "result";
+    BLIND: "blind";
+    UNMEASURED: "unmeasured";
+    DANGLING: "dangling";
+}>;
+export function evidenceList(reading: any): any;
+export function kindsOf(reading: any): string[];
+export function sectionTotal(count: any): any;
+export function reviewActorName(actor: any): any;
+export function evalReviewState(reading: any): any;