@aexol/spectral 0.0.1

package/dist/relay/models-fetch.js

@@ -0,0 +1,108 @@
+/**
+ * Fetch the admin-managed list of allowed base models from the backend.
+ *
+ * Used by `PiBridge` at startup to register synthetic providers
+ * (`spectral-proxy-anthropic` / `spectral-proxy-openai`) that route every
+ * inference call through the backend's `/v1/messages` and
+ * `/v1/chat/completions` endpoints. The backend authenticates the call
+ * with the machine JWT (Bearer) and forwards to the upstream provider
+ * using its own (centralized) API keys.
+ *
+ * Why GraphQL (not REST):
+ *  - The backend already exposes the whitelist via `availableBaseModels`
+ *    in its public GraphQL schema (`schema.graphql`); there is no
+ *    equivalent REST endpoint and we don't want to add one just for the
+ *    CLI.
+ *  - The query is parameterless and authenticated via the same Bearer
+ *    machine JWT used by `/v1/*`, so a single `fetch` call is enough —
+ *    no Zeus client setup required.
+ *
+ * Caching:
+ *  - In-memory TTL cache (default 5 min), keyed by `${backendUrl}|${jwt}`.
+ *    Pi sessions are short-lived but a single `spectral serve` process
+ *    creates many of them, so we don't want to hammer the GraphQL
+ *    endpoint on every reconnect.
+ */
+const cache = new Map();
+/** Test-only helper: drops every cached entry. */
+export function clearAllowedModelsCache() {
+    cache.clear();
+}
+const QUERY = `query AvailableBaseModels { availableBaseModels { name provider userModelId agentEnabled } }`;
+/**
+ * Fetch the whitelist of allowed base models. Throws on any failure with a
+ * message tailored for an operator running `spectral serve` — the caller
+ * (PiBridge.start) lets the throw propagate so the WS subscriber sees a
+ * clear error event instead of a silent fall-through to "no models".
+ */
+export async function fetchAllowedModels(opts) {
+    const ttlMs = opts.cacheTtlMs ?? 5 * 60 * 1000;
+    const key = `${opts.backendUrl}|${opts.machineJwt}`;
+    if (!opts.bypassCache) {
+        const hit = cache.get(key);
+        if (hit && Date.now() - hit.fetchedAt < hit.ttlMs) {
+            return hit.models;
+        }
+    }
+    const fetchImpl = opts.fetchImpl ?? fetch;
+    const url = `${opts.backendUrl.replace(/\/$/, "")}/graphql`;
+    let res;
+    try {
+        res = await fetchImpl(url, {
+            method: "POST",
+            headers: {
+                Authorization: `Bearer ${opts.machineJwt}`,
+                "Content-Type": "application/json",
+            },
+            body: JSON.stringify({ query: QUERY }),
+        });
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        throw new Error(`Failed to fetch allowed models from backend (${url}): ${msg}. ` +
+            `Check SPECTRAL_BACKEND_URL and machine JWT.`);
+    }
+    if (!res.ok) {
+        let detail = "";
+        try {
+            detail = await res.text();
+        }
+        catch {
+            // ignore
+        }
+        throw new Error(`Failed to fetch allowed models from backend (HTTP ${res.status} ${res.statusText})` +
+            (detail ? `: ${detail.slice(0, 500)}` : "") +
+            ". Check SPECTRAL_BACKEND_URL and machine JWT.");
+    }
+    let payload;
+    try {
+        payload = (await res.json());
+    }
+    catch (err) {
+        throw new Error(`Failed to fetch allowed models: backend returned non-JSON (${err instanceof Error ? err.message : String(err)})`);
+    }
+    if (payload.errors && payload.errors.length > 0) {
+        const msg = payload.errors
+            .map((e) => (typeof e?.message === "string" ? e.message : "unknown"))
+            .join("; ");
+        throw new Error(`Failed to fetch allowed models: GraphQL errors: ${msg}`);
+    }
+    const rows = payload.data?.availableBaseModels;
+    if (!Array.isArray(rows)) {
+        throw new Error(`Failed to fetch allowed models: response missing availableBaseModels array`);
+    }
+    const models = [];
+    for (const row of rows) {
+        const name = typeof row?.name === "string" ? row.name : null;
+        const provider = typeof row?.provider === "string" ? row.provider : null;
+        if (!name || !provider)
+            continue; // skip malformed rows defensively
+        const model = { modelId: name, displayName: name, provider };
+        if (typeof row?.userModelId === "string") {
+            model.userModelId = row.userModelId;
+        }
+        models.push(model);
+    }
+    cache.set(key, { fetchedAt: Date.now(), ttlMs, models });
+    return models;
+}

package/dist/relay/registration.js

@@ -0,0 +1,135 @@
+/**
+ * Machine registration with the Aexol backend.
+ *
+ * Contract (Batch 1 backend):
+ *   POST <backend>/api/machines/register
+ *     Headers: Authorization: Bearer <teamApiKey>
+ *     Body:    { name?: string, hostname: string, version: string, pid: number }
+ *     200:     { machineId: string, jwt: string, name: string }
+ *
+ * Why this lives in its own module:
+ *  - It's the ONLY consumer of the team API key. Once registration succeeds,
+ *    the team key is dropped on the floor — only the short-lived `machineJwt`
+ *    is persisted (in `machine.json`) and threaded into `RelayClient`. Keeps
+ *    the blast radius of an in-memory leak minimal.
+ *  - It owns JWT expiry decoding so `serve.ts` doesn't have to know about
+ *    JWT internals; a single boundary for "is the saved record still good".
+ *
+ * Failure mode: registration is fail-fast (no retry). The user is sitting
+ * at a CLI prompt; if their team key is wrong or the backend is down, the
+ * right answer is a clear error message, not a hang. WS reconnect (which
+ * IS retried) is the long-running path; that's `RelayClient`'s job.
+ */
+import { hostname } from "node:os";
+import { loadMachine, saveMachine } from "./machine-store.js";
+/**
+ * Decode the `exp` claim of a JWT without verifying the signature.
+ * We're not using this for AuthN — only for "should we re-register
+ * proactively". The backend is the source of truth on validity; if our
+ * cheap pre-check is wrong, the WS handshake will reject and we'll fall
+ * through to a full re-register on the next `spectral serve`.
+ *
+ * Returns `null` if the token isn't a parseable JWT or has no `exp`.
+ */
+export function decodeJwtExp(jwt) {
+    const parts = jwt.split(".");
+    if (parts.length < 2)
+        return null;
+    try {
+        // base64url -> base64. Node 20's Buffer accepts 'base64url' directly.
+        const payloadJson = Buffer.from(parts[1], "base64url").toString("utf8");
+        const payload = JSON.parse(payloadJson);
+        return typeof payload.exp === "number" ? payload.exp : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** True when the JWT is past expiry (with skew). Treats undecodable as expired. */
+export function isJwtExpired(jwt, skewSec = 60) {
+    const exp = decodeJwtExp(jwt);
+    if (exp === null)
+        return true;
+    return Date.now() / 1000 + skewSec >= exp;
+}
+/**
+ * Ensure a machine is registered. Returns the record either from the cached
+ * `machine.json` (when the JWT is still fresh) or from a freshly issued one.
+ *
+ * Re-registration triggers:
+ *   - No `machine.json` on disk (first run).
+ *   - The cached JWT is expired or near-expired.
+ *
+ * Why we don't re-register on `--machine-name` change: the CLI flag controls
+ * the *next* registration's display name, but switching it shouldn't burn a
+ * fresh `machineId` on every restart. If users want a clean break they can
+ * delete `machine.json`.
+ */
+export async function ensureMachineRegistered(deps) {
+    const skew = deps.expirySkewSec ?? 60;
+    const existing = await loadMachine();
+    if (existing && !isJwtExpired(existing.machineJwt, skew)) {
+        return { reused: true, record: existing };
+    }
+    const fetchImpl = deps.fetchImpl ?? fetch;
+    const url = `${deps.backendUrl.replace(/\/$/, "")}/api/machines/register`;
+    const body = {
+        // Reuse the cached display name on JWT-expiry refresh so the backend's
+        // machine list stays stable; only on a clean install do we fall back to
+        // hostname or the CLI override.
+        name: deps.machineNameOverride ?? existing?.machineName ?? hostname(),
+        hostname: hostname(),
+        version: deps.version,
+        pid: deps.pid ?? process.pid,
+    };
+    let res;
+    try {
+        res = await fetchImpl(url, {
+            method: "POST",
+            headers: {
+                Authorization: `Bearer ${deps.apiKey}`,
+                "Content-Type": "application/json",
+            },
+            body: JSON.stringify(body),
+        });
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        throw new Error(`Failed to reach backend at ${url}: ${msg}`);
+    }
+    if (!res.ok) {
+        let detail = "";
+        try {
+            detail = await res.text();
+        }
+        catch {
+            // ignore
+        }
+        throw new Error(`Machine registration failed (${res.status} ${res.statusText})` +
+            (detail ? `: ${detail.slice(0, 500)}` : ""));
+    }
+    let payload;
+    try {
+        payload = await res.json();
+    }
+    catch (err) {
+        throw new Error(`Machine registration: backend returned non-JSON (${err instanceof Error ? err.message : String(err)})`);
+    }
+    const obj = payload;
+    if (typeof obj.machineId !== "string" ||
+        typeof obj.jwt !== "string" ||
+        typeof obj.name !== "string") {
+        throw new Error(`Machine registration: backend response missing required fields (machineId, jwt, name)`);
+    }
+    const record = {
+        machineId: obj.machineId,
+        machineName: obj.name,
+        machineJwt: obj.jwt,
+        teamId: typeof obj.teamId === "string" ? obj.teamId : undefined,
+        registeredAt: Date.now(),
+        hostname: hostname(),
+        version: deps.version,
+    };
+    await saveMachine(record);
+    return { reused: false, record };
+}

package/dist/server/handlers/errors.js

@@ -0,0 +1,34 @@
+/**
+ * Typed errors thrown by REST handlers.
+ *
+ * Each error carries a stable `code` that the relay envelope dispatcher
+ * (Batch 3) maps to a wire-level status. Until then, the handlers throw
+ * and the relay loop just acks — Batch 3 will catch and translate.
+ *
+ * Why typed errors instead of returning `{ ok: false, code }` discriminated
+ * unions? Two reasons:
+ *  - The handlers are also called directly from unit tests; `throw` lets
+ *    tests use `expect(...).rejects.toThrow(NotFoundError)` ergonomically.
+ *  - The Batch 3 dispatcher needs a single `try/catch` boundary; a sum
+ *    type per handler would force every handler to return its own variant.
+ */
+export class HandlerError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "HandlerError";
+    }
+}
+export class BadRequestError extends HandlerError {
+    constructor(message) {
+        super("BAD_REQUEST", message);
+        this.name = "BadRequestError";
+    }
+}
+export class NotFoundError extends HandlerError {
+    constructor(message) {
+        super("NOT_FOUND", message);
+        this.name = "NotFoundError";
+    }
+}

package/dist/server/handlers/projects.js

@@ -0,0 +1,86 @@
+/**
+ * Pure REST handlers for `/api/projects/*`.
+ *
+ * Extracted from the deleted Hono `routes.ts` so the relay envelope dispatcher
+ * (Batch 3) can call them with a parsed payload instead of a Hono context.
+ *
+ * Contract:
+ *  - Inputs are already-parsed JSON objects (or `unknown` shapes the handler
+ *    validates). The dispatcher upstream parses the relay envelope body.
+ *  - Outputs are the wire shapes the landing client already expects, so the
+ *    Batch 3 dispatcher can JSON-stringify them straight into the response
+ *    envelope without remapping.
+ *  - Errors are thrown as typed `HandlerError` subclasses; the dispatcher
+ *    maps `BAD_REQUEST` → 400-equivalent and `NOT_FOUND` → 404-equivalent.
+ *  - Stream teardown on project delete is the caller's responsibility — the
+ *    handler returns the cascaded session ids so the dispatcher can hand
+ *    them to `SessionStreamManager.disposeProjectStreams` BEFORE the SQL
+ *    cascade has already torn down (in our model the cascade has already
+ *    happened by the time we return; that's intentional and matches the
+ *    old route's ordering — the manager is best-effort cleanup).
+ */
+import { validateProjectPath } from "../paths.js";
+import { BadRequestError, NotFoundError } from "./errors.js";
+export function handleListProjects(store) {
+    return store.listProjects();
+}
+export function handleCreateProject(store, body) {
+    if (typeof body.name !== "string" || !body.name.trim()) {
+        throw new BadRequestError("name (non-empty string) is required");
+    }
+    if (typeof body.path !== "string" || !body.path.trim()) {
+        throw new BadRequestError("path (non-empty string) is required");
+    }
+    const validation = validateProjectPath(body.path);
+    if (!validation.ok) {
+        throw new BadRequestError(validation.error ?? "Invalid path");
+    }
+    return store.createProject({ name: body.name, path: validation.path });
+}
+export function handleGetProject(store, id) {
+    const project = store.getProject(id);
+    if (!project)
+        throw new NotFoundError("Project not found");
+    return project;
+}
+export function handleUpdateProject(store, id, body) {
+    const update = {};
+    if (body.name !== undefined) {
+        if (typeof body.name !== "string") {
+            throw new BadRequestError("name must be a string");
+        }
+        update.name = body.name;
+    }
+    if (body.path !== undefined) {
+        if (typeof body.path !== "string") {
+            throw new BadRequestError("path must be a string");
+        }
+        const validation = validateProjectPath(body.path);
+        if (!validation.ok) {
+            throw new BadRequestError(validation.error ?? "Invalid path");
+        }
+        update.path = validation.path;
+    }
+    if (update.name === undefined && update.path === undefined) {
+        throw new BadRequestError("At least one of name, path must be provided");
+    }
+    const updated = store.updateProject(id, update);
+    if (!updated)
+        throw new NotFoundError("Project not found");
+    return updated;
+}
+export function handleDeleteProject(store, id) {
+    const project = store.getProject(id);
+    if (!project)
+        throw new NotFoundError("Project not found");
+    const result = store.deleteProject(id);
+    if (!result.deleted)
+        throw new NotFoundError("Project not found");
+    return { sessionIds: result.sessionIds };
+}
+export function handleListSessionsByProject(store, id) {
+    const project = store.getProject(id);
+    if (!project)
+        throw new NotFoundError("Project not found");
+    return store.listSessionsByProject(id);
+}

package/dist/server/handlers/sessions.js

@@ -0,0 +1,42 @@
+/**
+ * Pure REST handlers for `/api/sessions/*`.
+ *
+ * Same shape as projects handlers — see that file's header for the contract.
+ *
+ * Note: session deletion does not tear down the in-flight pi stream itself.
+ * The Batch 3 dispatcher must call `manager.disposeSessionStream(id)` BEFORE
+ * invoking `handleDeleteSession` so the FK cascade doesn't leave a zombie
+ * bridge driving events at a row that no longer exists. This matches the
+ * ordering the old Hono route used.
+ */
+import { BadRequestError, NotFoundError } from "./errors.js";
+export function handleCreateSession(store, body) {
+    if (typeof body.projectId !== "string" || !body.projectId) {
+        throw new BadRequestError("projectId (string) is required");
+    }
+    const project = store.getProject(body.projectId);
+    if (!project)
+        throw new BadRequestError("Unknown projectId");
+    const title = typeof body.title === "string" ? body.title : undefined;
+    return store.createSession({ projectId: body.projectId, title });
+}
+export function handleGetSessionDetail(store, id) {
+    const detail = store.getSession(id);
+    if (!detail)
+        throw new NotFoundError("Session not found");
+    return detail;
+}
+export function handleUpdateSession(store, id, body) {
+    if (typeof body.title !== "string") {
+        throw new BadRequestError("title (string) is required");
+    }
+    const updated = store.renameSession(id, body.title);
+    if (!updated)
+        throw new NotFoundError("Session not found");
+    return updated;
+}
+export function handleDeleteSession(store, id) {
+    const deleted = store.deleteSession(id);
+    if (!deleted)
+        throw new NotFoundError("Session not found");
+}

package/dist/server/paths.js

@@ -0,0 +1,78 @@
+/**
+ * Filesystem path helpers for project management.
+ *
+ * Projects in `spectral serve` are user-owned directories on disk. We accept
+ * paths typed by the user from the browser, so two small concerns:
+ *
+ *  - Tilde expansion: `~/foo/bar` is the natural way to refer to a path
+ *    inside `$HOME`. Node's `path` module does not expand tildes; we do it
+ *    ourselves with a leading-segment check (NOT a global string replace —
+ *    `~user/...` and embedded `~` are intentionally left alone).
+ *  - Validation: the path must exist, must be a directory, and must be
+ *    readable. We do NOT attempt to verify writability — pi may want to
+ *    create files inside it, but failure modes there surface naturally
+ *    through pi's tools, and a write probe here would create stray files.
+ *
+ * Both helpers are synchronous because they're called on hot HTTP paths
+ * (POST /api/projects) where blocking is acceptable: the operation is rare
+ * and the user is waiting on the response anyway. `node:fs` sync calls in
+ * this regime are simpler than juggling promises through validation.
+ */
+import { existsSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { isAbsolute, resolve, sep } from "node:path";
+/**
+ * Expand a leading `~` or `~/` to the user's home directory and return an
+ * absolute, normalized path.
+ *
+ * Behavior:
+ *   - `~`           → `$HOME`
+ *   - `~/foo`       → `$HOME/foo`
+ *   - `/abs/path`   → `/abs/path` (unchanged, normalized)
+ *   - `relative`    → resolved against `$HOME` (NOT process.cwd, since the
+ *     server runs from `$HOME` and "relative to home" matches the user's
+ *     mental model when typing into a form)
+ *   - `~user/...`   → returned as-is and resolved against `$HOME`. We do NOT
+ *     attempt to look up other users' home directories — out of scope.
+ */
+export function expandPath(input) {
+    const trimmed = input.trim();
+    if (!trimmed)
+        return homedir();
+    // Tilde expansion — leading-segment only. `~` alone or `~/...`.
+    if (trimmed === "~")
+        return homedir();
+    if (trimmed.startsWith("~/") || trimmed.startsWith(`~${sep}`)) {
+        return resolve(homedir(), trimmed.slice(2));
+    }
+    if (isAbsolute(trimmed))
+        return resolve(trimmed);
+    // Relative path → resolve against $HOME. Matches the form-typing UX where
+    // a user enters `projects/foo` expecting `~/projects/foo`.
+    return resolve(homedir(), trimmed);
+}
+/**
+ * Validate a user-supplied project path.
+ *
+ * Returns `{ok:true, path}` for a real, accessible directory. On failure,
+ * `error` carries a message suitable for surfacing to the user. The expanded
+ * path is included in both cases so callers can echo it back in errors.
+ */
+export function validateProjectPath(input) {
+    const path = expandPath(input);
+    let st;
+    try {
+        if (!existsSync(path)) {
+            return { ok: false, path, error: `Path does not exist: ${path}` };
+        }
+        st = statSync(path);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return { ok: false, path, error: `Cannot access path: ${msg}` };
+    }
+    if (!st.isDirectory()) {
+        return { ok: false, path, error: `Path is not a directory: ${path}` };
+    }
+    return { ok: true, path };
+}