@aexol/spectral 0.9.230 → 0.9.231

package/dist/relay/rest.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Relay REST request handler (CLI side).
+ *
+ * Translates an inbound `RestRequestFrame` into a `dispatchRoute` call and
+ * maps handler errors to status codes (400/404/500). Errors thrown by
+ * handlers are 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.
+ *
+ * Extracted from `relay/dispatcher.ts` — the dispatcher re-exports
+ * `handleRestRequest` so existing imports keep working.
+ */
+import type { RestRequestFrame, RestResponseFrame } from "@aexol/relay-protocol";
+import { type RestRequestDeps } from "./routing.js";
+/**
+ * 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 declare function handleRestRequest(frame: RestRequestFrame, deps: RestRequestDeps): Promise<RestResponseFrame>;
+//# sourceMappingURL=rest.d.ts.map

package/dist/relay/rest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rest.d.ts","sourceRoot":"","sources":["../../src/relay/rest.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EACV,gBAAgB,EAChB,iBAAiB,EAClB,MAAM,uBAAuB,CAAC;AAG/B,OAAO,EAA6B,KAAK,eAAe,EAAE,MAAM,cAAc,CAAC;AAE/E;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,iBAAiB,CACrC,KAAK,EAAE,gBAAgB,EACvB,IAAI,EAAE,eAAe,GACpB,OAAO,CAAC,iBAAiB,CAAC,CAoE5B"}

package/dist/relay/rest.js

@@ -0,0 +1,85 @@
+/**
+ * Relay REST request handler (CLI side).
+ *
+ * Translates an inbound `RestRequestFrame` into a `dispatchRoute` call and
+ * maps handler errors to status codes (400/404/500). Errors thrown by
+ * handlers are 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.
+ *
+ * Extracted from `relay/dispatcher.ts` — the dispatcher re-exports
+ * `handleRestRequest` so existing imports keep working.
+ */
+import { BadRequestError, NotFoundError } from "../server/handlers/errors.js";
+import { dispatchRoute, matchRoute } from "./routing.js";
+/**
+ * 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 async function handleRestRequest(frame, deps) {
+    const { reqId, method, path, body } = frame;
+    const logger = deps.logger ?? console;
+    const startedAt = performance.now();
+    logger.info?.(`[rest] start machineId=${frame.machineId} method=${method} path=${path} reqId=${reqId}`);
+    const match = matchRoute(method, path);
+    if (!match) {
+        logger.info?.(`[rest] finish machineId=${frame.machineId} method=${method} path=${path} reqId=${reqId} status=404 durationMs=${Math.round(performance.now() - startedAt)}`);
+        return {
+            kind: "rest_response",
+            reqId,
+            status: 404,
+            body: { error: `Unknown route: ${method} ${path}` },
+        };
+    }
+    try {
+        const result = await dispatchRoute(match, body, deps);
+        logger.info?.(`[rest] finish machineId=${frame.machineId} method=${method} path=${path} reqId=${reqId} status=200 durationMs=${Math.round(performance.now() - startedAt)}`);
+        return {
+            kind: "rest_response",
+            reqId,
+            status: 200,
+            body: result,
+        };
+    }
+    catch (err) {
+        if (err instanceof BadRequestError) {
+            logger.info?.(`[rest] finish machineId=${frame.machineId} method=${method} path=${path} reqId=${reqId} status=400 durationMs=${Math.round(performance.now() - startedAt)}`);
+            return {
+                kind: "rest_response",
+                reqId,
+                status: 400,
+                body: { error: err.message, code: err.code },
+            };
+        }
+        if (err instanceof NotFoundError) {
+            logger.info?.(`[rest] finish machineId=${frame.machineId} method=${method} path=${path} reqId=${reqId} status=404 durationMs=${Math.round(performance.now() - startedAt)}`);
+            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);
+        logger.info?.(`[rest] finish machineId=${frame.machineId} method=${method} path=${path} reqId=${reqId} status=500 durationMs=${Math.round(performance.now() - startedAt)}`);
+        return {
+            kind: "rest_response",
+            reqId,
+            status: 500,
+            body: { error: "Internal error" },
+        };
+    }
+}

package/dist/relay/routing.d.ts

@@ -0,0 +1,109 @@
+/**
+ * Relay route table (CLI side).
+ *
+ * `matchRoute` is the pure path matcher translating `method + path` into a
+ * `RouteMatch`; `dispatchRoute` is the inner switch that calls the pure REST
+ * handlers (`handlers/projects.ts`, `handlers/sessions.ts`, ...). Extracted
+ * from `relay/dispatcher.ts` — `handleRestRequest` (`relay/rest.ts`) owns the
+ * single try/catch boundary around `dispatchRoute`, and the dispatcher
+ * re-exports `matchRoute` + the request-deps types so existing imports keep
+ * working.
+ */
+import type { MetaEvent } from "@aexol/relay-protocol";
+import type { McpExtensionState } from "../mcp/state.js";
+import type { SessionStreamManager } from "../server/session-stream.js";
+import type { DevProcessRegistry } from "../server/dev-process-registry.js";
+import type { SessionStore } from "../server/storage.js";
+import { type WizardLoginResult } from "./wizard-login.js";
+/**
+ * Result of matching a request path against a route table entry.
+ * `id` is populated when the route had an `:id` placeholder.
+ */
+interface RouteMatch {
+    route: "list_projects" | "create_project" | "update_project" | "delete_project" | "bind_studio" | "unbind_studio" | "get_project_observations" | "list_project_sessions" | "cleanup_project_sessions" | "cleanup_all_sessions" | "create_session" | "get_session" | "get_session_active_agent" | "update_session_active_agent" | "get_session_messages" | "update_session" | "delete_session" | "get_session_memory" | "get_session_memory_details" | "compact_session" | "remember_and_delete_session" | "fork_session" | "list_path_autocomplete" | "list_directory" | "get_home_directory" | "search_project_files" | "enqueue_prompt" | "get_prompt_queue" | "remove_prompt" | "clear_prompt_queue" | "list_mcp_status" | "reload_mcp_config" | "refresh_native_extensions" | "refresh_cloud_agents" | "get_settings" | "put_settings" | "get_agent_settings" | "put_agent_settings" | "get_prompt_mutation_settings" | "put_prompt_mutation_settings" | "wizard_login" | "list_agents" | "list_dev_processes" | "start_dev_process" | "kill_dev_process" | "restart_dev_process" | "scan_dev_servers" | "kill_dev_server";
+    id?: string;
+    /** Parsed query params, if the path carried a `?...` suffix. */
+    query?: URLSearchParams;
+    /** For `remove_prompt`: the queue item id extracted from the path. */
+    itemId?: string;
+    /** For `kill_dev_server`: optional target port from the query string. */
+    port?: number;
+}
+/**
+ * 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 ~11 routes.
+ */
+export declare function matchRoute(method: string, path: string): RouteMatch | null;
+/**
+ * Best-effort publisher for project/session lifecycle meta events. Bound
+ * by `serve.ts` to `relay.send({kind:"meta_event", machineId, event})`;
+ * tests pass a recording stub. Always called inside a try/catch by the
+ * dispatcher so a publish failure never breaks the REST response — the
+ * mutation already succeeded.
+ *
+ * Omit (`undefined`) to disable publishing entirely (used in the handler
+ * unit tests where there's no relay).
+ */
+export type PublishMetaEvent = (event: MetaEvent) => void;
+export interface RestRequestDeps {
+    store: SessionStore;
+    manager: SessionStreamManager;
+    /** Working directory for this machine. Used by settings persistence. Defaults to homedir. */
+    cwd?: string;
+    /** Agent config dir (`~/.spectral/agent` by default). Passed through to agent-settings persistence. */
+    agentDir?: string;
+    /**
+     * Optional logger for unexpected errors and per-request timing.
+     * Defaults to `console`; optional methods are guarded so a minimal
+     * `{ error }` logger (used by tests) remains valid.
+     */
+    logger?: {
+        error?: (...args: unknown[]) => void;
+        info?: (...args: unknown[]) => void;
+    };
+    /**
+     * Optional MCP extension state. Passed through by `serve.ts` from the
+     * `AgentBridge`. When set, `GET /api/mcp-status` returns the current
+     * machine-local MCP snapshot.
+     */
+    mcpState?: McpExtensionState;
+    /** Machine-level dev process registry. Used by `/api/dev-processes`. */
+    devProcessRegistry?: DevProcessRegistry;
+    /**
+     * Optional meta-event publisher. Invoked AFTER each successful mutation
+     * (create/update/delete project, create/update/delete session) so all
+     * tabs of all browsers subscribed to this machine refetch. Read paths
+     * (`list_*`, `get_*`) never publish.
+     *
+     * Failure handling: any throw is caught + logged; we never propagate
+     * publish failures into the REST response (the SQLite mutation has
+     * already committed and the caller deserves the success it asked for).
+     */
+    publishMetaEvent?: PublishMetaEvent;
+    refreshNativeExtensions?: () => Promise<void>;
+    /**
+     * Refresh the cloud-agent cache. Returns a result describing whether the
+     * backend rejected auth; callers that just need a cache warm may ignore it
+     * (the bridge handles auth-rejection separately via onCloudAgentsAuthRejected).
+     */
+    refreshCloudAgents?: (teamId: string) => Promise<unknown>;
+    startWizardLogin?: () => Promise<WizardLoginResult>;
+}
+/**
+ * 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.
+ */
+export declare function dispatchRoute(match: RouteMatch, body: unknown, deps: RestRequestDeps): Promise<unknown>;
+export {};
+//# sourceMappingURL=routing.d.ts.map

package/dist/relay/routing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"routing.d.ts","sourceRoot":"","sources":["../../src/relay/routing.ts"],"names":[],"mappings":"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"}