@spexcode/spec-cli 0.6.5

package/dist/host.js

@@ -0,0 +1,663 @@
+import net from 'node:net';
+import { spawn } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { mkdirSync, writeFileSync, readFileSync, renameSync, rmSync, readdirSync, openSync, closeSync, existsSync, realpathSync, statSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join, basename, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { spexcodeHome, encodeProject } from '@spexcode/spec-core';
+import { git } from '@spexcode/spec-core';
+import { serveStatic, resolveDistDir } from './gateway.js';
+import { startHubGateway } from './gateway-hub.js';
+import { MachinePeerGateway } from './machine-peer.js';
+import { DEFAULT_PROJECT_ICON, requireIdentityChoice } from '@spexcode/spec-core/identity';
+import { resolveProjectIdentity, writeGatewayIcon, } from '@spexcode/spec-core';
+import { cliEntrypointArgs } from './tsx-bin.js';
+const here = dirname(fileURLToPath(import.meta.url));
+export const endpointRecordPath = (root) => join(spexcodeHome(), 'projects', encodeProject(root), 'backend.json');
+// atomic publish: tmp + rename, so a reader never sees a torn record (the old write-in-place could be
+// caught mid-write by the reconciler or a bare `spex`'s discovery probe).
+export function publishEndpoint(rec) {
+    const file = endpointRecordPath(rec.root);
+    mkdirSync(dirname(file), { recursive: true });
+    const tmp = join(dirname(file), `.backend.json.${process.pid}.tmp`);
+    writeFileSync(tmp, JSON.stringify(rec, null, 2) + '\n');
+    renameSync(tmp, file);
+}
+// remove the record ONLY if it is ours (matched by instanceId): a newer serve that already overwrote it,
+// or another project's record, is never deleted by a retiring process.
+export function dropOwnEndpoint(instanceId, root) {
+    const file = endpointRecordPath(root);
+    try {
+        if (JSON.parse(readFileSync(file, 'utf8'))?.instanceId === instanceId)
+            rmSync(file);
+    }
+    catch { /* not ours / already gone */ }
+}
+// a record is HOSTABLE only in the full identity shape; legacy {url,pid} records (pre-instance-identity)
+// are ignored by the host — the direct CLI ladder still reads their url, and they are rewritten in the new
+// shape the next time that serve restarts.
+export function readEndpointRecord(file) {
+    try {
+        const r = JSON.parse(readFileSync(file, 'utf8'));
+        if (r?.version === 2 && typeof r.url === 'string' && typeof r.instanceId === 'string' && typeof r.root === 'string' &&
+            typeof r.identity?.title === 'string' && typeof r.identity?.icon === 'string')
+            return r;
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+export const catalogPath = () => join(spexcodeHome(), 'projects.json');
+let catalogWarned = false;
+export function readCatalog() {
+    let raw;
+    try {
+        raw = readFileSync(catalogPath(), 'utf8');
+    }
+    catch {
+        return [];
+    }
+    try {
+        const parsed = JSON.parse(raw);
+        const list = Array.isArray(parsed?.projects) ? parsed.projects : [];
+        return list.filter((e) => e && typeof e.root === 'string');
+    }
+    catch (e) {
+        // reads degrade loud-but-alive (the reconciler must keep serving live records); WRITES refuse below,
+        // so a malformed catalog is never silently clobbered.
+        if (!catalogWarned) {
+            catalogWarned = true;
+            console.error(`[host] malformed ${catalogPath()} (${e.message}) — known-project catalog ignored until fixed`);
+        }
+        return [];
+    }
+}
+function writeCatalog(entries) {
+    if (existsSync(catalogPath())) {
+        try {
+            JSON.parse(readFileSync(catalogPath(), 'utf8'));
+        }
+        catch {
+            throw new Error(`refusing to overwrite malformed ${catalogPath()} — fix or remove it first`);
+        }
+    }
+    mkdirSync(dirname(catalogPath()), { recursive: true });
+    const tmp = join(dirname(catalogPath()), `.projects.json.${process.pid}.tmp`);
+    writeFileSync(tmp, JSON.stringify({ projects: entries }, null, 2) + '\n');
+    renameSync(tmp, catalogPath());
+}
+function existingDirectory(dir) {
+    let path;
+    try {
+        path = realpathSync(resolve(dir));
+    }
+    catch {
+        throw new Error(`${dir} is not an existing directory`);
+    }
+    try {
+        if (!statSync(path).isDirectory())
+            throw new Error('not a directory');
+    }
+    catch {
+        throw new Error(`${dir} is not an existing directory`);
+    }
+    return path;
+}
+function gitProjectRoot(dir) {
+    try {
+        return dirname(git(['-C', dir, 'rev-parse', '--path-format=absolute', '--git-common-dir']).trim());
+    }
+    catch {
+        return null;
+    }
+}
+export function browseProjectDirectories(dir) {
+    const requested = (dir ?? '').trim() || homedir();
+    if (!existsSync(resolve(requested))) {
+        const path = resolve(requested);
+        return {
+            path, exists: false, parent: dirname(path) === path ? null : dirname(path), home: homedir(),
+            gitRoot: null, initialized: false, cataloged: false, entries: [],
+        };
+    }
+    const path = existingDirectory(requested);
+    const gitRoot = gitProjectRoot(path);
+    const entries = readdirSync(path, { withFileTypes: true })
+        .filter((entry) => {
+        if (entry.isDirectory())
+            return true;
+        if (!entry.isSymbolicLink())
+            return false;
+        try {
+            return statSync(join(path, entry.name)).isDirectory();
+        }
+        catch {
+            return false;
+        }
+    })
+        .map((entry) => {
+        const child = join(path, entry.name);
+        const isGit = existsSync(join(child, '.git'));
+        return {
+            name: entry.name,
+            path: child,
+            git: isGit,
+            initialized: isGit && existsSync(join(child, '.spec')),
+        };
+    })
+        .sort((a, b) => a.name.localeCompare(b.name));
+    return {
+        path, exists: true,
+        parent: dirname(path) === path ? null : dirname(path),
+        home: homedir(),
+        gitRoot,
+        initialized: !!gitRoot && existsSync(join(gitRoot, '.spec')),
+        cataloged: !!gitRoot && readCatalog().some((entry) => entry.root === gitRoot),
+        entries,
+    };
+}
+// Register a repo by normalizing any path inside it to its MAIN checkout (the identity every record and
+// store key uses), then dedupe + persist it.
+export function addKnownProject(dir) {
+    const path = existingDirectory(dir);
+    const root = gitProjectRoot(path);
+    if (!root)
+        throw new Error(`${dir} is not a git repository — SpexCode projects are git-backed (run \`git init\` there first)`);
+    catalogAdd(root);
+    return root;
+}
+function catalogAdd(root) {
+    const entries = readCatalog();
+    if (entries.some((e) => e.root === root))
+        return;
+    writeCatalog([...entries, { root, addedAt: new Date().toISOString() }]);
+}
+async function fetchInstance(url) {
+    const ctrl = new AbortController();
+    const t = setTimeout(() => ctrl.abort(), 900);
+    try {
+        const r = await fetch(`${url}/api/instance`, { signal: ctrl.signal });
+        if (!r.ok)
+            return null;
+        return await r.json();
+    }
+    catch {
+        return null;
+    }
+    finally {
+        clearTimeout(t);
+    }
+}
+export async function reconcileProjects() {
+    const projectsDir = join(spexcodeHome(), 'projects');
+    let dirs = [];
+    try {
+        dirs = readdirSync(projectsDir, { withFileTypes: true }).filter((d) => d.isDirectory()).map((d) => d.name);
+    }
+    catch (e) {
+        if (e.code !== 'ENOENT')
+            throw e;
+    }
+    const live = new Map();
+    const claimed = new Set(); // roots with a slot-matched record, validated or not
+    await Promise.all(dirs.map(async (d) => {
+        const rec = readEndpointRecord(join(projectsDir, d, 'backend.json'));
+        if (!rec)
+            return;
+        if (encodeProject(rec.root) !== d)
+            return;
+        claimed.add(rec.root); // a dead/mismatched record still NAMES a project — listed offline
+        const inst = await fetchInstance(rec.url);
+        if (inst && inst.instanceId === rec.instanceId && inst.root === rec.root &&
+            typeof inst.identity?.title === 'string' && typeof inst.identity?.icon === 'string') {
+            live.set(rec.root, { rec, identity: inst.identity });
+        }
+    }));
+    const byId = new Map();
+    const push = (root) => {
+        if (!existsSync(root))
+            return;
+        const projectId = encodeProject(root);
+        if (byId.has(projectId))
+            return; // encodeProject is lossy; first root wins a (pathological) collision
+        const active = live.get(root) ?? null;
+        const source = readProjectConfig(root);
+        let identity;
+        try {
+            identity = active?.identity ?? resolveProjectIdentity(root, root);
+        }
+        catch (e) {
+            console.error(`[host] cannot resolve identity for ${root}: ${e.message}`);
+            identity = { title: basename(root), icon: DEFAULT_PROJECT_ICON };
+        }
+        byId.set(projectId, {
+            projectId, root, identity, configRevision: source.revision,
+            online: !!active, url: active?.rec.url ?? null,
+            ...(active ? { pid: active.rec.pid, startedAt: active.rec.startedAt } : {}),
+        });
+    };
+    for (const e of readCatalog())
+        push(e.root);
+    for (const root of claimed)
+        push(root);
+    return [...byId.values()].sort((a, b) => a.identity.title.localeCompare(b.identity.title) || a.root.localeCompare(b.root));
+}
+// single-flight + last-snapshot: every reader (GET, the stream loop, the per-request proxy resolution)
+// shares one in-flight reconcile instead of stampeding probes.
+let snapshot = [];
+let inflight = null;
+export function reconcileNow() {
+    return (inflight ??= reconcileProjects()
+        .then((list) => { snapshot = list; return list; })
+        .finally(() => { inflight = null; }));
+}
+// ── host operations (spawned `spex`, never forked logic) ─────────────────────────────────────────────
+// init / doctor / serve run the EXISTING CLI implementations as child processes with cwd = the project
+// root: the same git/harness/additive guarantees `spex init` gives at a terminal, the same doctor report,
+// the same supervisor `spex serve` boots — no second implementation of any domain semantics. The spawned
+// env is scrubbed of routing state (SPEXCODE_API_URL/PORT/session/instance ids) so a child never inherits
+// the gateway's — or another project's — backend routing.
+const cliArgs = cliEntrypointArgs(join(here, '..'), here);
+function scrubbedEnv() {
+    const env = { ...process.env };
+    delete env.SPEXCODE_API_URL;
+    delete env.PORT;
+    delete env.SPEXCODE_SESSION_ID;
+    delete env.SPEXCODE_INSTANCE_ID;
+    return env;
+}
+export function runSpex(root, args, timeoutMs = 120_000) {
+    return new Promise((resolve) => {
+        const child = spawn(process.execPath, [...cliArgs, ...args], { cwd: root, env: scrubbedEnv() });
+        let output = '';
+        child.stdout.on('data', (d) => { output += d; });
+        child.stderr.on('data', (d) => { output += d; });
+        const t = setTimeout(() => { try {
+            child.kill('SIGKILL');
+        }
+        catch { /* gone */ } }, timeoutMs);
+        child.on('close', (code) => { clearTimeout(t); resolve({ code, output }); });
+        child.on('error', (e) => { clearTimeout(t); resolve({ code: null, output: `${output}\nspawn failed: ${e.message}` }); });
+    });
+}
+// One ordered add transaction: select an existing directory or explicitly create one with Git, run the
+// real CLI initializer when requested, and only then claim catalog success.
+export async function addKnownProjectWithSetup(dir, setup = {}) {
+    if (setup.createDir && !setup.initGit)
+        throw new Error('creating a project directory requires Git initialization');
+    let directoryCreated = false;
+    let path;
+    try {
+        path = existingDirectory(dir);
+    }
+    catch (e) {
+        if (!setup.createDir)
+            throw e;
+        mkdirSync(resolve(dir), { recursive: true });
+        directoryCreated = true;
+        path = existingDirectory(dir);
+    }
+    let root = gitProjectRoot(path);
+    let gitInitialized = false;
+    if (!root) {
+        if (!setup.initGit)
+            throw new Error(`${dir} is not a git repository — enable Git initialization to add it`);
+        git(['init', '--quiet', '--', path]);
+        gitInitialized = true;
+        root = gitProjectRoot(path);
+        if (!root)
+            throw new Error(`git init completed but ${path} is still not a Git repository`);
+    }
+    let init;
+    if (setup.init) {
+        const harness = typeof setup.init.harness === 'string' ? setup.init.harness.trim() : '';
+        if (!harness)
+            throw new Error('SpexCode initialization requires at least one explicit harness target');
+        const preset = typeof setup.init.preset === 'string' ? setup.init.preset.trim() : '';
+        const result = await runSpex(root, ['init', '--harness', harness, ...(preset ? ['--preset', preset] : [])]);
+        init = result;
+        if (result.code !== 0)
+            return { ok: false, root, directoryCreated, gitInitialized, init };
+    }
+    catalogAdd(root);
+    return { ok: true, root, directoryCreated, gitInitialized, ...(init ? { init } : {}) };
+}
+let configWriteSeq = 0;
+const configRevision = (raw) => createHash('sha256').update(raw === null ? 'missing' : `present\0${raw}`).digest('hex');
+function readProjectConfig(root) {
+    try {
+        const content = readFileSync(join(root, 'spexcode.json'), 'utf8');
+        return { content, revision: configRevision(content) };
+    }
+    catch (e) {
+        if (e.code === 'ENOENT')
+            return { content: '{}\n', revision: configRevision(null) };
+        throw e;
+    }
+}
+function writeProjectConfig(root, content, revision) {
+    const current = readProjectConfig(root);
+    if (revision !== current.revision) {
+        const e = new Error('spexcode.json changed on disk — reload before saving');
+        e.status = 409;
+        throw e;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(content);
+    }
+    catch (e) {
+        const err = new Error(`spexcode.json is not valid JSON: ${e.message}`);
+        err.status = 400;
+        throw err;
+    }
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        const e = new Error('spexcode.json must contain one top-level JSON object');
+        e.status = 400;
+        throw e;
+    }
+    const normalized = content.endsWith('\n') ? content : `${content}\n`;
+    const file = join(root, 'spexcode.json');
+    const tmp = join(root, `.spexcode.json.${process.pid}.${++configWriteSeq}.tmp`);
+    try {
+        writeFileSync(tmp, normalized);
+        renameSync(tmp, file);
+    }
+    finally {
+        try {
+            rmSync(tmp);
+        }
+        catch { /* rename consumed it / write never created it */ }
+    }
+    return { content: normalized, revision: configRevision(normalized) };
+}
+function writeProjectIcon(root, icon, revision) {
+    const canonical = requireIdentityChoice(icon);
+    const current = readProjectConfig(root);
+    let config;
+    try {
+        config = JSON.parse(current.content);
+    }
+    catch (e) {
+        const error = new Error(`spexcode.json is not valid JSON: ${e.message}`);
+        error.status = 400;
+        throw error;
+    }
+    const dashboard = config.dashboard === undefined
+        ? {}
+        : config.dashboard && typeof config.dashboard === 'object' && !Array.isArray(config.dashboard)
+            ? config.dashboard
+            : null;
+    if (!dashboard) {
+        const error = new Error('spexcode.json dashboard must be an object before its icon can be changed');
+        error.status = 400;
+        throw error;
+    }
+    const saved = writeProjectConfig(root, `${JSON.stringify({ ...config, dashboard: { ...dashboard, icon: canonical } }, null, 2)}\n`, revision);
+    return { ...saved, identity: resolveProjectIdentity(root, root) };
+}
+function freeTcpPort() {
+    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)); });
+    });
+}
+// start an OFFLINE project's backend: spawn a detached `spex serve --port <free>` whose lifetime is
+// independent of the gateway (it owns its record exactly like a hand-run serve), log to the project's
+// runtime tier, and wait for its instance-validated record to reconcile online.
+export async function startBackend(root, waitMs = 45_000) {
+    const port = await freeTcpPort();
+    const logDir = join(spexcodeHome(), 'projects', encodeProject(root));
+    mkdirSync(logDir, { recursive: true });
+    const logFile = join(logDir, 'serve.log');
+    const log = openSync(logFile, 'a');
+    const child = spawn(process.execPath, [...cliArgs, 'serve', '--port', String(port)], { cwd: root, env: scrubbedEnv(), detached: true, stdio: ['ignore', log, log] });
+    child.unref();
+    closeSync(log); // the child holds its own copy; keep no fd open in the gateway
+    const deadline = Date.now() + waitMs;
+    while (Date.now() < deadline) {
+        await new Promise((r) => setTimeout(r, 500));
+        const entry = (await reconcileNow()).find((p) => p.root === root && p.online);
+        if (entry)
+            return entry;
+    }
+    throw new Error(`backend for ${root} did not come online within ${Math.round(waitMs / 1000)}s — see ${logFile}`);
+}
+const json = (res, status, body) => {
+    res.writeHead(status, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify(body));
+};
+function readBody(req) {
+    return new Promise((resolve) => {
+        let body = '';
+        req.on('data', (d) => { body += d; if (body.length > 65536)
+            req.destroy(); });
+        req.on('end', () => resolve(body));
+    });
+}
+export function startHostDashboard(opts) {
+    const distDir = opts.distDir ?? resolveDistDir();
+    const peers = new MachinePeerGateway();
+    peers.start();
+    const sseClients = new Set();
+    let lastBroadcast = '';
+    // reconcile → push the fresh list to every /projects/stream subscriber when it changed.
+    async function tick() {
+        const list = await reconcileNow();
+        const j = JSON.stringify(list);
+        if (j !== lastBroadcast) {
+            lastBroadcast = j;
+            for (const c of sseClients)
+                c.write(`data: ${j}\n\n`);
+        }
+        return list;
+    }
+    const extensions = {
+        // the hub's GET /projects rows, host-enriched: every cataloged/claimed project (not only live
+        // records), instance-validated online state, and the hub's own gating flag per row. `id` mirrors
+        // projectId — the hub's documented row key, kept so both shapes read the same list.
+        listProjects: async (store) => (await tick()).map((p) => ({ id: p.projectId, ...p, gated: !!store.projects[p.projectId] })),
+        adminRoute: async (req, res, path) => {
+            if (path === '/projects/stream') {
+                res.writeHead(200, { 'Content-Type': 'text/event-stream', 'Cache-Control': 'no-cache', Connection: 'keep-alive' });
+                res.write(`data: ${JSON.stringify(await tick())}\n\n`);
+                sseClients.add(res);
+                req.on('close', () => sseClients.delete(res));
+                return true;
+            }
+            if (path === '/projects/browse' && req.method === 'GET') {
+                const requested = new URL(req.url ?? path, 'http://localhost').searchParams.get('path') ?? '';
+                try {
+                    json(res, 200, browseProjectDirectories(requested));
+                }
+                catch (e) {
+                    json(res, 400, { error: e.message });
+                }
+                return true;
+            }
+            if (path === '/projects' && req.method === 'POST') {
+                let body = {};
+                try {
+                    body = JSON.parse(await readBody(req) || '{}');
+                }
+                catch { /* malformed body */ }
+                const root = String(body?.root ?? '').trim();
+                if (!root) {
+                    json(res, 400, { error: 'body must be {"root": "/abs/path/to/repo"}' });
+                    return true;
+                }
+                if (body.init !== undefined && (!body.init || typeof body.init !== 'object' || Array.isArray(body.init))) {
+                    json(res, 400, { error: 'init must be {"harness":"<ids>","preset":"<optional>"}' });
+                    return true;
+                }
+                try {
+                    const setup = await addKnownProjectWithSetup(root, {
+                        createDir: body.createDir === true,
+                        initGit: body.initGit === true,
+                        ...(body.init ? { init: { harness: body.init.harness, ...(body.init.preset !== undefined ? { preset: body.init.preset } : {}) } } : {}),
+                    });
+                    if (!setup.ok) {
+                        json(res, 422, { error: 'spex init failed', ...setup });
+                        return true;
+                    }
+                    const entry = (await tick()).find((p) => p.root === setup.root);
+                    json(res, 200, { ...(entry ?? {
+                            projectId: encodeProject(setup.root), root: setup.root,
+                            identity: resolveProjectIdentity(setup.root, setup.root), configRevision: readProjectConfig(setup.root).revision,
+                            online: false, url: null,
+                        }), setup });
+                }
+                catch (e) {
+                    json(res, 400, { error: e.message });
+                }
+                return true;
+            }
+            if (path === '/projects/icon' && req.method === 'PUT') {
+                let body;
+                try {
+                    body = JSON.parse(await readBody(req) || '{}');
+                }
+                catch {
+                    json(res, 400, { error: 'body must be {"icon":"<choice>","revision":"..."}' });
+                    return true;
+                }
+                if (typeof body?.icon !== 'string' || typeof body?.revision !== 'string') {
+                    json(res, 400, { error: 'body must be {"icon":"<choice>","revision":"..."}' });
+                    return true;
+                }
+                try {
+                    json(res, 200, { ok: true, gateway: writeGatewayIcon(body.icon, body.revision) });
+                }
+                catch (e) {
+                    json(res, e.status ?? 400, { error: e.message });
+                }
+                return true;
+            }
+            const icon = path.match(/^\/projects\/([^/]+)\/icon$/);
+            if (icon && req.method === 'PUT') {
+                const projectId = decodeURIComponent(icon[1]);
+                const entry = (await reconcileNow()).find((p) => p.projectId === projectId);
+                if (!entry) {
+                    json(res, 404, { error: `unknown project '${projectId}' — add it first (POST /projects)` });
+                    return true;
+                }
+                let body;
+                try {
+                    body = JSON.parse(await readBody(req) || '{}');
+                }
+                catch {
+                    json(res, 400, { error: 'body must be {"icon":"<choice>","revision":"..."}' });
+                    return true;
+                }
+                if (typeof body?.icon !== 'string' || typeof body?.revision !== 'string') {
+                    json(res, 400, { error: 'body must be {"icon":"<choice>","revision":"..."}' });
+                    return true;
+                }
+                try {
+                    json(res, 200, { ok: true, ...writeProjectIcon(entry.root, body.icon, body.revision) });
+                }
+                catch (e) {
+                    json(res, e.status ?? 400, { error: e.message });
+                }
+                return true;
+            }
+            const config = path.match(/^\/projects\/([^/]+)\/config$/);
+            if (config && (req.method === 'GET' || req.method === 'PUT')) {
+                const projectId = decodeURIComponent(config[1]);
+                const entry = (await reconcileNow()).find((p) => p.projectId === projectId);
+                if (!entry) {
+                    json(res, 404, { error: `unknown project '${projectId}' — add it first (POST /projects)` });
+                    return true;
+                }
+                if (req.method === 'GET') {
+                    try {
+                        json(res, 200, readProjectConfig(entry.root));
+                    }
+                    catch (e) {
+                        json(res, 500, { error: `cannot read spexcode.json: ${e.message}` });
+                    }
+                    return true;
+                }
+                let body;
+                try {
+                    body = JSON.parse(await readBody(req) || '{}');
+                }
+                catch {
+                    json(res, 400, { error: 'body must be {"content":"...","revision":"..."}' });
+                    return true;
+                }
+                if (typeof body?.content !== 'string' || typeof body?.revision !== 'string') {
+                    json(res, 400, { error: 'body must be {"content":"...","revision":"..."}' });
+                    return true;
+                }
+                try {
+                    json(res, 200, { ok: true, ...writeProjectConfig(entry.root, body.content, body.revision) });
+                }
+                catch (e) {
+                    json(res, e.status ?? 500, { error: e.message });
+                }
+                return true;
+            }
+            const op = path.match(/^\/projects\/([^/]+)\/(init|doctor|serve)$/);
+            if (op && req.method === 'POST') {
+                const projectId = decodeURIComponent(op[1]);
+                const entry = (await reconcileNow()).find((p) => p.projectId === projectId);
+                if (!entry) {
+                    json(res, 404, { error: `unknown project '${projectId}' — add it first (POST /projects)` });
+                    return true;
+                }
+                if (op[2] === 'serve') {
+                    if (entry.online) {
+                        json(res, 409, { error: `backend already online at ${entry.url}`, project: entry });
+                        return true;
+                    }
+                    try {
+                        json(res, 200, { ok: true, project: await startBackend(entry.root) });
+                    }
+                    catch (e) {
+                        json(res, 502, { error: e.message });
+                    }
+                    return true;
+                }
+                let body = {};
+                try {
+                    body = JSON.parse(await readBody(req) || '{}');
+                }
+                catch { /* malformed body → defaults */ }
+                const args = op[2] === 'init'
+                    ? ['init', ...(body?.harness ? ['--harness', String(body.harness)] : []), ...(body?.preset ? ['--preset', String(body.preset)] : [])]
+                    : ['doctor'];
+                const r = await runSpex(entry.root, args);
+                json(res, 200, { ok: r.code === 0, code: r.code, output: r.output });
+                return true;
+            }
+            return false;
+        },
+        fallback: (req, res, path) => serveStatic(req, res, distDir, path),
+    };
+    const server = startHubGateway({ port: opts.port, host: opts.host ?? '127.0.0.1', tls: opts.tls ?? null, extensions });
+    // continuous reconciliation: the stream stays live without a client-side poll and the list the hub
+    // serves stays fresh. Heartbeat comments keep intermediaries from timing the stream out. Both timers
+    // unref'd — the SERVER holds the process open, not the loops.
+    const loop = setInterval(() => void tick().catch((e) => console.error(`[host] reconcile failed: ${e.message}`)), 2500);
+    loop.unref();
+    const ping = setInterval(() => { for (const c of sseClients)
+        c.write(': ping\n\n'); }, 10_000);
+    ping.unref();
+    return {
+        server,
+        close: async () => {
+            clearInterval(loop);
+            clearInterval(ping);
+            for (const c of sseClients)
+                c.destroy();
+            sseClients.clear();
+            await peers.close();
+            await new Promise((resolve) => server.close(() => resolve()));
+            server.closeAllConnections?.();
+        },
+    };
+}

package/dist/index.d.ts

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