@spexcode/spec-cli 0.6.5

package/dist/pty-bridge.js

@@ -0,0 +1,404 @@
+import { execFile, spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { promisify } from 'node:util';
+import { alive, withSessionInputLock } from './sessions.js';
+const pexec = promisify(execFile);
+const TMUX_SOCK = process.env.SPEXCODE_TMUX || 'spexcode';
+const HELPER = fileURLToPath(new URL('./pty-helper.mjs', import.meta.url));
+const subscribers = new Map();
+const BSU = Buffer.from('\x1b[?2026h');
+const ESU = Buffer.from('\x1b[?2026l');
+const GEOMETRY_STABILIZATION_MS = 400;
+// A hidden but still-alive browser keeps its own client briefly so a quick return is continuous. A dead
+// socket bypasses this window and detaches immediately.
+const LINGER_MS = Number(process.env.SPEXCODE_TERM_LINGER_MS) > 0 ? Number(process.env.SPEXCODE_TERM_LINGER_MS) : 30_000;
+function subscriptionMap(id) {
+    let map = subscribers.get(id);
+    if (!map)
+        subscribers.set(id, map = new Map());
+    return map;
+}
+function currentSubscription(id, viewer) {
+    return subscribers.get(id)?.get(viewer);
+}
+function isCurrent(bridge) {
+    return currentSubscription(bridge.id, bridge.viewer)?.bridge === bridge;
+}
+function deliver(bridge, data) {
+    const subscription = currentSubscription(bridge.id, bridge.viewer);
+    if (!subscription || (!subscription.visible && !subscription.lingering))
+        return;
+    try {
+        bridge.viewer.send(data);
+    }
+    catch { /* socket close or heartbeat expiry owns removal */ }
+}
+function commitSize(bridge) {
+    const subscription = currentSubscription(bridge.id, bridge.viewer);
+    if (!subscription?.visible)
+        return;
+    try {
+        bridge.viewer.commitSize?.(bridge.cols, bridge.rows);
+    }
+    catch { /* socket close owns removal */ }
+}
+async function tmux(args) {
+    try {
+        const { stdout } = await pexec('tmux', ['-L', TMUX_SOCK, ...args]);
+        return stdout.trim();
+    }
+    catch {
+        return '';
+    }
+}
+function onHelperOutput(bridge, chunk) {
+    if (!isCurrent(bridge))
+        return;
+    if (bridge.delivery === 'stream') {
+        deliver(bridge, chunk);
+        return;
+    }
+    bridge.refreshBuf = bridge.refreshBuf.length ? Buffer.concat([bridge.refreshBuf, chunk]) : chunk;
+    releaseInitialRefresh(bridge);
+}
+function sendControl(bridge, message) {
+    try {
+        bridge.proc.stdin.write(`${JSON.stringify(message)}\n`);
+    }
+    catch { /* exit recovery owns retry */ }
+}
+function onHelperStderr(bridge, chunk) {
+    bridge.stderr += chunk.toString('utf8');
+    let newline;
+    while ((newline = bridge.stderr.indexOf('\n')) >= 0) {
+        const line = bridge.stderr.slice(0, newline);
+        bridge.stderr = bridge.stderr.slice(newline + 1);
+        const ready = line.match(/^READY (\d+)$/);
+        if (ready) {
+            bridge.ptyPid = Number(ready[1]);
+            const subscription = currentSubscription(bridge.id, bridge.viewer);
+            if (subscription)
+                subscription.startupError = undefined;
+            if (bridge.delivery === 'initial') {
+                armDeliveryBoundary(bridge);
+                queueRefresh(bridge);
+            }
+            continue;
+        }
+        const resized = line.match(/^RESIZED (\d+) (\d+)$/);
+        if (resized) {
+            if (bridge.delivery === 'initial'
+                && Number(resized[1]) === bridge.cols
+                && Number(resized[2]) === bridge.rows) {
+                queueRefresh(bridge);
+            }
+        }
+        else if (line) {
+            const failed = line.match(/^ERROR (.+)$/);
+            if (failed)
+                reportStartupError(bridge, failed[1]);
+            console.error(`[terminal helper ${bridge.id}/${bridge.ptyPid ?? 'starting'}] ${line}`);
+        }
+    }
+}
+function reportStartupError(bridge, detail) {
+    const subscription = currentSubscription(bridge.id, bridge.viewer);
+    if (!subscription || subscription.bridge !== bridge)
+        return;
+    const message = boundedStartupError(detail);
+    bridge.startupError = message;
+    if (!message || subscription.startupError === message)
+        return;
+    subscription.startupError = message;
+    deliver(bridge, Buffer.from(`\r\n[SpexCode terminal unavailable] ${message}\r\n`, 'utf8'));
+}
+function boundedStartupError(detail) {
+    return (detail instanceof Error ? detail.message : String(detail))
+        .replace(/[\x00-\x1f\x7f]+/g, ' ').trim().slice(0, 500) || 'native PTY failed to start';
+}
+function ensureBridge(id, viewer, subscription, cols, rows) {
+    if (subscription.bridge)
+        return { bridge: subscription.bridge, created: false };
+    let proc;
+    try {
+        proc = spawn(process.execPath, [HELPER, id, String(cols), String(rows)], {
+            stdio: ['pipe', 'pipe', 'pipe'],
+            env: process.env,
+        });
+    }
+    catch (error) {
+        try {
+            proc?.kill();
+        }
+        catch { /* spawn did not complete */ }
+        const detail = boundedStartupError(error);
+        if (subscription.startupError !== detail) {
+            subscription.startupError = detail;
+            try {
+                viewer.send(Buffer.from(`\r\n[SpexCode terminal unavailable] ${detail}\r\n`, 'utf8'));
+            }
+            catch { /* socket closed */ }
+        }
+        return { bridge: null, created: false };
+    }
+    const bridge = {
+        id, viewer, proc, cols, rows, stderr: '', delivery: 'initial',
+        refreshBuf: Buffer.alloc(0), refreshPending: false, refreshRunning: false,
+    };
+    subscription.bridge = bridge;
+    proc.stdout.on('data', (data) => onHelperOutput(bridge, data));
+    proc.stderr.on('data', (data) => onHelperStderr(bridge, data));
+    let reaped = false;
+    const gone = (detail) => {
+        if (reaped)
+            return;
+        reaped = true;
+        const current = currentSubscription(id, viewer);
+        if (current?.bridge !== bridge)
+            return;
+        if (!bridge.ptyPid && !bridge.startupError)
+            reportStartupError(bridge, detail || 'helper exited before native PTY startup');
+        current.bridge = undefined;
+        clearDelivery(bridge);
+        try {
+            bridge.proc.kill();
+        }
+        catch { /* already gone */ }
+        scheduleRestore(id, viewer, current);
+    };
+    proc.on('exit', (code, signal) => gone(`helper exited before native PTY startup (${signal ? `signal ${signal}` : `code ${code ?? 'unknown'}`})`));
+    proc.on('error', (error) => gone(`helper process failed: ${error.message}`));
+    return { bridge, created: true };
+}
+function cancelLinger(subscription) {
+    if (subscription.lingerTimer)
+        clearTimeout(subscription.lingerTimer);
+    subscription.lingerTimer = undefined;
+    subscription.lingering = false;
+}
+function cancelRestore(subscription) {
+    if (subscription.restoreTimer)
+        clearTimeout(subscription.restoreTimer);
+    subscription.restoreTimer = undefined;
+}
+function killBridge(subscription) {
+    cancelLinger(subscription);
+    cancelRestore(subscription);
+    const bridge = subscription.bridge;
+    if (!bridge)
+        return;
+    subscription.bridge = undefined;
+    clearDelivery(bridge);
+    try {
+        bridge.proc.stdin.end();
+    }
+    catch { /* already gone */ }
+    const kill = setTimeout(() => { try {
+        bridge.proc.kill();
+    }
+    catch { /* already gone */ } }, 250);
+    kill.unref();
+}
+function beginDelivery(bridge) {
+    if (bridge.delivery === 'stream')
+        bridge.refreshBuf = Buffer.alloc(0);
+    bridge.delivery = 'initial';
+    bridge.refreshOffset = undefined;
+    armDeliveryBoundary(bridge);
+}
+function armDeliveryBoundary(bridge) {
+    if (bridge.deliveryTimer)
+        clearTimeout(bridge.deliveryTimer);
+    bridge.deliveryTimer = setTimeout(() => finishDelivery(bridge), GEOMETRY_STABILIZATION_MS);
+    bridge.deliveryTimer.unref();
+}
+function clearDelivery(bridge) {
+    bridge.delivery = 'stream';
+    if (bridge.deliveryTimer)
+        clearTimeout(bridge.deliveryTimer);
+    bridge.deliveryTimer = undefined;
+    bridge.refreshBuf = Buffer.alloc(0);
+    bridge.refreshPending = false;
+    bridge.refreshOffset = undefined;
+}
+function completeTransactionEnd(buffer, offset) {
+    const begin = buffer.indexOf(BSU, offset);
+    const end = begin >= 0 ? buffer.indexOf(ESU, begin + BSU.length) : -1;
+    return end >= 0 ? end + ESU.length : undefined;
+}
+function releaseInitialRefresh(bridge) {
+    if (bridge.delivery !== 'initial' || bridge.refreshOffset === undefined)
+        return;
+    const end = completeTransactionEnd(bridge.refreshBuf, bridge.refreshOffset);
+    if (end === undefined)
+        return;
+    const batch = bridge.refreshBuf.subarray(0, end);
+    bridge.refreshBuf = bridge.refreshBuf.subarray(end);
+    bridge.delivery = 'quarantine';
+    commitSize(bridge);
+    if (batch.length)
+        deliver(bridge, batch);
+}
+function finishDelivery(bridge) {
+    if (bridge.delivery === 'stream' || !isCurrent(bridge))
+        return;
+    const failOpen = bridge.delivery === 'initial';
+    const batch = bridge.refreshBuf;
+    clearDelivery(bridge);
+    if (!failOpen && !batch.length)
+        return;
+    // The control commit and following binary frame are one browser render transaction, including fail-open.
+    commitSize(bridge);
+    deliver(bridge, batch);
+}
+async function refreshBridge(bridge) {
+    if (!isCurrent(bridge) || !bridge.ptyPid)
+        return false;
+    const tty = await clientTty(bridge);
+    if (!tty)
+        return false;
+    await tmux(['refresh-client', '-t', tty]);
+    return true;
+}
+function queueRefresh(bridge) {
+    if (bridge.delivery !== 'initial')
+        return;
+    bridge.refreshPending = true;
+    if (bridge.refreshRunning)
+        return;
+    bridge.refreshPending = false;
+    bridge.refreshRunning = true;
+    void refreshBridge(bridge).then((refreshed) => {
+        bridge.refreshRunning = false;
+        if (!isCurrent(bridge) || bridge.delivery !== 'initial')
+            return;
+        if (bridge.refreshPending) {
+            queueRefresh(bridge);
+            return;
+        }
+        if (!refreshed)
+            return;
+        bridge.refreshOffset = bridge.refreshBuf.length;
+        releaseInitialRefresh(bridge);
+    });
+}
+async function clientTty(bridge) {
+    if (bridge.clientTty)
+        return bridge.clientTty;
+    if (!bridge.ptyPid)
+        return undefined;
+    const clients = await tmux(['list-clients', '-t', bridge.id, '-F', '#{client_pid} #{client_tty}']);
+    for (const line of clients.split('\n')) {
+        const space = line.indexOf(' ');
+        if (space > 0 && Number(line.slice(0, space)) === bridge.ptyPid) {
+            return (bridge.clientTty = line.slice(space + 1).trim());
+        }
+    }
+    return undefined;
+}
+function resize(bridge, cols, rows) {
+    if (bridge.cols === cols && bridge.rows === rows)
+        return;
+    beginDelivery(bridge);
+    bridge.cols = cols;
+    bridge.rows = rows;
+    sendControl(bridge, { t: 'resize', cols, rows });
+}
+export function attachViewer(id, viewer) {
+    const map = subscriptionMap(id);
+    const previous = map.get(viewer);
+    if (previous)
+        killBridge(previous);
+    map.set(viewer, { visible: false, lingering: false, cols: 0, rows: 0 });
+}
+export function hideViewer(id, viewer) {
+    const subscription = currentSubscription(id, viewer);
+    if (!subscription)
+        return;
+    subscription.visible = false;
+    if (!subscription.bridge)
+        return;
+    subscription.lingering = true;
+    if (subscription.lingerTimer)
+        return;
+    subscription.lingerTimer = setTimeout(() => {
+        subscription.lingerTimer = undefined;
+        if (!subscription.visible && currentSubscription(id, viewer) === subscription)
+            killBridge(subscription);
+    }, LINGER_MS);
+    subscription.lingerTimer.unref();
+}
+export function detachViewer(id, viewer) {
+    const map = subscribers.get(id);
+    const subscription = map?.get(viewer);
+    if (!map || !subscription)
+        return;
+    // A closed/dead socket is not a hidden live tab: remove its native client now, never after linger.
+    killBridge(subscription);
+    map.delete(viewer);
+    if (map.size === 0)
+        subscribers.delete(id);
+}
+export function resizeBridge(id, viewer, colsValue, rowsValue) {
+    const cols = Math.floor(colsValue), rows = Math.floor(rowsValue);
+    if (!(cols > 0 && rows > 0))
+        return;
+    const subscription = currentSubscription(id, viewer);
+    if (!subscription)
+        return;
+    const seamless = subscription.lingering && !!subscription.bridge
+        && subscription.bridge.cols === cols && subscription.bridge.rows === rows;
+    cancelLinger(subscription);
+    subscription.visible = true;
+    subscription.cols = cols;
+    subscription.rows = rows;
+    const { bridge, created } = ensureBridge(id, viewer, subscription, cols, rows);
+    if (!bridge || created || seamless)
+        return;
+    if (bridge.cols === cols && bridge.rows === rows) {
+        beginDelivery(bridge);
+        queueRefresh(bridge);
+    }
+    else {
+        resize(bridge, cols, rows);
+    }
+}
+const MAX_INPUT_BYTES = 64 * 1024;
+export function forwardInput(id, viewer, data) {
+    const subscription = currentSubscription(id, viewer);
+    if (!subscription?.visible || !subscription.bridge || !data || Buffer.byteLength(data, 'utf8') > MAX_INPUT_BYTES)
+        return false;
+    return withSessionInputLock(id, () => {
+        sendControl(subscription.bridge, { t: 'input', data });
+        return true;
+    }) ?? false;
+}
+async function restoreBridge(id, viewer, subscription) {
+    subscription.restoreTimer = undefined;
+    if (currentSubscription(id, viewer) !== subscription || subscription.bridge || !subscription.visible || !(await alive(id)))
+        return;
+    if (!(subscription.cols > 0 && subscription.rows > 0))
+        return;
+    ensureBridge(id, viewer, subscription, subscription.cols, subscription.rows);
+}
+function scheduleRestore(id, viewer, subscription) {
+    if (currentSubscription(id, viewer) !== subscription || !subscription.visible || subscription.bridge || subscription.restoreTimer)
+        return;
+    subscription.restoreTimer = setTimeout(() => void restoreBridge(id, viewer, subscription), 750);
+    subscription.restoreTimer.unref();
+}
+let supervising = false;
+export function superviseBridges(intervalMs = 4000) {
+    if (supervising)
+        return;
+    supervising = true;
+    const tick = () => {
+        for (const [id, viewers] of subscribers) {
+            for (const [viewer, subscription] of viewers)
+                scheduleRestore(id, viewer, subscription);
+        }
+        const timer = setTimeout(tick, intervalMs);
+        timer.unref();
+    };
+    tick();
+}

package/dist/pty-helper.d.mts

@@ -0,0 +1 @@
+export {};

package/dist/pty-helper.mjs

@@ -0,0 +1,101 @@
+import * as pty from 'node-pty';
+import { execFileSync } from 'node:child_process';
+import { ensureExecutableIfPresent, nodePtySpawnHelperPath } from './pty-native-helper.mjs';
+const [id, colsArg, rowsArg] = process.argv.slice(2);
+const cols = Number(colsArg);
+const rows = Number(rowsArg);
+const socket = process.env.SPEXCODE_TMUX || 'spexcode';
+if (!id || !(cols > 0 && rows > 0)) {
+    process.stderr.write('ERROR invalid helper arguments\n');
+    process.exit(2);
+}
+// Establish the outer-terminal contract before this process owns a PTY. tmux must preserve hyperlinks and
+// wrap client updates in DEC 2026 for xterm 6; doing the setup before forkpty preserves helper isolation.
+try {
+    // The dashboard renders the pane, not tmux's client chrome. Keeping this as a tmux session option makes
+    // the requested PTY grid the pane grid too; filtering a coloured final row in xterm would corrupt real
+    // pane content. SpexCode owns these sessions, so a later foreground attach sees the same status-free pane.
+    execFileSync('tmux', ['-L', socket, 'set-option', '-t', id, 'status', 'off']);
+    // Control follows the person actually driving: `latest` sizes the window to the most recently
+    // active client, so a small screen takes the grid the moment its user interacts and sees the WHOLE
+    // pane, while an idle larger viewer letterboxes. `largest` optimized the big display's real estate
+    // but left a small concurrent viewer a cropped corner it could never take back.
+    execFileSync('tmux', ['-L', socket, 'set-window-option', '-t', id, 'window-size', 'latest']);
+    execFileSync('tmux', ['-L', socket, 'set-option', '-g', 'mouse', 'on']);
+    execFileSync('tmux', ['-L', socket, 'set-option', '-g', 'history-limit', '50000']);
+    // Wheel routing stays tmux-default: copy-mode history for a plain pane, pass-through to a
+    // mouse-owning TUI. Claude's TUI virtual-scrolls its own transcript on those reports (it lives on
+    // the alternate screen and repaints in place, so tmux history cannot substitute — an in-place
+    // renderer never scrolls lines off the top). Restore the default bindings idempotently in case an
+    // earlier release rebound them server-wide; the unbind may already be clean, so it fails quietly.
+    execFileSync('tmux', ['-L', socket, 'bind-key', '-n', 'WheelUpPane', 'if', '-F', '-t=', '#{||:#{pane_in_mode},#{mouse_any_flag}}', 'send-keys -M', 'copy-mode -et=']);
+    try {
+        execFileSync('tmux', ['-L', socket, 'unbind-key', '-n', 'WheelDownPane']);
+    }
+    catch { /* already unbound */ }
+    const features = execFileSync('tmux', ['-L', socket, 'show-options', '-gsv', 'terminal-features'], { encoding: 'utf8' });
+    const xtermFeatures = new Set(features.split('\n').filter((line) => line.startsWith('xterm*:')).flatMap((line) => line.split(':').slice(1)));
+    const missing = ['sync', 'hyperlinks'].filter((feature) => !xtermFeatures.has(feature));
+    if (missing.length) {
+        execFileSync('tmux', ['-L', socket, 'set-option', '-as', 'terminal-features', `,xterm*:${missing.join(':')}`]);
+    }
+}
+catch { /* attach below fails loudly if the tmux server/session is unavailable */ }
+let terminal;
+try {
+    ensureExecutableIfPresent(nodePtySpawnHelperPath(pty.native));
+    terminal = pty.spawn('tmux', ['-u', '-L', socket, 'attach-session', '-t', id], {
+        name: 'xterm-256color',
+        cols,
+        rows,
+        env: { ...process.env, LANG: process.env.LANG || 'en_US.UTF-8' },
+    });
+}
+catch (error) {
+    const detail = (error instanceof Error ? error.message : String(error))
+        .replace(/[\x00-\x1f\x7f]+/g, ' ').trim().slice(0, 500);
+    process.stderr.write(`ERROR ${detail || 'native PTY failed to start'}\n`);
+    process.exit(1);
+}
+terminal.onData((data) => process.stdout.write(Buffer.from(data, 'utf8')));
+terminal.onExit(({ exitCode }) => process.exit(exitCode === 0 ? 0 : 1));
+process.stderr.write(`READY ${terminal.pid}\n`);
+let input = '';
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', (chunk) => {
+    input += chunk;
+    let newline;
+    while ((newline = input.indexOf('\n')) >= 0) {
+        const line = input.slice(0, newline);
+        input = input.slice(newline + 1);
+        if (!line)
+            continue;
+        try {
+            const message = JSON.parse(line);
+            if (message?.t === 'resize' && message.cols > 0 && message.rows > 0) {
+                const nextCols = Math.floor(message.cols);
+                const nextRows = Math.floor(message.rows);
+                terminal.resize(nextCols, nextRows);
+                process.stderr.write(`RESIZED ${nextCols} ${nextRows}\n`);
+            }
+            else if (message?.t === 'input' && typeof message.data === 'string' && Buffer.byteLength(message.data, 'utf8') <= 64 * 1024) {
+                terminal.write(message.data);
+            }
+        }
+        catch { /* malformed controls cannot become terminal input */ }
+    }
+});
+let closing = false;
+function close() {
+    if (closing)
+        return;
+    closing = true;
+    try {
+        terminal.kill();
+    }
+    catch { /* already gone */ }
+    setTimeout(() => process.exit(0), 100).unref();
+}
+process.stdin.on('end', close);
+process.on('SIGTERM', close);
+process.on('SIGINT', close);

package/dist/pty-native-helper.d.mts

@@ -0,0 +1,2 @@
+export function nodePtySpawnHelperPath(nativeModule: any): string;
+export function ensureExecutableIfPresent(path: any): void;

package/dist/pty-native-helper.mjs

@@ -0,0 +1,23 @@
+import { chmodSync, statSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname, join } from 'node:path';
+const require = createRequire(import.meta.url);
+export function nodePtySpawnHelperPath(nativeModule) {
+    const nativeAddon = Object.values(require.cache).find((loaded) => loaded?.exports === nativeModule)?.filename;
+    if (!nativeAddon)
+        throw new Error('cannot locate node-pty loaded native addon');
+    return join(dirname(nativeAddon), 'spawn-helper');
+}
+export function ensureExecutableIfPresent(path) {
+    let mode;
+    try {
+        mode = statSync(path).mode & 0o777;
+    }
+    catch (error) {
+        if (error?.code === 'ENOENT')
+            return;
+        throw error;
+    }
+    if ((mode & 0o111) !== 0o111)
+        chmodSync(path, mode | 0o111);
+}

package/dist/public-graph.d.ts

@@ -0,0 +1,46 @@
+export declare const PUBLIC_GRAPH_SCHEMA: "spexcode.public-spec-graph/v1";
+export declare const PUBLIC_GRAPH_PAYLOAD_NAME: "public-graph.json";
+export type PublicGraphNode = Readonly<{
+    id: string;
+    parent: string | null;
+    path: string;
+    title: string;
+    status: string;
+    fmStatus: string | null;
+    hue: number;
+    desc: string;
+    code: readonly string[];
+    related: readonly string[];
+    version: number;
+    lastEdited: string | null;
+    drift: number;
+    driftFiles: readonly {
+        file: string;
+        behind: number;
+    }[];
+}>;
+export type PublicGraph = Readonly<{
+    schema: typeof PUBLIC_GRAPH_SCHEMA;
+    payloadName: typeof PUBLIC_GRAPH_PAYLOAD_NAME;
+    revision: string;
+    sourceRoot: string;
+    identity: Readonly<{
+        title: string;
+        icon: string;
+    }>;
+    nodes: readonly PublicGraphNode[];
+}>;
+export type PublicGraphDocument = Readonly<{
+    schema: 'spexcode.public-spec-document/v1';
+    revision: string;
+    id: string;
+    body: string;
+    parts: unknown;
+}>;
+export type PublicGraphArtifact = Readonly<{
+    graph: PublicGraph;
+    documents: readonly PublicGraphDocument[];
+}>;
+export declare function buildPublicGraphArtifact(): Promise<PublicGraphArtifact>;
+export declare function buildPublicGraph(): Promise<PublicGraph>;
+export declare function publicGraphJson(graph: PublicGraph): string;

package/dist/public-graph.js

@@ -0,0 +1,56 @@
+import { loadSpecs, repoRoot, resolveProjectIdentity, gitA } from '@spexcode/spec-core';
+export const PUBLIC_GRAPH_SCHEMA = 'spexcode.public-spec-graph/v1';
+export const PUBLIC_GRAPH_PAYLOAD_NAME = 'public-graph.json';
+function stableNode(node) {
+    return {
+        id: node.id,
+        parent: node.parent,
+        path: node.path,
+        title: node.title,
+        status: node.status,
+        fmStatus: node.fmStatus,
+        hue: node.hue,
+        desc: node.desc,
+        code: [...node.code],
+        related: [...node.related],
+        version: node.version,
+        lastEdited: node.lastEdited,
+        drift: node.drift,
+        driftFiles: node.driftFiles.map((entry) => ({ file: entry.file, behind: entry.behind })),
+    };
+}
+export async function buildPublicGraphArtifact() {
+    const root = repoRoot();
+    const [nodes, revision] = await Promise.all([
+        loadSpecs(root),
+        gitA(['-C', root, 'rev-parse', 'HEAD']).then((value) => value.trim()),
+    ]);
+    if (!revision)
+        throw new Error('public graph cannot be published without a Git revision');
+    const identity = resolveProjectIdentity(root, root);
+    const graph = Object.freeze({
+        schema: PUBLIC_GRAPH_SCHEMA,
+        payloadName: PUBLIC_GRAPH_PAYLOAD_NAME,
+        revision,
+        // A public artifact must be relocatable and must not disclose its producer's checkout layout.
+        sourceRoot: '.',
+        identity: Object.freeze({ title: identity.title, icon: identity.icon }),
+        nodes: Object.freeze(nodes.map(stableNode).sort((a, b) => a.path.localeCompare(b.path))),
+    });
+    const documents = Object.freeze(nodes
+        .map((node) => Object.freeze({
+        schema: 'spexcode.public-spec-document/v1',
+        revision,
+        id: node.id,
+        body: node.body,
+        parts: node.parts,
+    }))
+        .sort((a, b) => a.id.localeCompare(b.id)));
+    return Object.freeze({ graph, documents });
+}
+export async function buildPublicGraph() {
+    return (await buildPublicGraphArtifact()).graph;
+}
+export function publicGraphJson(graph) {
+    return `${JSON.stringify(graph, null, 2)}\n`;
+}

package/dist/ranker.d.ts

@@ -0,0 +1,15 @@
+export declare function terms(query: string): string[];
+export type RankInput<T> = {
+    ref: T;
+    name: string;
+    desc: string;
+    body: string;
+};
+export type Ranked<T> = {
+    ref: T;
+    score: number;
+    snippet: string;
+};
+export declare function rankDocs<T>(query: string, inputs: RankInput<T>[], opts?: {
+    limit?: number;
+}): Ranked<T>[];