@m6d/cortex-cli 0.18.0 → 0.19.0

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@m6d/cortex-cli",
-    "version": "0.18.0",
+    "version": "0.19.0",
     "description": "Scaffold Cortex projects and manage a Cortex deployment",
     "license": "MIT",
     "type": "module",

package/src/commands/apply.ts

@@ -4,6 +4,11 @@ import { relative, resolve } from "node:path";
 import { Option } from "@commander-js/extra-typings";
 import type { Command } from "@commander-js/extra-typings";
 import { isRecord } from "@cortex/contracts/json";
+import {
+    callManagement,
+    ManagementClientError,
+    managementPath,
+} from "@cortex/contracts/management";
 import {
     appliedManifestSchema,
     manifestApplyInputSchema,
@@ -12,7 +17,7 @@ import {
 import { loadManifestFile } from "@cortex/contracts/manifest-file";
 import { z } from "zod";
 
-import { callManagement, ManagementError } from "@/management/client";
+import { managementTarget } from "@/management/client";
 import { callOrFail, confirmDestructive, requireProfile } from "@/commands/management";
 import { askChoice, canAsk } from "@/ui/prompts";
 import * as report from "@/ui/report";
@@ -137,7 +142,7 @@ export async function applyManifest(options: {
     const { profile, dryRun } = options;
     const answer = await sendManifest({
         ...options,
-        path: dryRun ? "/manifests/preview" : "/manifests/sync",
+        path: managementPath(dryRun ? "manifests.preview" : "manifests.sync"),
     });
     // The secrets are read apart from the changes: a sync has committed by
     // now, and a summary this CLI is too old to read must not lose them.
@@ -179,14 +184,14 @@ async function sendManifest(options: {
     const resolutions: Resolution = [];
     for (;;) {
         try {
-            return await callManagement(profile, "post", path, {
-                ...manifest,
-                prefer,
-                resolutions,
+            return await callManagement(managementTarget(profile), {
+                method: "post",
+                path,
+                input: { ...manifest, prefer, resolutions },
             });
         } catch (error) {
             const refused =
-                error instanceof ManagementError
+                error instanceof ManagementClientError
                     ? unresolvedSchema.safeParse(error.detail)
                     : undefined;
             if (!refused?.success) throw error;

package/src/commands/management.ts

@@ -3,12 +3,13 @@ import { readFileSync } from "node:fs";
 import { type Command, Option } from "@commander-js/extra-typings";
 import { canCarrySecret } from "@cortex/contracts/egress-policy";
 import { isRecord } from "@cortex/contracts/json";
+import { callManagement, ManagementClientError } from "@cortex/contracts/management";
 
 import {
-    callManagement,
     inputSchemaOf,
     loadOpenApi,
-    ManagementError,
+    managementClient,
+    managementTarget,
     UnreachableError,
 } from "@/management/client";
 import type { OpenApiDocument, OpenApiOperation } from "@/management/client";
@@ -134,14 +135,11 @@ async function login(given: string | undefined, name: string) {
  */
 async function whoami(profile: { url: string; key: string }) {
     try {
-        const me = (await callManagement(profile, "get", "/management-keys/mine", undefined)) as {
-            name: string;
-            fingerprint: string;
-        };
+        const me = await managementClient(profile).managementKeys.mine();
         return `key "${me.name}" (${me.fingerprint})`;
     } catch (error) {
-        if (error instanceof ManagementError && error.status === 401) return null;
-        if (error instanceof ManagementError) {
+        if (error instanceof ManagementClientError && error.status === 401) return null;
+        if (error instanceof ManagementClientError) {
             report.fail({
                 what: `${profile.url} answered ${error.status} ${error.code}: ${error.message}`,
             });
@@ -323,7 +321,7 @@ function registerOperation(scope: {
         const result = await callOrFail(profile, () =>
             all
                 ? walkPages(profile, method, path, body)
-                : callManagement(profile, method, path, body),
+                : callManagement(managementTarget(profile), { method, path, input: body }),
         );
         print(result, format);
         if (publisher) {
@@ -427,7 +425,11 @@ async function publishAfterWrite(
     }
     if (publish) {
         const published = await callOrFail(profile, () =>
-            callManagement(profile, publisher.method, publisher.path, { id }),
+            callManagement(managementTarget(profile), {
+                method: publisher.method,
+                path: publisher.path,
+                input: { id },
+            }),
         );
         options.note(`Published ${id}.`);
         for (const warning of warningsOf(published)) options.note(`Warning: ${warning}`);
@@ -454,7 +456,7 @@ export async function callOrFail<T>(profile: ResolvedProfile, call: () => Promis
  * rethrown.
  */
 export function failCall(profile: { url: string }, error: unknown): never {
-    if (error instanceof ManagementError) {
+    if (error instanceof ManagementClientError) {
         report.fail({
             what: `${error.status} ${error.code}: ${error.message}`,
             blocks: [
@@ -605,10 +607,10 @@ export async function walkPages(
     // Bounded: if Cortex reports more rows than it serves, the walk must not
     // spin, and a listing the bound cannot cover is an error, never a short result.
     for (let pageIndex = 0; pageIndex < MAX_PAGES; pageIndex += 1) {
-        const page = (await callManagement(profile, method, path, {
-            ...given,
-            pageIndex,
-            pageSize,
+        const page = (await callManagement(managementTarget(profile), {
+            method,
+            path,
+            input: { ...given, pageIndex, pageSize },
         })) as { items?: unknown[]; count?: number; filteredCount?: number };
         if (!Array.isArray(page.items)) return page;
         items.push(...page.items);

package/src/commands/setup.ts

@@ -12,6 +12,7 @@ import {
     normalizeHost,
     scrubCredentialStrings,
 } from "@cortex/contracts/egress-policy";
+import { ManagementClientError, managementPath } from "@cortex/contracts/management";
 import { MODEL_PROVIDER_LIMITS, NAME_MAX_LENGTH, SETTING_BOUNDS } from "@cortex/contracts/manifest";
 import { z } from "zod";
 
@@ -29,7 +30,7 @@ import {
     requireProfile,
     walkPages,
 } from "@/commands/management";
-import { callManagement, ManagementError, UnreachableError } from "@/management/client";
+import { managementClient, UnreachableError } from "@/management/client";
 import { DOCKER_HOST, EMBEDDING, withEnvValues } from "@/scaffold/files";
 import * as prompts from "@/ui/prompts";
 import * as report from "@/ui/report";
@@ -154,7 +155,7 @@ export function registerSetup(program: Command<[], { verbose?: true; profile?: s
             interactive,
             command: "bun cortex apply --yes",
         }).catch(function (error: unknown) {
-            if (error instanceof ManagementError && error.message === "chat_model_required") {
+            if (error instanceof ManagementClientError && error.message === "chat_model_required") {
                 return undefined;
             }
             return failCall(profile, error);
@@ -233,12 +234,12 @@ async function waitForCortex(profile: Profile, wait: boolean) {
     let announced = false;
     for (;;) {
         try {
-            await callManagement(profile, "get", "/secrets/list", { pageSize: 1 });
+            await managementClient(profile).secrets.list({ pageSize: 1 });
             return;
         } catch (error) {
             const starting =
                 error instanceof UnreachableError ||
-                (error instanceof ManagementError && error.status >= 500);
+                (error instanceof ManagementClientError && error.status >= 500);
             if (!starting || Date.now() >= deadline) failCall(profile, error);
             if (!announced) {
                 report.row("", `Waiting for ${profile.url}. A first start pulls the image.`);
@@ -249,24 +250,21 @@ async function waitForCortex(profile: Profile, wait: boolean) {
     }
 }
 
-function call(profile: Profile, method: "get" | "post", path: string, input: unknown) {
-    return callOrFail(profile, () => callManagement(profile, method, path, input));
-}
-
 /** The entry named exactly `name`, across every page; a listing's search matches any part of it. */
 async function findByName<TItem extends typeof namedSchema>(
     profile: Profile,
-    router: string,
+    router: "secrets" | "modelProviders" | "servers",
     name: string,
     item: TItem,
 ) {
-    const { items } = z
-        .object({ items: z.array(item) })
-        .parse(
-            await callOrFail(profile, () =>
-                walkPages(profile, "get", `/${router}/list`, { q: name, pageSize: 100 }),
-            ),
-        );
+    const { items } = z.object({ items: z.array(item) }).parse(
+        await callOrFail(profile, () =>
+            walkPages(profile, "get", managementPath(`${router}.list`), {
+                q: name,
+                pageSize: 100,
+            }),
+        ),
+    );
     return items.find((entry) => entry.name === name);
 }
 
@@ -284,7 +282,9 @@ function secretFor(owner: string, role: "api-key" | "server-key", value: string)
 
 async function ensureSecret(profile: Profile, name: string, value: string) {
     const found = await findByName(profile, "secrets", name, namedSchema);
-    if (!found) await call(profile, "post", "/secrets/set", { name, value });
+    if (!found) {
+        await callOrFail(profile, () => managementClient(profile).secrets.set({ name, value }));
+    }
 }
 
 /**
@@ -307,7 +307,7 @@ function failCallsElsewhere(what: string, calls: string | null, wanted: string,
  * write.
  */
 async function ensureProvider(profile: Profile, provider: Provider) {
-    const found = await findByName(profile, "model-providers", provider.name, providerRowSchema);
+    const found = await findByName(profile, "modelProviders", provider.name, providerRowSchema);
     if (found && found.baseUrl !== provider.baseUrl) {
         failCallsElsewhere(
             `Provider ${provider.name}`,
@@ -330,13 +330,15 @@ async function ensureProvider(profile: Profile, provider: Provider) {
     await ensureSecret(profile, secretName, provider.apiKey);
 
     if (!found) {
-        await call(profile, "post", "/model-providers/create", {
-            name: provider.name,
-            baseUrl: provider.baseUrl,
-            secretName,
-            models,
-            efforts: [],
-        });
+        await callOrFail(profile, () =>
+            managementClient(profile).modelProviders.create({
+                name: provider.name,
+                baseUrl: provider.baseUrl,
+                secretName,
+                models,
+                efforts: [],
+            }),
+        );
         report.input("Provider", `${provider.name} · created`);
         return;
     }
@@ -344,13 +346,15 @@ async function ensureProvider(profile: Profile, provider: Provider) {
         report.input("Provider", `${provider.name} · kept`);
         return;
     }
-    await call(profile, "post", "/model-providers/update", {
-        id: found.id,
-        baseUrl: found.baseUrl,
-        secretName,
-        models,
-        efforts: found.efforts,
-    });
+    await callOrFail(profile, () =>
+        managementClient(profile).modelProviders.update({
+            id: found.id,
+            baseUrl: found.baseUrl,
+            secretName,
+            models,
+            efforts: found.efforts,
+        }),
+    );
     report.input("Provider", `${provider.name} · updated`);
 }
 
@@ -369,7 +373,11 @@ async function ensureServer(
     const url = `${project.CORTEX_SERVER_URL}/cortex`;
     const found = await findByName(profile, "servers", name, namedSchema);
     const server = found
-        ? serverSchema.parse(await call(profile, "get", "/servers/get", { id: found.id }))
+        ? serverSchema.parse(
+              await callOrFail(profile, () =>
+                  managementClient(profile).servers.get({ id: found.id }),
+              ),
+          )
         : undefined;
     if (server && server.url !== url) {
         failCallsElsewhere(`Server ${name}`, server.url, url, "CORTEX_SERVER_NAME");
@@ -384,15 +392,17 @@ async function ensureServer(
     };
     if (!server) {
         const created = serverSchema.parse(
-            await call(profile, "post", "/servers/create", {
-                name,
-                description: "",
-                url,
-                keySecretName,
-                ...model,
-                signInChecksPerMinute: SETTING_BOUNDS.server.signInChecksPerMinute.default,
-                triggerChecksPerMinute: SETTING_BOUNDS.server.triggerChecksPerMinute.default,
-            }),
+            await callOrFail(profile, () =>
+                managementClient(profile).servers.create({
+                    name,
+                    description: "",
+                    url,
+                    keySecretName,
+                    ...model,
+                    signInChecksPerMinute: SETTING_BOUNDS.server.signInChecksPerMinute.default,
+                    triggerChecksPerMinute: SETTING_BOUNDS.server.triggerChecksPerMinute.default,
+                }),
+            ),
         );
         report.input("Server", `${name} · created`);
         return created;
@@ -404,22 +414,24 @@ async function ensureServer(
         return server;
     }
     const updated = serverSchema.parse(
-        await call(profile, "post", "/servers/update", {
-            id: server.id,
-            name,
-            description: server.description ?? "",
-            url,
-            keySecretName,
-            ...(takesModel
-                ? model
-                : {
-                      modelProvider: server.modelProvider,
-                      modelName: server.modelName,
-                      modelEffort: server.modelEffort,
-                  }),
-            signInChecksPerMinute: server.signInChecksPerMinute,
-            triggerChecksPerMinute: server.triggerChecksPerMinute,
-        }),
+        await callOrFail(profile, () =>
+            managementClient(profile).servers.update({
+                id: server.id,
+                name,
+                description: server.description ?? "",
+                url,
+                keySecretName,
+                ...(takesModel
+                    ? model
+                    : {
+                          modelProvider: server.modelProvider,
+                          modelName: server.modelName,
+                          modelEffort: server.modelEffort,
+                      }),
+                signInChecksPerMinute: server.signInChecksPerMinute,
+                triggerChecksPerMinute: server.triggerChecksPerMinute,
+            }),
+        ),
     );
     report.input("Server", `${name} · updated`);
     return updated;
@@ -434,14 +446,14 @@ async function syncServer(profile: Profile, id: string, url: string) {
     const deadline = Date.now() + SYNC_WAIT_MS;
     for (;;) {
         try {
-            await callManagement(profile, "post", "/servers/sync", { id });
+            await managementClient(profile).servers.sync({ id });
             report.input("Synced", `${url}/cortex`);
             return;
         } catch (error) {
             // Only a backend Cortex cannot reach yet is worth asking again; a
             // refused manifest or blocked host fails the same way next time.
             const starting =
-                error instanceof ManagementError && error.message === "upstream_failed";
+                error instanceof ManagementClientError && error.message === "upstream_failed";
             if (starting && Date.now() < deadline) {
                 await Bun.sleep(POLL_MS);
                 continue;

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;
+}