@aexol/spectral 0.0.1

package/dist/relay/dispatcher.js

@@ -0,0 +1,504 @@
+/**
+ * Relay envelope dispatcher (CLI side).
+ *
+ * Translates inbound `RelayFrame`s from the backend into calls against the
+ * pure REST handlers (`handlers/projects.ts`, `handlers/sessions.ts`) and
+ * the live `SessionStreamManager`. Pure module — no socket, no timers,
+ * no logging side-channels except what the caller passes in. The caller
+ * (`commands/serve.ts`) owns lifecycle and the `RelayClient`.
+ *
+ * Two entry points, one per inbound frame kind we route:
+ *
+ *  - `handleRestRequest(frame, deps)` — synchronous-style request/response.
+ *    Resolves to a `RestResponseFrame` the caller sends back via
+ *    `relay.send(...)`. Errors thrown by handlers are mapped to status
+ *    codes (400/404/500) and returned in the body, never re-thrown — the
+ *    backend has a 30 s pending-request timeout and we want every request
+ *    to terminate with a wire response so the browser doesn't sit on a
+ *    stale spinner.
+ *
+ *  - `handleClientMessage(frame, deps)` — fire-and-forget. Attaches a
+ *    `Subscriber` (the relay socket, wrapped) to the session if not
+ *    already attached, then calls `manager.prompt()`. Outbound
+ *    `ServerEvent`s flow back through the subscriber as `WsEventFrame`s
+ *    via `deps.relay.send()`.
+ *
+ * Subscriber bookkeeping lives in `serve.ts`, NOT here. The dispatcher
+ * is given the subscriber by the caller so it stays pure-ish (depends
+ * only on `manager` + `relay.send`). This also keeps the lifecycle for
+ * "detach all on relay disconnect" in one place.
+ *
+ * Path matching is a 30-line inline switch; we deliberately do not pull
+ * in `path-to-regexp` for five literal patterns. The matcher returns
+ * the parsed `id` param when applicable.
+ *
+ * Close-code policy (mirroring backend `router.ts`):
+ *  - The dispatcher itself never closes the relay; that's serve.ts.
+ *  - Backend cancels pending REST requests with `code:"timeout"` (30 s)
+ *    or `code:"machine_offline"` (CLI socket dropped). Both are
+ *    transparent to this layer — we just respond when we can.
+ */
+import { BadRequestError, NotFoundError } from "../server/handlers/errors.js";
+import { handleCreateProject, handleDeleteProject, handleListProjects, handleListSessionsByProject, handleUpdateProject, } from "../server/handlers/projects.js";
+import { handleCreateSession, handleDeleteSession, handleGetSessionDetail, handleUpdateSession, } from "../server/handlers/sessions.js";
+import { shutdownState } from "../server/shutdown.js";
+/**
+ * Inline path matcher. Returns `null` for any path/method combination we
+ * don't recognise; the caller turns that into a `404 Unknown route`.
+ *
+ * Intentionally literal — a regex table would be marginally fancier but
+ * also marginally slower and harder to read for ~9 routes.
+ */
+export function matchRoute(method, path) {
+    // Strip query string if any (we don't use any, but be defensive).
+    const qIdx = path.indexOf("?");
+    const cleanPath = qIdx === -1 ? path : path.slice(0, qIdx);
+    // /api/projects
+    if (cleanPath === "/api/projects") {
+        if (method === "GET")
+            return { route: "list_projects" };
+        if (method === "POST")
+            return { route: "create_project" };
+        return null;
+    }
+    // /api/sessions
+    if (cleanPath === "/api/sessions") {
+        if (method === "POST")
+            return { route: "create_session" };
+        return null;
+    }
+    // /api/projects/:id  and  /api/projects/:id/sessions
+    const projectMatch = /^\/api\/projects\/([^/]+)(\/sessions)?$/.exec(cleanPath);
+    if (projectMatch) {
+        const id = decodeURIComponent(projectMatch[1]);
+        const isSessions = projectMatch[2] === "/sessions";
+        if (isSessions) {
+            if (method === "GET")
+                return { route: "list_project_sessions", id };
+            return null;
+        }
+        if (method === "PATCH")
+            return { route: "update_project", id };
+        if (method === "DELETE")
+            return { route: "delete_project", id };
+        return null;
+    }
+    // /api/sessions/:id
+    const sessionMatch = /^\/api\/sessions\/([^/]+)$/.exec(cleanPath);
+    if (sessionMatch) {
+        const id = decodeURIComponent(sessionMatch[1]);
+        if (method === "GET")
+            return { route: "get_session", id };
+        if (method === "PATCH")
+            return { route: "update_session", id };
+        if (method === "DELETE")
+            return { route: "delete_session", id };
+        return null;
+    }
+    return null;
+}
+/**
+ * Dispatch a `rest_request` frame. Always resolves with a
+ * `RestResponseFrame` — handler exceptions are caught and translated.
+ *
+ * Status mapping:
+ *  - 200: handler returned successfully (body is the handler's return value
+ *         or `{ ok: true }` for void returns)
+ *  - 400: `BadRequestError` thrown by handler, OR malformed body for a
+ *         route that requires one, OR unknown route
+ *  - 404: `NotFoundError` thrown by handler
+ *  - 405: route matches but method doesn't (returned as 404 since we don't
+ *         distinguish — the matcher treats it as "no route", consistent
+ *         with the original Hono router which also 404'd)
+ *  - 500: anything else; `error` field carries a sanitized message
+ */
+export function handleRestRequest(frame, deps) {
+    const { reqId, method, path, body } = frame;
+    const logger = deps.logger ?? console;
+    const match = matchRoute(method, path);
+    if (!match) {
+        return {
+            kind: "rest_response",
+            reqId,
+            status: 404,
+            body: { error: `Unknown route: ${method} ${path}` },
+        };
+    }
+    try {
+        const result = dispatchRoute(match, body, deps);
+        return {
+            kind: "rest_response",
+            reqId,
+            status: 200,
+            body: result,
+        };
+    }
+    catch (err) {
+        if (err instanceof BadRequestError) {
+            return {
+                kind: "rest_response",
+                reqId,
+                status: 400,
+                body: { error: err.message, code: err.code },
+            };
+        }
+        if (err instanceof NotFoundError) {
+            return {
+                kind: "rest_response",
+                reqId,
+                status: 404,
+                body: { error: err.message, code: err.code },
+            };
+        }
+        // Unexpected — log locally so operators can correlate, but only
+        // return a sanitized message to the caller.
+        logger.error?.(`[dispatcher] unexpected error in ${method} ${path}:`, err);
+        return {
+            kind: "rest_response",
+            reqId,
+            status: 500,
+            body: { error: "Internal error" },
+        };
+    }
+}
+/**
+ * Inner switch: route → handler call. Separated so `handleRestRequest`
+ * owns ONE try/catch boundary for all error mapping.
+ *
+ * Meta publish is fired AFTER the handler returns successfully (i.e.
+ * after SQLite has committed) so subscribers never see a "create" event
+ * for a row the next read won't find. Publish failures are swallowed
+ * inside `safePublish` — the wire response goes back regardless.
+ *
+ * The body is `unknown` from the wire; each handler validates its own
+ * shape via the `BadRequestError`-throwing checks they already do.
+ */
+function dispatchRoute(match, body, deps) {
+    const { store, manager, publishMetaEvent, logger } = deps;
+    const id = match.id ?? "";
+    switch (match.route) {
+        case "list_projects":
+            return handleListProjects(store);
+        case "create_project": {
+            const project = handleCreateProject(store, asObject(body));
+            safePublish(publishMetaEvent, logger, {
+                type: "project_created",
+                projectId: project.id,
+            });
+            return project;
+        }
+        case "update_project": {
+            const project = handleUpdateProject(store, id, asObject(body));
+            safePublish(publishMetaEvent, logger, {
+                type: "project_renamed",
+                projectId: project.id,
+            });
+            return project;
+        }
+        case "delete_project": {
+            // Order matters: tear down live streams BEFORE the row is gone so
+            // the bridges don't try to write to a deleted FK target. Mirrors
+            // the ordering the deleted Hono route used.
+            const project = store.getProject(id);
+            if (project) {
+                const sessions = store.listSessionsByProject(id);
+                manager.disposeProjectStreams(sessions.map((s) => s.id));
+            }
+            const result = handleDeleteProject(store, id);
+            // Publish AFTER the cascade has committed. We use `id` (the URL
+            // param) as the projectId — `handleDeleteProject` would have
+            // thrown 404 above if it didn't exist.
+            safePublish(publishMetaEvent, logger, {
+                type: "project_deleted",
+                projectId: id,
+            });
+            return result;
+        }
+        case "list_project_sessions":
+            return handleListSessionsByProject(store, id);
+        case "create_session": {
+            const session = handleCreateSession(store, asObject(body));
+            safePublish(publishMetaEvent, logger, {
+                type: "session_created",
+                projectId: session.projectId,
+                sessionId: session.id,
+            });
+            return session;
+        }
+        case "get_session":
+            return handleGetSessionDetail(store, id);
+        case "update_session": {
+            const session = handleUpdateSession(store, id, asObject(body));
+            safePublish(publishMetaEvent, logger, {
+                type: "session_renamed",
+                projectId: session.projectId,
+                sessionId: session.id,
+            });
+            return session;
+        }
+        case "delete_session": {
+            // Capture projectId BEFORE the row is gone — otherwise the
+            // post-delete publish has no project to attribute to. Treat a
+            // missing session here the same way `handleDeleteSession` does
+            // (throws NotFoundError → 404), but capture first.
+            const detail = store.getSession(id);
+            // Same ordering rationale as delete_project.
+            manager.disposeSessionStream(id);
+            handleDeleteSession(store, id);
+            if (detail) {
+                safePublish(publishMetaEvent, logger, {
+                    type: "session_deleted",
+                    projectId: detail.projectId,
+                    sessionId: id,
+                });
+            }
+            return { ok: true };
+        }
+    }
+}
+/**
+ * Invoke `publishMetaEvent` if provided, swallowing any throw. The
+ * caller has already returned a 200 to the browser; a publish failure
+ * (e.g. relay socket just dropped) must NEVER turn a successful
+ * mutation into a wire-level error.
+ */
+function safePublish(publish, logger, event) {
+    if (!publish)
+        return;
+    try {
+        publish(event);
+    }
+    catch (err) {
+        (logger ?? console).error?.(`[dispatcher] publishMetaEvent failed for ${event.type}:`, err);
+    }
+}
+/**
+ * Coerce an `unknown` body to a plain object for the handler. Returns an
+ * empty object when the body is missing/non-object so the handler's own
+ * field checks produce the canonical error message ("name (string) is
+ * required") instead of a confusing "body must be object" from us.
+ */
+function asObject(body) {
+    if (body !== null && typeof body === "object" && !Array.isArray(body)) {
+        return body;
+    }
+    return {};
+}
+/**
+ * Build a `Subscriber` that wraps each `ServerEvent` in a `WsEventFrame`
+ * and pushes it through the relay. `isOpen()` defers to the relay's
+ * connection state — we treat queue-while-disconnected as "still open"
+ * since `RelayClient.send()` will buffer and flush on reconnect.
+ */
+function makeRelaySubscriber(sessionId, relay) {
+    return {
+        send(event) {
+            relay.send({
+                kind: "ws_event",
+                sessionId,
+                event,
+            });
+        },
+        isOpen() {
+            // The relay client buffers while reconnecting; from the manager's
+            // POV the subscriber is always reachable until serve.ts detaches
+            // it. Returning `true` here means the manager won't garbage-collect
+            // the subscriber on transient socket blips.
+            return true;
+        },
+    };
+}
+/**
+ * Dispatch a `client_message` frame. Idempotent w.r.t. attach: the same
+ * `Subscriber` is reused across messages for a given session.
+ *
+ * Errors:
+ *  - Unknown sessionId → emits a `ws_event` carrying an `error`-typed
+ *    `ServerEvent` so the browser sees it on the established stream
+ *    (mirrors how the old WS route surfaced `manager.attach` failures).
+ *  - Unknown message shape → silently ignored with a logger warning;
+ *    the wire contract is `{type:"user_message", content:string}` and
+ *    anything else is a protocol violation we don't escalate.
+ *  - `manager.prompt()` rejection → logged; the manager itself broadcasts
+ *    an `error` event to subscribers, so we don't double-report.
+ */
+export function handleClientMessage(frame, deps) {
+    const { sessionId, message, modelId } = frame;
+    const { manager, relay, subscribers } = deps;
+    const logger = deps.logger ?? console;
+    // 0. Shutdown gate. Once `gracefulShutdown` flips the flag we refuse
+    //    new turns immediately — even if the relay socket is still open
+    //    and even if the session already has a subscriber attached. The
+    //    error surfaces on the same `ws_event` channel the browser is
+    //    already listening on, so the UI sees it on the established
+    //    stream and can show a "server shutting down" message instead of
+    //    sitting on a perpetual spinner.
+    //
+    //    We do NOT detach the subscriber here — pre-existing in-flight
+    //    turns still need to flush their final events before the grace
+    //    window closes.
+    if (shutdownState.isShuttingDown) {
+        relay.send({
+            kind: "ws_event",
+            sessionId,
+            event: {
+                type: "error",
+                message: "Server is shutting down; please retry shortly.",
+            },
+        });
+        return;
+    }
+    // 1. Validate inner message shape. Only `user_message` is supported
+    //    today; reject anything else loudly-but-locally.
+    if (message === null ||
+        typeof message !== "object" ||
+        message.type !== "user_message" ||
+        typeof message.content !== "string") {
+        logger.error?.(`[dispatcher] ignoring malformed client_message for ${sessionId}`);
+        return;
+    }
+    const content = message.content;
+    const isAexol = message.aexol === true;
+    // Set autonomous refactor loop state before firing the prompt.
+    // aexol:true  → start/renew loop; aexol:false → stop loop.
+    manager.setAexolActive(sessionId, isAexol);
+    // 2. Attach (idempotent). On first attach we capture the replay payload
+    //    and synthesize a `session_ready` ws_event so the browser sees the
+    //    same first frame it would have on a direct WS connection.
+    let subscriber = subscribers.get(sessionId);
+    if (!subscriber) {
+        subscriber = makeRelaySubscriber(sessionId, relay);
+        let attachResult;
+        try {
+            attachResult = manager.attach(sessionId, subscriber);
+        }
+        catch (err) {
+            // Unknown session — surface as a ws_event so the browser's stream
+            // handler sees it. Don't keep the subscriber around.
+            const msg = err instanceof Error ? err.message : String(err);
+            relay.send({
+                kind: "ws_event",
+                sessionId,
+                event: { type: "error", message: msg },
+            });
+            return;
+        }
+        subscribers.set(sessionId, subscriber);
+        // Synthesize the initial frame the WS route used to send. The
+        // browser's protocol layer expects `session_ready` as the first
+        // event on a new stream.
+        relay.send({
+            kind: "ws_event",
+            sessionId,
+            event: {
+                type: "session_ready",
+                sessionId,
+                history: attachResult.history,
+                currentTurn: attachResult.currentTurn,
+            },
+        });
+        // Surface bridge-start failures as `error` events; otherwise the
+        // browser would sit on a `session_ready` with no further frames.
+        attachResult.ready.catch((err) => {
+            const msg = err instanceof Error ? err.message : String(err);
+            relay.send({
+                kind: "ws_event",
+                sessionId,
+                event: { type: "error", message: msg },
+            });
+        });
+    }
+    // 3. Fire the prompt. `prompt()` resolves on `agent_end`; errors are
+    //    converted to `error` events by the manager itself, so we just log.
+    //    `modelId` (Phase 3 — Available Models whitelist) is forwarded as
+    //    sticky next-prompt selection. The backend has already validated it
+    //    against the team-scoped whitelist; the CLI resolves it via pi's
+    //    own model registry inside the manager → bridge.
+    //
+    //    When `aexol: true` is set on the message, route to the refactor-loop
+    //    user model instead of the default session model.
+    const effectiveModelId = isAexol ? "__aexol_refactor_loop__" : modelId;
+    manager.prompt(sessionId, content, effectiveModelId).catch((err) => {
+        logger.error?.(`[dispatcher] manager.prompt failed for ${sessionId}:`, err);
+    });
+}
+/**
+ * Dispatch a `subscribe` frame from the backend. Handles the case where a
+ * browser enters an old session — we load history from SQLite immediately
+ * via `manager.attach()` and synthesize `session_ready` so the browser sees
+ * the full chat history without needing to send a first `client_message`.
+ *
+ * Idempotent: if a subscriber already exists for this session, we re-send
+ * `session_ready` (history may have changed, and the newly-joined browser
+ * tab needs it). The `ready.catch` handler is only registered once — on the
+ * first subscriber creation — to avoid duplicate error events.
+ */
+export function handleSubscribe(frame, deps) {
+    const { sessionId } = frame;
+    const { manager, relay, subscribers } = deps;
+    const logger = deps.logger ?? console;
+    let subscriber = subscribers.get(sessionId);
+    let isNewSubscriber = false;
+    if (!subscriber) {
+        subscriber = makeRelaySubscriber(sessionId, relay);
+        subscribers.set(sessionId, subscriber);
+        isNewSubscriber = true;
+    }
+    let attachResult;
+    try {
+        attachResult = manager.attach(sessionId, subscriber);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        relay.send({
+            kind: "ws_event",
+            sessionId,
+            event: { type: "error", message: msg },
+        });
+        return;
+    }
+    // Send history to all browser subscribers. The backend's fan-out
+    // delivers this to the newly-subscribed tab (and any others).
+    relay.send({
+        kind: "ws_event",
+        sessionId,
+        event: {
+            type: "session_ready",
+            sessionId,
+            history: attachResult.history,
+            currentTurn: attachResult.currentTurn,
+        },
+    });
+    if (isNewSubscriber) {
+        // Surface bridge-start failures as `error` events; otherwise the
+        // browser would sit on a `session_ready` with no further frames.
+        attachResult.ready.catch((err) => {
+            const msg = err instanceof Error ? err.message : String(err);
+            relay.send({
+                kind: "ws_event",
+                sessionId,
+                event: { type: "error", message: msg },
+            });
+        });
+    }
+}
+/**
+ * Detach every subscriber the dispatcher has attached. Called by
+ * `serve.ts` on relay disconnect / shutdown so the underlying pi
+ * processes don't keep an unreachable subscriber pinned.
+ *
+ * NOTE: this does NOT dispose the streams themselves — pi keeps running
+ * so a future browser reconnect can resume mid-turn. Use
+ * `manager.dispose()` at full shutdown.
+ */
+export function detachAllSubscribers(manager, subscribers) {
+    for (const [sessionId, sub] of subscribers) {
+        try {
+            manager.detach(sessionId, sub);
+        }
+        catch {
+            // ignore — best-effort cleanup
+        }
+    }
+    subscribers.clear();
+}

package/dist/relay/machine-store.js

@@ -0,0 +1,116 @@
+/**
+ * Persistent record of a registered machine.
+ *
+ * Lives at `<configDir>/machine.json` (mode 0600). Created the first time
+ * `spectral serve` runs after login; reused across restarts so a single
+ * developer machine appears as one logical agent in the backend's machine
+ * list, regardless of how many times the CLI process restarts.
+ *
+ * Why a separate file from `config.json`?
+ *  - `config.json` carries the team API key (rotated on logout). The
+ *    machine identity outlives logout/login: if you `logout` then
+ *    `login` with the same team, your machine should keep its `machineId`
+ *    so the backend's audit log stays continuous.
+ *  - The machine JWT is short-lived (decoded `exp` checked by
+ *    `registration.ts`). Splitting it out keeps the auth file minimal and
+ *    avoids any risk of accidentally serializing the JWT into a
+ *    `spectral login` log line.
+ *
+ * Schema is intentionally minimal — Batch 3 will add capability flags;
+ * unknown fields are preserved on round-trip via `extra` so older CLIs
+ * don't strip data the backend later cares about.
+ */
+import { mkdirSync } from "node:fs";
+import { readFile, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { getConfigDir } from "../config.js";
+const KNOWN_KEYS = new Set([
+    "machineId",
+    "machineName",
+    "machineJwt",
+    "teamId",
+    "registeredAt",
+    "hostname",
+    "version",
+]);
+export function getMachineFile() {
+    return join(getConfigDir(), "machine.json");
+}
+/**
+ * Read the persisted machine record. Returns `null` when the file is
+ * missing or malformed — callers treat both as "needs registration".
+ *
+ * We intentionally do NOT throw on parse errors: a corrupted machine.json
+ * should self-heal on the next `spectral serve` (re-register, overwrite),
+ * not block startup forever.
+ */
+export async function loadMachine() {
+    let raw;
+    try {
+        raw = await readFile(getMachineFile(), "utf8");
+    }
+    catch {
+        return null;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+    if (typeof parsed.machineId !== "string" ||
+        typeof parsed.machineName !== "string" ||
+        typeof parsed.machineJwt !== "string" ||
+        typeof parsed.registeredAt !== "number" ||
+        typeof parsed.hostname !== "string" ||
+        typeof parsed.version !== "string") {
+        return null;
+    }
+    const extra = {};
+    for (const [k, v] of Object.entries(parsed)) {
+        if (!KNOWN_KEYS.has(k))
+            extra[k] = v;
+    }
+    return {
+        machineId: parsed.machineId,
+        machineName: parsed.machineName,
+        machineJwt: parsed.machineJwt,
+        teamId: typeof parsed.teamId === "string" ? parsed.teamId : undefined,
+        registeredAt: parsed.registeredAt,
+        hostname: parsed.hostname,
+        version: parsed.version,
+        extra: Object.keys(extra).length > 0 ? extra : undefined,
+    };
+}
+/**
+ * Write the machine record with restrictive permissions. Creates the
+ * config directory if missing (matches `writeConfig` in `config.ts`).
+ *
+ * Atomicity: we do NOT write-then-rename. The record is small, the file
+ * is single-writer (one `spectral serve` at a time per `$SPECTRAL_CONFIG_DIR`),
+ * and a torn write self-heals via `loadMachine` returning null + re-register.
+ */
+export async function saveMachine(rec) {
+    const file = getMachineFile();
+    mkdirSync(dirname(file), { recursive: true, mode: 0o700 });
+    // Reassemble: known fields in stable order, then any forward-compat keys.
+    const toWrite = {
+        machineId: rec.machineId,
+        machineName: rec.machineName,
+        machineJwt: rec.machineJwt,
+        registeredAt: rec.registeredAt,
+        hostname: rec.hostname,
+        version: rec.version,
+    };
+    if (rec.teamId !== undefined)
+        toWrite.teamId = rec.teamId;
+    if (rec.extra) {
+        for (const [k, v] of Object.entries(rec.extra))
+            toWrite[k] = v;
+    }
+    await writeFile(file, JSON.stringify(toWrite, null, 2) + "\n", {
+        mode: 0o600,
+        encoding: "utf8",
+    });
+}