spexcode 0.6.1 → 0.6.5

package/node_modules/@spexcode/spec-cli/dist/supervise.js

@@ -0,0 +1,308 @@
+// SO_REUSEPORT is ENOTSUP on macOS/Node, so the supervisor owns the public port as a raw-TCP proxy and
+// runs the Hono server as a child on a private port (raw piping carries WS upgrades too).
+import net from 'node:net';
+import http from 'node:http';
+import { randomUUID } from 'node:crypto';
+import { spawn, spawnSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { stat, readdir } from 'node:fs/promises';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+import { installProcessGuards } from '@spexcode/spec-core';
+import { listenOrExit } from './listen.js';
+import { resolvePublicConfig, startGateway, resolveDistDir } from './gateway.js';
+import { publishEndpoint, dropOwnEndpoint } from './host.js';
+import { repoRoot as servedRepoRoot } from '@spexcode/spec-core';
+import { resolveProjectIdentity } from '@spexcode/spec-core';
+import { startResourceMonitor } from './host-resources.js';
+import { registerBackendInstance, unregisterBackendInstance } from './runtime-ownership.js';
+import { sessionIdentityEnvVars } from './harness.js';
+import { serverEntrypointArgs } from './tsx-bin.js';
+// the supervisor OWNS the public port, so it must outlive any transient throw: an uncaught error here is
+// logged and survived, never an exit that closes the port (and the tmux session) and takes the frontend down.
+installProcessGuards();
+const here = dirname(fileURLToPath(import.meta.url));
+const packageRoot = join(here, '..');
+const sourceRoot = join(packageRoot, 'src');
+const workspaceRoot = existsSync(sourceRoot) ? join(packageRoot, '..') : null;
+const entryArgs = serverEntrypointArgs(packageRoot, here);
+const publicPort = Number(process.env.PORT || 8787);
+const projectRoot = servedRepoRoot(); // the actual git tree whose source/spec/config the child serves
+// @@@ public mode ([[public-mode]]) - with `spex serve --public`, the supervisor is NOT the internet face:
+// the gateway is. The raw-TCP proxy retreats to a loopback internal port (the trusted boundary local agents
+// reach) and the password-gated TLS gateway takes the public port, proxying /api + WS back to that loopback
+// port. Off → unchanged: the proxy itself owns the public port and SPEXCODE_API_URL points there.
+const publicCfg = resolvePublicConfig(projectRoot);
+// the port the raw-TCP proxy actually binds: a private loopback port in public mode, the public port otherwise.
+const proxyPort = publicCfg ? await freePort() : publicPort;
+// what launched agents inherit as their `spex` endpoint — ALWAYS the loopback proxy, so local agents never
+// meet the password gate (loopback is the trust boundary). Equals the public port when public mode is off.
+const childApiBase = `http://127.0.0.1:${proxyPort}`;
+// An installed package only has compiled JavaScript. In a source workspace keep the development loop honest:
+// observe the source closure, compile it, then make the supervisor's normal zero-downtime swap. A source edit
+// must never cause a restart that still runs the old dist.
+const watchRoots = workspaceRoot
+    ? [sourceRoot, join(workspaceRoot, 'spec-forge', 'src'), join(workspaceRoot, 'spec-eval', 'src'), join(workspaceRoot, 'packages', 'spec-core', 'src')]
+    : [here];
+function buildWorkspace() {
+    if (!workspaceRoot)
+        return true;
+    console.log('[supervisor] building workspace artifacts');
+    const result = spawnSync('npm', ['run', 'build'], { cwd: workspaceRoot, stdio: 'inherit' });
+    if (result.status === 0)
+        return true;
+    console.error('[supervisor] workspace build failed — keeping current backend');
+    return false;
+}
+// @@@ instance identity - one id for this serve's whole lifetime, minted at supervisor start and handed to
+// every child via env, so the endpoint record and the live backend answer with the SAME identity across
+// zero-downtime reloads. The host gateway ([[host-gateway]]) validates a record by comparing this id (and the
+// served root) against the live /api/instance answer — a recycled port serving a DIFFERENT project or a
+// different serve generation fails the match and is treated as offline, never proxied to.
+const instanceId = randomUUID();
+// A backend is a project control plane, never the session that happened to invoke `spex serve`. Strip every
+// adapter identity before any hot child is spawned; otherwise all backend work is falsely charged to that
+// caller long after its session ends.
+for (const key of sessionIdentityEnvVars())
+    delete process.env[key];
+process.env.SPEXCODE_PROJECT_ROOT = projectRoot;
+process.env.SPEXCODE_INSTANCE_ID = instanceId;
+registerBackendInstance(instanceId, process.pid, projectRoot);
+let current = null; // which internal port new proxy connections forward to
+let reloading = false; // single-flight guard for reload()
+let pending = false; // a code change arrived mid-reload → reload again when done
+// grab an ephemeral port by binding :0, then release it for the child to claim (negligible rebind race).
+function freePort() {
+    return new Promise((res, rej) => {
+        const s = net.createServer();
+        s.once('error', rej);
+        s.listen(0, '127.0.0.1', () => { const p = s.address().port; s.close(() => res(p)); });
+    });
+}
+// poll GET /health until 200; ~15s budget covers a cold Node + Hono start. False → keep old.
+function waitHealthy(port, tries = 150) {
+    return new Promise((resolve) => {
+        const retry = (left) => { if (left <= 1)
+            resolve(false);
+        else
+            setTimeout(() => attempt(left - 1), 100); };
+        const attempt = (left) => {
+            const req = http.get({ host: '127.0.0.1', port, path: '/health', timeout: 1000 }, (r) => {
+                r.resume();
+                if (r.statusCode === 200)
+                    resolve(true);
+                else
+                    retry(left);
+            });
+            req.on('error', () => retry(left));
+            req.on('timeout', () => { req.destroy(); retry(left); });
+        };
+        attempt(tries);
+    });
+}
+// boot a fresh backend child on a free internal port and wait until it's serving.
+async function boot() {
+    const port = await freePort();
+    // PORT pins the child's PRIVATE bind port; SPEXCODE_API_URL pins everything the child SPAWNS (launched
+    // sessions + their hooks) at the PUBLIC port, so a launched agent's own `spex` reaches the stable proxy
+    // and never inherits this ephemeral, soon-retired port. ALWAYS childApiBase, never the ambient
+    // process.env.SPEXCODE_API_URL: the env this serve itself inherited may carry ANOTHER project's backend
+    // (the exact misroute [[remote-client]]'s ladder exists to kill), and a worker's env is its routing
+    // LIFELINE — it must be a deterministic backend-injected fact, not an inheritance gamble.
+    const child = spawn(process.execPath, entryArgs, { stdio: 'inherit', env: { ...process.env, PORT: String(port), SPEXCODE_API_URL: childApiBase, SPEXCODE_INSTANCE_ID: instanceId } });
+    // if the ACTIVE backend dies unexpectedly (crash, OOM), restart it so the public port keeps serving.
+    // Planned retirement sets current to the NEW child first, so the old child's exit fails this identity
+    // check and is ignored. boot()'s ~5s health budget rate-limits any crash loop.
+    child.on('exit', (code, sig) => {
+        if (current?.child === child) {
+            console.error(`[supervisor] active backend exited (${code ?? sig}) — restarting`);
+            current = null;
+            void reload('crash');
+        }
+    });
+    if (await waitHealthy(port))
+        return { port, child };
+    try {
+        child.kill('SIGKILL');
+    }
+    catch { /* already gone */ }
+    return null;
+}
+// boot → health-gate → atomic flip → drain old. The flip is a single assignment; the old child is killed
+// only after a drain delay, so a connection mid-flip is never refused.
+async function reload(reason) {
+    if (reloading) {
+        pending = true;
+        return;
+    }
+    reloading = true;
+    try {
+        do {
+            pending = false;
+            if (!buildWorkspace())
+                break;
+            const next = await boot();
+            if (!next) {
+                console.error(`[supervisor] new backend failed health check (${reason}) — keeping current`);
+                break;
+            }
+            const old = current;
+            current = next; // atomic flip: new connections now route to `next`
+            console.log(`[supervisor] reloaded (${reason}) → backend :${next.port}`);
+            if (old)
+                setTimeout(() => { try {
+                    old.child.kill('SIGTERM');
+                }
+                catch { /* already gone */ } }, 500);
+        } while (pending);
+    }
+    finally {
+        reloading = false;
+    }
+}
+// the public port: a raw byte pipe to the current backend. Works for HTTP and WS upgrades alike.
+// @@@ connection reaping ([[spec-cli]]) - a raw TCP proxy must tear down the PAIR when EITHER end goes, or it
+// leaks the still-open half. The wedge that started the mass-restore incident was exactly this: every
+// client-side timeout-kill left the client's UPSTREAM socket half-open to the child (the old handler bailed
+// only on `error`, so a clean FIN / a silent drop never reaped the upstream) — 135 leaked conns piled on the
+// child and it looked dead. So a close on either side destroys BOTH (idempotent). The abandoned-but-silent
+// case (no FIN/RST ever arrives) is reaped from the CHILD instead — its socket-level reaper (reaper.ts)
+// destroys an idle/stalled socket, whose close then propagates here — so an active WS/SSE (not idle
+// keep-alive) is never mistaken for abandoned and cut.
+const proxy = net.createServer((client) => {
+    const target = current;
+    if (!target) {
+        client.destroy();
+        return;
+    }
+    const up = net.connect(target.port, '127.0.0.1');
+    client.setNoDelay(true);
+    up.setNoDelay(true); // proxy a request promptly — don't let Nagle add latency
+    const bail = () => { client.destroy(); up.destroy(); };
+    client.on('error', bail);
+    up.on('error', bail);
+    client.once('close', () => up.destroy()); // client abandoned → reap its upstream (THE leak that wedged :8787); nothing left to flush to a gone client
+    // upstream gone → drop the client half, but ONLY force it when the close was ABNORMAL: on a normal FIN,
+    // `up.pipe(client)` has already called `client.end()` (writableEnded), so let the client flush the last of a
+    // large response (e.g. /api/graph) rather than truncate it with a destroy; a crash/half-open close (no prior
+    // end) still gets reaped.
+    up.once('close', () => { if (!client.writableEnded)
+        client.destroy(); });
+    client.pipe(up);
+    up.pipe(client);
+});
+// @@@ endpoint record - this project's live backend endpoint, published into the per-project runtime tier
+// (~/.spexcode/projects/<enc>/backend.json) only AFTER the public bind succeeds. It's what lets a bare
+// `spex` run from this project's tree find ITS OWN backend instead of an env URL inherited from another
+// project's ([[remote-client]]'s resolution ladder), and what the host gateway ([[host-gateway]]) reconciles
+// its project list from. The write is ATOMIC (tmp + rename) and carries the serve's actual git toplevel +
+// resolved identity — so a reader can VALIDATE the record against the live /api/instance answer,
+// never just trust a URL. Readers health-probe before trusting, so a crashed serve leaves at worst a dead
+// record that is ignored — never followed. The recorded URL is the LOOPBACK face local agents reach (equals
+// the public port when public mode is off), never the password-gated gateway. A linked worktree therefore
+// gets its own encoded slot and can never overwrite the main checkout's endpoint.
+function recordEndpoint(url) {
+    try {
+        publishEndpoint({
+            version: 2,
+            url,
+            pid: process.pid,
+            instanceId,
+            root: projectRoot,
+            identity: resolveProjectIdentity(projectRoot, projectRoot),
+            startedAt: new Date().toISOString(),
+        });
+    }
+    catch (e) {
+        console.error(`[supervisor] could not record the backend endpoint (${e.message}) — cwd-based \`spex\` discovery won't find this backend`);
+    }
+}
+// best-effort removal on a clean stop, only if the record is OURS — matched by instanceId, so a newer serve
+// that already overwrote the record (or another project's) is never deleted by a retiring one.
+function dropEndpoint() {
+    try {
+        dropOwnEndpoint(instanceId, projectRoot);
+    }
+    catch { /* not ours / already gone */ }
+}
+const shutdown = () => { dropEndpoint(); unregisterBackendInstance(instanceId); try {
+    current?.child.kill('SIGTERM');
+}
+catch { /* */ } process.exit(0); };
+process.on('SIGINT', shutdown);
+process.on('SIGTERM', shutdown);
+const first = await boot();
+if (!first) {
+    console.error('[supervisor] initial backend failed to start');
+    process.exit(1);
+}
+current = first;
+// reap the booted child if a port bind fails, so a "can't own my port → exit" never leaves a zombie child.
+// SIGTERM lets the direct Node child release its backend port before the supervisor exits.
+const reapChild = () => { unregisterBackendInstance(instanceId); try {
+    current?.child.kill('SIGTERM');
+}
+catch { /* already gone */ } };
+if (publicCfg) {
+    // public mode: the raw proxy stays on loopback; the password-gated gateway owns the public port.
+    const distDir = resolveDistDir();
+    listenOrExit(proxy, proxyPort, { host: '127.0.0.1', label: 'supervisor (loopback proxy)', cleanup: reapChild, onListen: () => { recordEndpoint(childApiBase); console.log(`spec-cli supervisor on loopback :${proxyPort} (zero-downtime reloads, backend :${first.port})`); } });
+    startGateway({ publicPort, upstreamPort: proxyPort, password: publicCfg.password, tls: publicCfg.tls, distDir, onBindFail: reapChild });
+}
+else {
+    listenOrExit(proxy, publicPort, { label: 'supervisor', cleanup: reapChild, onListen: () => { recordEndpoint(childApiBase); console.log(`spec-cli supervisor serving on http://localhost:${publicPort} (zero-downtime reloads, backend :${first.port})`); } });
+}
+startResourceMonitor();
+// Watch the source closure in a workspace and the emitted directory in an installed package. Debounce a
+// burst of writes (a merge touching several files across packages) into one rebuild and reload. A root that
+// can't be watched (a package absent in some checkout) is logged and skipped — the supervisor owns the
+// public port and must never die over a missing watch.
+// fs.watch — even recursive — is NOT reliable for a long-lived supervisor: its inotify watches are silently
+// dropped when a watched dir is rewritten (a git merge, a `materialize`) and NEVER re-established, so reloads
+// quietly stop (observed: the watcher fired a few times then went deaf for hours). A cheap mtime poll can't go
+// deaf: every 2s, take the newest .ts/.js/.json mtime across the trees; a jump triggers the debounced reload
+// (a burst of writes still lands as one). Polling a few small src trees is negligible cost.
+let timer;
+const newestMtime = async (dir) => {
+    let max = 0;
+    let entries;
+    try {
+        entries = await readdir(dir, { withFileTypes: true });
+    }
+    catch {
+        return 0;
+    } // a tree absent in some checkout → skip
+    for (const e of entries) {
+        if (e.isDirectory()) {
+            if (e.name !== 'node_modules')
+                max = Math.max(max, await newestMtime(join(dir, e.name)));
+        }
+        else if (/\.(ts|js|mjs|json)$/.test(e.name)) {
+            try {
+                max = Math.max(max, (await stat(join(dir, e.name))).mtimeMs);
+            }
+            catch { /* raced unlink */ }
+        }
+    }
+    return max;
+};
+const scanMtime = async () => {
+    let m = 0;
+    for (const root of watchRoots)
+        m = Math.max(m, await newestMtime(root));
+    return m;
+};
+let lastMtime = await scanMtime(); // baseline at boot — only a LATER change reloads
+let scanning = false;
+setInterval(() => {
+    if (scanning)
+        return;
+    scanning = true;
+    void scanMtime().then((m) => {
+        if (m > lastMtime) {
+            lastMtime = m;
+            clearTimeout(timer);
+            timer = setTimeout(() => void reload('code change'), 150);
+        }
+    }).finally(() => { scanning = false; });
+}, 2000).unref();

package/node_modules/@spexcode/spec-cli/dist/tree.d.ts

@@ -0,0 +1,25 @@
+export type TreeNode = {
+    id: string;
+    parent: string | null;
+    title: string;
+    status: string;
+    version?: number;
+    drift?: number;
+    ghost?: boolean;
+    reviewSummary?: {
+        issues?: {
+            open: number;
+        };
+        evals?: {
+            stalePass: number;
+            staleFail: number;
+        };
+    };
+};
+export type TreeOpts = {
+    node?: string;
+    depth?: number;
+    color?: boolean;
+};
+export declare function renderTree(nodes: TreeNode[], opts?: TreeOpts): string;
+export declare function treeJson(nodes: TreeNode[], opts?: TreeOpts): object[];

package/node_modules/@spexcode/spec-cli/dist/tree.js

@@ -0,0 +1,98 @@
+// @@@ spex graph - the CLI's human-readable graph view: the same assembled board the dashboard's
+// tidy-tree renders, as an indented terminal tree. Pure presentation over buildBoard()'s nodes —
+// no read path of its own; status colours and badge semantics mirror the dashboard (drift /
+// stale-eval / open-issues counts). Governed by the spex-tree spec node.
+// dashboard status palette mapped onto ANSI: merged=green, active=cyan (live/in-flight, distinct
+// from the warning yellow), drift=yellow (the dashboard's warning colour), pending=muted grey.
+const STATUS_ANSI = { merged: '32', active: '36', drift: '33', pending: '90' };
+// stale-eval count: declared scenarios whose LATEST reading exists but is no longer fresh.
+// board `evals` is already latest-per-scenario, so this is a straight filter — the same freshness
+// axis the dashboard's grey ✓/✗ badges read (score.jsx readingScore).
+function staleYatsu(n) {
+    const summary = n.reviewSummary?.evals;
+    return summary ? summary.stalePass + summary.staleFail : 0;
+}
+function childrenIndex(nodes) {
+    const byParent = new Map();
+    for (const n of nodes) {
+        const list = byParent.get(n.parent) ?? [];
+        list.push(n);
+        byParent.set(n.parent, list);
+    }
+    return byParent;
+}
+// resolve the display roots: --node picks one subtree; default is the forest of parentless nodes
+// (a node whose parent id isn't on the board — a ghost mid-add, say — surfaces as a root rather
+// than vanishing). Unknown --node throws (fail loud, caller prints + exits 2), never an empty tree.
+function roots(nodes, nodeId) {
+    if (nodeId) {
+        const hit = nodes.find((n) => n.id === nodeId);
+        if (!hit)
+            throw new Error(`no spec node "${nodeId}" — spex graph lists every id; spex spec search <topic> finds one by intent`);
+        return [hit];
+    }
+    const ids = new Set(nodes.map((n) => n.id));
+    return nodes.filter((n) => n.parent === null || !ids.has(n.parent));
+}
+export function renderTree(nodes, opts = {}) {
+    const color = opts.color ?? false;
+    const c = (code, t) => (color ? `\x1b[${code}m${t}\x1b[0m` : t);
+    const byParent = childrenIndex(nodes);
+    const lines = [];
+    const badges = (n) => {
+        const parts = [];
+        if (n.ghost)
+            parts.push(c('90', 'ghost'));
+        if (n.drift)
+            parts.push(c('33', `drift:${n.drift}`));
+        const stale = staleYatsu(n);
+        if (stale)
+            parts.push(c('90', `stale:${stale}`));
+        if (n.reviewSummary?.issues?.open)
+            parts.push(c('31', `issues:${n.reviewSummary.issues.open}`));
+        return parts.length ? '  ' + parts.join(' ') : '';
+    };
+    const line = (n, prefix, branch) => {
+        const code = STATUS_ANSI[n.status] ?? '0';
+        // base state is invisible: merged (~80% of nodes) is the healthy ground state, already carried by
+        // the dot's colour — only deviations get a text label. Without colour the word IS the signal, so
+        // every status (merged included) prints in plain-text mode.
+        const label = color && n.status === 'merged' ? '' : ' ' + c(code, `[${n.status}]`);
+        const title = n.title && n.title !== n.id ? ' ' + c('90', '· ' + n.title) : '';
+        lines.push(`${prefix}${branch}${c(code, '●')} ${n.id}${label}${title}${badges(n)}`);
+    };
+    const walk = (n, prefix, branch, childPrefix, depth) => {
+        line(n, prefix, branch);
+        const kids = byParent.get(n.id) ?? [];
+        if (!kids.length)
+            return;
+        if (opts.depth !== undefined && depth >= opts.depth) {
+            lines.push(`${childPrefix}${c('90', `└─ … ${kids.length} more (raise --depth)`)}`);
+            return;
+        }
+        kids.forEach((k, i) => {
+            const last = i === kids.length - 1;
+            walk(k, childPrefix, last ? '└─ ' : '├─ ', childPrefix + (last ? '   ' : '│  '), depth + 1);
+        });
+    };
+    for (const r of roots(nodes, opts.node))
+        walk(r, '', '', '', 0);
+    return lines.join('\n');
+}
+// the machine exit: the same filtered subtree as NESTED objects, badge counts precomputed — a
+// shaped view, not a replacement for `spex graph --json` (which stays the full flat payload). Pruned
+// children degrade to their ids, so --depth still tells the machine what exists below the cut.
+export function treeJson(nodes, opts = {}) {
+    const byParent = childrenIndex(nodes);
+    const shape = (n, depth) => {
+        const kids = byParent.get(n.id) ?? [];
+        const pruned = opts.depth !== undefined && depth >= opts.depth;
+        return {
+            id: n.id, title: n.title, status: n.status, version: n.version ?? 0,
+            drift: n.drift ?? 0, staleYatsu: staleYatsu(n), openIssues: n.reviewSummary?.issues?.open ?? 0,
+            ...(n.ghost ? { ghost: true } : {}),
+            children: pruned ? kids.map((k) => k.id) : kids.map((k) => shape(k, depth + 1)),
+        };
+    };
+    return roots(nodes, opts.node).map((r) => shape(r, 0));
+}

package/node_modules/@spexcode/spec-cli/dist/tsx-bin.d.ts

@@ -0,0 +1,3 @@
+export declare function tsxBin(pkgDir: string): string;
+export declare function cliEntrypointArgs(pkgDir: string, callerDir: string): string[];
+export declare function serverEntrypointArgs(pkgDir: string, callerDir: string): string[];

package/node_modules/@spexcode/spec-cli/dist/tsx-bin.js

@@ -0,0 +1,41 @@
+import { createRequire } from 'node:module';
+import { dirname, join, resolve } from 'node:path';
+// @@@ tsxBin - tsx's JS ENTRY (dist/cli.mjs), dev-or-published, run through `node` by the caller
+// (`spawn(process.execPath, [tsxBin(pkgDir), entry, …])`). In the dev monorepo tsx sits in
+// spec-cli/node_modules; in an installed `spexcode` package npm may hoist it to the consumer's node_modules
+// — Node's own package resolver from spec-cli covers dev, global, and project-local installs in one rule.
+// We resolve the .mjs entry rather than the `.bin/tsx` shim on purpose: the shim is an unspawnable sh
+// script on Windows, so `node dist/cli.mjs` (identical to the shim on POSIX) is the one cross-platform form.
+// `pkgDir` is the spec-cli directory.
+export function tsxBin(pkgDir) {
+    try {
+        const req = createRequire(join(pkgDir, 'package.json'));
+        return join(dirname(req.resolve('tsx/package.json')), 'dist', 'cli.mjs');
+    }
+    catch {
+        throw new Error(`tsx runtime not found from ${pkgDir} — run \`npm install\` in the SpexCode package`);
+    }
+}
+function tsxLoader(pkgDir) {
+    try {
+        return createRequire(join(pkgDir, 'package.json')).resolve('tsx/esm');
+    }
+    catch {
+        throw new Error(`tsx runtime not found from ${pkgDir} — run \`npm install\` in the SpexCode package`);
+    }
+}
+// A direct source invocation is a development/test contract. A compiled launcher in the same workspace
+// must still execute dist so an installed release never accidentally reintroduces a tsx requirement.
+function sourceInvocation(pkgDir, callerDir) {
+    return resolve(callerDir) === join(resolve(pkgDir), 'src');
+}
+export function cliEntrypointArgs(pkgDir, callerDir) {
+    return sourceInvocation(pkgDir, callerDir)
+        ? ['--import', tsxLoader(pkgDir), join(pkgDir, 'src', 'cli.ts')]
+        : [join(pkgDir, 'dist', 'cli.js')];
+}
+export function serverEntrypointArgs(pkgDir, callerDir) {
+    return sourceInvocation(pkgDir, callerDir)
+        ? ['--import', tsxLoader(pkgDir), join(pkgDir, 'src', 'index.ts')]
+        : [join(pkgDir, 'dist', 'index.js')];
+}

package/node_modules/@spexcode/spec-cli/dist/uninstall.d.ts

@@ -0,0 +1,3 @@
+export declare function uninstall(targetArg: string | undefined, opts?: {
+    hooks?: boolean;
+}): void;

package/node_modules/@spexcode/spec-cli/dist/uninstall.js

@@ -0,0 +1,177 @@
+import { existsSync, readFileSync, readdirSync, rmSync } from 'node:fs';
+import { basename, join, resolve, relative } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { execFileSync } from 'node:child_process';
+import { HARNESSES } from './harness.js';
+import { runtimeRoot, readConfig, mainCheckout } from '@spexcode/spec-core';
+import { resolveHarnessTargets } from './harness-select.js';
+import { loadSkillConfig, loadAgentConfig } from '@spexcode/spec-core';
+import { dematerialize } from './materialize.js';
+import { gitBinary } from '@spexcode/spec-core';
+// the standard plugin-host folders a host agent scans (in addition to any named in spexcode.json's `harnesses`).
+const DEFAULT_PLUGIN_HOSTS = ['.claude', '.codex', '.adopter-a'];
+// Init and uninstall share one ownership source for generated git hooks: the shipped canonical templates.
+// Exact bytes prove the destination is still our derivative; any user edit withdraws that ownership.
+const HOOK_TEMPLATES = fileURLToPath(new URL('../templates/hooks', import.meta.url));
+// is this dir a SpexCode plugin bundle? Either its folder name is the identity stamp, or its
+// `.claude-plugin/plugin.json` declares `name: spexcode`. Read-gated so a user's other plugin is never touched.
+function isSpexcodeBundle(dir) {
+    if (basename(dir) === 'spexcode')
+        return true;
+    const manifest = join(dir, '.claude-plugin', 'plugin.json');
+    if (!existsSync(manifest))
+        return false;
+    try {
+        return JSON.parse(readFileSync(manifest, 'utf8')).name === 'spexcode';
+    }
+    catch {
+        return false;
+    }
+}
+// sweep any spexcode-stamped plugin bundle (`<host>/plugins/spexcode`, or a `.claude-plugin/plugin.json` named
+// spexcode) under the project's plugin-host folders. The bundle EMITTER is a later node, so a native-only install
+// has nothing here today; the sweep keeps uninstall a true inverse once it lands (and cleans a hand-dropped one).
+function sweepPluginBundles(proj, hosts) {
+    const removed = [];
+    for (const host of new Set(hosts)) {
+        const pluginsDir = join(proj, host, 'plugins');
+        if (!existsSync(pluginsDir))
+            continue;
+        for (const e of readdirSync(pluginsDir, { withFileTypes: true })) {
+            if (!e.isDirectory())
+                continue;
+            const dir = join(pluginsDir, e.name);
+            if (isSpexcodeBundle(dir)) {
+                rmSync(dir, { recursive: true, force: true });
+                removed.push(relative(proj, dir));
+            }
+        }
+    }
+    return removed;
+}
+// Arbitrary plugin landing folders are the one materialized path set that cannot be reconstructed from stamps
+// alone, so materialize records them as data. Read every current per-tree ledger plus the legacy project-global
+// ledger before uninstall removes the store; a stale bundle remains removable even after current config stopped
+// naming its former host folder.
+function pluginLedgerHosts(store) {
+    const ledgers = [join(store, 'plugin-folders')];
+    const trees = join(store, 'trees');
+    if (existsSync(trees)) {
+        for (const e of readdirSync(trees, { withFileTypes: true })) {
+            if (e.isDirectory())
+                ledgers.push(join(trees, e.name, 'plugin-folders'));
+        }
+    }
+    const hosts = [];
+    for (const ledger of ledgers) {
+        if (!existsSync(ledger))
+            continue;
+        hosts.push(...readFileSync(ledger, 'utf8').split('\n').map((line) => line.trim()).filter(Boolean));
+    }
+    return hosts;
+}
+// resolve the repo's shared git hooks dir (the common dir's hooks/), or null when <dir> isn't a git repo.
+function hooksDir(proj) {
+    try {
+        const common = execFileSync(gitBinary(process.env), ['-C', proj, 'rev-parse', '--path-format=absolute', '--git-common-dir'], {
+            encoding: 'utf8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+        }).trim();
+        return join(common, 'hooks');
+    }
+    catch {
+        return null;
+    }
+}
+// Remove only byte-identical products of the canonical hook templates. Enumerating the same template directory
+// init copies keeps every generated hook covered without a second name list; modified and unrelated hooks survive.
+function removeHooks(proj) {
+    const dir = hooksDir(proj);
+    if (!dir)
+        return [];
+    const removed = [];
+    for (const e of readdirSync(HOOK_TEMPLATES, { withFileTypes: true })) {
+        if (!e.isFile())
+            continue;
+        const hook = join(dir, e.name);
+        if (!existsSync(hook) || !readFileSync(hook).equals(readFileSync(join(HOOK_TEMPLATES, e.name))))
+            continue;
+        rmSync(hook, { force: true });
+        removed.push(e.name);
+    }
+    return removed;
+}
+export function uninstall(targetArg, opts = {}) {
+    const proj = resolve(targetArg ?? process.cwd());
+    console.log(`spex uninstall → ${proj}`);
+    // cwd = the project so the .plugins loaders read THIS tree's surface nodes (the live skill/agent names tell
+    // each adapter's clean() exactly which name-scoped on-demand files were its to remove).
+    const prevCwd = process.cwd();
+    let arts = { skills: [], agents: [] };
+    try {
+        process.chdir(proj);
+        arts = { skills: loadSkillConfig().map((s) => s.name), agents: loadAgentConfig().map((a) => a.name) };
+    }
+    catch {
+        // no readable .plugins (already partly torn down, or never adopted) — clean still strips the harness wiring.
+    }
+    finally {
+        process.chdir(prevCwd);
+    }
+    // 1+2. materialize(∅): every harness's artifacts (contract block, shim, trust, skills/agents), the managed
+    //    .gitignore + info/exclude blocks, any legacy skip-worktree bit, and the content filter — the SAME
+    //    erase phase every materialize runs, asserted against the empty policy. One inverse, never a parallel one.
+    dematerialize(proj, arts);
+    // 3. Locate the global per-project store and recover every current/legacy plugin landing folder from its
+    //    ledgers BEFORE deleting it. The store is the runtime tier, not the user's tracked intent asset.
+    let store = null;
+    let ledgerHosts = [];
+    try {
+        store = runtimeRoot(proj);
+    }
+    catch {
+        store = null;
+    }
+    if (store)
+        ledgerHosts = pluginLedgerHosts(store);
+    // 4. Any spexcode-stamped plugin bundle under configured, standard, or ledger-recovered hosts. The ledger
+    //    input is what closes plugin-folder A -> native/folder B even when the previous materialize never finished.
+    let pluginHosts = [...DEFAULT_PLUGIN_HOSTS, ...ledgerHosts];
+    try {
+        const targets = resolveHarnessTargets(readConfig(mainCheckout(proj)).harnesses);
+        pluginHosts = [...pluginHosts, ...targets.filter((t) => t.kind === 'plugin').map((t) => t.folder)];
+    }
+    catch {
+        // an illegal harnesses set doesn't block backout — fall through to the standard hosts.
+    }
+    const bundles = sweepPluginBundles(proj, pluginHosts);
+    // 5. The whole store: per-tree manifests/hashes/ledgers and sessions.
+    const removedStores = [];
+    for (const candidate of new Set([store].filter((path) => !!path))) {
+        if (!existsSync(candidate))
+            continue;
+        rmSync(candidate, { recursive: true, force: true });
+        removedStores.push(candidate);
+    }
+    console.log(`✓ dematerialized (contract blocks, shims, Codex trust, skills, sub-agents, ignore blocks, content filter) for ${HARNESSES.map((h) => h.id).join(', ')}`);
+    if (removedStores.length)
+        console.log(`✓ removed the global per-project store (${removedStores.join(', ')})`);
+    if (bundles.length)
+        console.log(`✓ removed plugin bundle(s): ${bundles.join(', ')}`);
+    // Git hooks are per-clone and may carry user logic → preserved unless --hooks (and even then only while
+    // byte-identical to a canonical generated template; a user edit withdraws our ownership).
+    if (opts.hooks) {
+        const removed = removeHooks(proj);
+        if (removed.length)
+            console.log(`✓ removed git hooks (${removed.join(', ')})`);
+        else
+            console.log('• no spexcode git hooks to remove');
+    }
+    else {
+        console.log('• left git hooks in place (per-clone; pass --hooks to remove the spexcode ones)');
+    }
+    console.log(`
+SpexCode wiring removed. Your spec data is untouched:
+  • .spec/ (including .plugins/) and spexcode.json remain — your tracked intent is never deleted by uninstall.
+  • To re-adopt later: \`spex init\` regenerates the shims, contract, trust, and global store.`);
+}