@m6d/cortex-cli 0.17.0 → 0.19.0

package/src/contracts/management/index.ts

@@ -0,0 +1,169 @@
+import { z } from "zod";
+
+import { isRecord } from "../json/index";
+import { managementProcedureKinds } from "./procedures.generated";
+import type { ManagementProcedures } from "./procedures.generated";
+
+/*
+ * Cortex's management API as a caller reaches it: one REST operation per
+ * console procedure under `/api/management`, a query as GET with its input
+ * on the query string, a mutation as POST with its input as the JSON body,
+ * and a management key as the bearer. The console routes a procedure by
+ * `managementPath`; the CLI and the TypeScript SDK call through
+ * `callManagement`, and M6d.Cortex spells the same rules in C#.
+ * `management.fixtures.json` holds every caller to the same requests and
+ * refusals. `createManagementClient` types each call from
+ * `procedures.generated.ts`, which the console prints from its procedures.
+ */
+
+/** Where a console serves the management API. */
+export const MANAGEMENT_BASE_PATH = "/api/management";
+
+/** A procedure's REST path: its tRPC path, kebab-cased (`managementKeys.mine` is `/management-keys/mine`). */
+export function managementPath(procedure: string) {
+    const kebab = procedure.replace(/[A-Z]/g, (upper) => `-${upper.toLowerCase()}`);
+    return `/${kebab.replaceAll(".", "/")}`;
+}
+
+function isScalar(value: unknown): value is string | number | boolean | null {
+    return value === null || ["string", "number", "boolean"].includes(typeof value);
+}
+
+/**
+ * A query's input on the query string, one parameter per field: a scalar as
+ * itself, a non-empty array of scalars as a repeated parameter, anything
+ * else as JSON, as the document declares each field; "" for none.
+ */
+function managementQuery(input: Record<string, unknown>) {
+    const params = new URLSearchParams();
+    for (const [name, value] of Object.entries(input)) {
+        if (value === undefined) continue;
+        if (isScalar(value)) params.set(name, String(value));
+        else if (Array.isArray(value) && value.length > 0 && value.every(isScalar)) {
+            for (const item of value) params.append(name, String(item));
+        } else params.set(name, JSON.stringify(value));
+    }
+    const encoded = params.toString();
+    return encoded === "" ? "" : `?${encoded}`;
+}
+
+/** The body a refusal answers with, each field kept only when it has its documented shape. */
+const refusalBodySchema = z.object({
+    code: z.string().optional().catch(undefined),
+    message: z.string().optional().catch(undefined),
+    refusal: z.string().optional().catch(undefined),
+    cause: z.record(z.string(), z.unknown()).optional().catch(undefined),
+});
+
+/**
+ * Cortex refused a management call: `code` is the tRPC code (`FORBIDDEN`),
+ * the message the refusal's literal (`read_only`), `detail` what the refusal
+ * names when it names something (`{ error, fields }`), and `refusal` the
+ * sentence Cortex words it in, when it has one. A body that is no refusal
+ * (a proxy's error page) reads as code `error` with the status text.
+ */
+export class ManagementClientError extends Error {
+    public constructor(
+        public readonly status: number,
+        public readonly code: string,
+        message: string,
+        public readonly detail?: Record<string, unknown>,
+        public readonly refusal?: string,
+    ) {
+        super(message);
+        this.name = "ManagementClientError";
+    }
+}
+
+/** Where management calls go: a console's origin and a management key (`cortex_mgmt_…`); a test hands in its own `fetch`. */
+export type ManagementTarget = {
+    url: string;
+    key: string;
+    fetch?: (url: string, init: RequestInit) => Promise<Response>;
+};
+
+/**
+ * One management call by REST route, answering the procedure's output as
+ * parsed JSON. A refusal throws `ManagementClientError`; a Cortex that cannot
+ * be reached, or a success body that cannot be read, rejects as `fetch` and
+ * `Response.json` do.
+ */
+export async function callManagement(
+    target: ManagementTarget,
+    request: { method: "get" | "post"; path: string; input?: unknown; signal?: AbortSignal },
+) {
+    const { method, path, input, signal } = request;
+    const query = method === "get" && isRecord(input) ? managementQuery(input) : "";
+    const url = `${target.url.replace(/\/+$/, "")}${MANAGEMENT_BASE_PATH}${path}${query}`;
+    const response = await (target.fetch ?? globalThis.fetch)(url, {
+        method: method.toUpperCase(),
+        headers: {
+            Authorization: `Bearer ${target.key}`,
+            ...(method === "post" ? { "Content-Type": "application/json" } : {}),
+        },
+        body: method === "post" && input !== undefined ? JSON.stringify(input) : undefined,
+        signal,
+    });
+    // A success that cannot be read is the caller's failure, never a null result.
+    if (response.ok) {
+        const output: unknown = await response.json();
+        return output;
+    }
+    const body: unknown = await response.json().catch(() => null);
+    const refused = refusalBodySchema.safeParse(body).data ?? {};
+    throw new ManagementClientError(
+        response.status,
+        refused.code ?? "error",
+        refused.message ?? response.statusText,
+        refused.cause,
+        refused.refusal,
+    );
+}
+
+type ManagementProcedure = keyof ManagementProcedures;
+
+/** What procedure `P` takes, as it is sent. */
+export type ManagementInput<P extends ManagementProcedure> = ManagementProcedures[P]["input"];
+
+/** What procedure `P` answers, as JSON carries it: a date is its ISO string. */
+export type ManagementOutput<P extends ManagementProcedure> = ManagementProcedures[P]["output"];
+
+type CallOptions = { signal?: AbortSignal };
+
+/** Procedure `P` as a call; its input may be left out when it takes none, or nothing it requires. */
+type Call<P extends ManagementProcedure> =
+    Partial<ManagementInput<P>> extends ManagementInput<P>
+        ? (input?: ManagementInput<P>, options?: CallOptions) => Promise<ManagementOutput<P>>
+        : (input: ManagementInput<P>, options?: CallOptions) => Promise<ManagementOutput<P>>;
+
+/** Every procedure as `client.<router>.<procedure>`, as the API documents it. */
+export type ManagementClient = {
+    [R in ManagementProcedure extends `${infer Router}.${string}` ? Router : never]: {
+        [P in ManagementProcedure as P extends `${R}.${infer Name}` ? Name : never]: Call<P>;
+    };
+};
+
+/**
+ * A typed management client: `client.agents.saveSettings({ id, greeting })`
+ * sends the procedure's request, a GET or a POST as its kind is, and answers
+ * its output. A refusal throws `ManagementClientError`.
+ */
+export function createManagementClient(target: ManagementTarget) {
+    const client: Record<
+        string,
+        Record<string, (input?: unknown, options?: CallOptions) => Promise<unknown>>
+    > = {};
+    for (const [procedure, kind] of Object.entries(managementProcedureKinds)) {
+        const [router = "", name = ""] = procedure.split(".");
+        (client[router] ??= {})[name] = (input, options) =>
+            callManagement(target, {
+                method: kind === "query" ? "get" : "post",
+                path: managementPath(procedure),
+                input,
+                signal: options?.signal,
+            });
+    }
+    // The table of kinds and the procedure map are printed from one model, so
+    // each call built here is the one its type names.
+    return client as ManagementClient;
+}