@m6d/cortex-cli 0.12.1 → 0.14.0

package/src/commands/setup.ts

@@ -0,0 +1,610 @@
+import { createHash } from "node:crypto";
+import { lookup } from "node:dns/promises";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+
+import type { Command } from "@commander-js/extra-typings";
+import {
+    canCarrySecret,
+    credentialForms,
+    egressAllowedHosts,
+    isEgressAllowedHost,
+    isPrivateAddress,
+    normalizeHost,
+    scrubCredentialStrings,
+} from "@cortex/contracts/egress-policy";
+import { z } from "zod";
+
+import {
+    applyManifest,
+    DEFAULT_MANIFEST,
+    findManifest,
+    printTriggerSecrets,
+} from "@/commands/apply";
+import { callOrFail, failCall, requireProfile, walkPages } from "@/commands/management";
+import { callManagement, ManagementError, UnreachableError } from "@/management/client";
+import { DOCKER_HOST, EMBEDDING, withEnvValues } from "@/scaffold/files";
+import * as prompts from "@/ui/prompts";
+import * as report from "@/ui/report";
+
+/** Long enough for a first `docker compose up` to pull the image and migrate. */
+const CORTEX_WAIT_MS = 10 * 60_000;
+/** How long Cortex gets to reach a backend that is still starting. */
+const SYNC_WAIT_MS = 60_000;
+const POLL_MS = 2_000;
+
+/** The backend as `cortex new` writes it into .env, which Bun loads from the directory it runs in. */
+const projectSchema = z.object({
+    CORTEX_SERVER_NAME: z.string().min(1),
+    CORTEX_SERVER_URL: z.url(),
+    CORTEX_SERVER_KEY: z.string().min(1),
+});
+
+/**
+ * What .env keeps as typed: Bun and Compose expand `$`, cut at `#`, and strip
+ * quotes and spaces. Checked on answers before they are written; a value
+ * edited into .env by hand reaches setup already parsed, past checking.
+ */
+const ENV_SAFE = /^[^\s$#'"`\\]+$/;
+
+/** The model provider in .env: all four values, or none. */
+const providerFields = z.object({
+    // Its key's secret is `<name>-api-key-<digest>`, within Cortex's 120 characters.
+    MODEL_PROVIDER_NAME: z.string().min(1).max(103),
+    MODEL_PROVIDER_URL: z.string().superRefine(function (value, context) {
+        const problem = checkBaseUrl(value);
+        if (problem) context.addIssue({ code: "custom", message: problem });
+    }),
+    MODEL_PROVIDER_API_KEY: z.string().min(1),
+    MODEL_PROVIDER_MODEL: z.string().min(1).max(200),
+});
+const providerEnvSchema = providerFields.transform((env) => ({
+    name: env.MODEL_PROVIDER_NAME,
+    baseUrl: env.MODEL_PROVIDER_URL,
+    apiKey: env.MODEL_PROVIDER_API_KEY,
+    model: env.MODEL_PROVIDER_MODEL,
+}));
+
+type Provider = z.output<typeof providerEnvSchema>;
+type Profile = ReturnType<typeof requireProfile>;
+
+const namedSchema = z.object({ id: z.string(), name: z.string() });
+const providerRowSchema = namedSchema.extend({
+    baseUrl: z.string(),
+    secretName: z.string(),
+    models: z.array(z.string()),
+    efforts: z.array(z.string()),
+});
+const serverSchema = namedSchema.extend({
+    description: z.string().nullable(),
+    url: z.string().nullable(),
+    keySecretName: z.string().nullable(),
+    modelProvider: z.string().nullable(),
+    modelName: z.string().nullable(),
+    modelEffort: z.string().nullable(),
+});
+const chatSchema = z.object({ choices: z.array(z.object({ message: z.object({}) })).min(1) });
+const embeddingsSchema = z.object({
+    data: z.array(z.object({ embedding: z.array(z.number()).length(EMBEDDING.dimension) })).min(1),
+});
+
+/**
+ * `cortex setup`: registers this project's backend in its Cortex and applies
+ * its manifest, in the one order Cortex accepts: the model provider and its
+ * key, the server and its key, its first sync, then the apply. Every step
+ * creates what is missing and keeps what exists, so it runs again on every
+ * `bun run dev`. A provider or server under .env's name must call .env's URL,
+ * or setup leaves it alone and stops, so no key reaches a URL .env did not name. With no model provider in .env it asks for
+ * one on a terminal, and under `--yes` registers the server and applies
+ * nothing, since Cortex publishes no agent without a model.
+ */
+export function registerSetup(program: Command<[], { verbose?: true; profile?: string }>) {
+    const command = program
+        .command("setup")
+        .helpGroup("Project:")
+        .description("Register this project's backend and model in Cortex, then apply its manifest")
+        .option("--wait", "Wait for Cortex to come up first")
+        .option("--yes", "Never ask; leave out what .env does not hold");
+
+    command.action(async function (options) {
+        const { verbose = false, profile: profileName } = program.opts();
+        const project = readProject();
+        const profile = requireProfile(profileName);
+        const file = findManifest(DEFAULT_MANIFEST);
+        const interactive = process.stdin.isTTY === true && options.yes !== true;
+        if (profileName === undefined) requireEnvCortex(profile.url);
+
+        report.header("cortex setup");
+        await waitForCortex(profile, options.wait === true);
+        report.input("Cortex", profile.url);
+
+        const provider = readProvider() ?? (interactive ? await askAndSave() : undefined);
+        if (provider) await requireReachable(provider.baseUrl);
+
+        if (provider) await ensureProvider(profile, provider);
+        const server = await ensureServer(profile, project, provider);
+        await syncServer(profile, server.id, project.CORTEX_SERVER_URL);
+
+        if (server.modelProvider === null) {
+            report.footer("no model yet, so nothing applied");
+            report.note("Run `bun cortex setup` in a terminal to add a model provider.");
+            return;
+        }
+
+        const { changes, triggerSecrets } = await applyManifest({
+            profile,
+            file,
+            dryRun: false,
+            verbose,
+        });
+        report.footer(`live · chat at ${profile.url}/playground`);
+        printTriggerSecrets(triggerSecrets);
+        if (Object.values(changes.create).flat().length > 0) printSignIn(profile.url);
+    });
+}
+
+function readProject() {
+    const parsed = projectSchema.safeParse(process.env);
+    if (parsed.success) return parsed.data;
+    return report.fail({
+        what: "No project here for cortex setup",
+        blocks: [
+            "It reads CORTEX_SERVER_NAME, CORTEX_SERVER_URL and CORTEX_SERVER_KEY from\n.env, which `cortex new` writes. Run it from that project's root.",
+        ],
+    });
+}
+
+/**
+ * The Cortex .env names is the one setup sets up, unless `-p` picks another.
+ * Bun lets a CORTEX_URL exported in the shell win over .env, and one left
+ * there for another deployment must not get this project's secrets. .env is
+ * read by a child Bun given this process's environment without the pair, so
+ * it picks the same files and expands `${VAR}` from the same values.
+ */
+function requireEnvCortex(url: string) {
+    if (!existsSync(".env")) return;
+    const child = Bun.spawnSync(
+        [process.execPath, "-e", "process.stdout.write(process.env.CORTEX_URL ?? '')"],
+        {
+            env: Object.fromEntries(
+                Object.entries(process.env).filter(
+                    ([name]) => name !== "CORTEX_URL" && name !== "CORTEX_KEY",
+                ),
+            ),
+        },
+    );
+    const named = child.stdout.toString().replace(/\/+$/, "");
+    if (named === "" || named === url) return;
+    report.fail({
+        what: `CORTEX_URL in your shell (${url}) wins over .env's (${named})`,
+        blocks: [
+            "cortex setup sets up the Cortex .env names. Unset the shell's pair, or pick a\nsaved profile with -p:",
+            "  unset CORTEX_URL CORTEX_KEY",
+        ],
+    });
+}
+
+/** The model provider in .env, while every value is blank none; a partial or invalid one ends the run. */
+function readProvider() {
+    if (providerFields.keyof().options.every((key) => !process.env[key])) return undefined;
+    const parsed = providerEnvSchema.safeParse(process.env);
+    if (parsed.success) return parsed.data;
+    return report.fail({
+        what: "MODEL_PROVIDER_* in .env is not a model provider setup can use",
+        blocks: [z.prettifyError(parsed.error), "Fill in all four values, or clear all four."],
+    });
+}
+
+/**
+ * Asks until Cortex answers, under `wait`; once otherwise. A refusal ends the
+ * run at once: only a Cortex that is not up yet is worth waiting for. The
+ * last failure ends it through `failCall`'s grammar.
+ */
+async function waitForCortex(profile: Profile, wait: boolean) {
+    const deadline = Date.now() + (wait ? CORTEX_WAIT_MS : 0);
+    let announced = false;
+    for (;;) {
+        try {
+            await callManagement(profile, "get", "/secrets/list", { pageSize: 1 });
+            return;
+        } catch (error) {
+            const starting =
+                error instanceof UnreachableError ||
+                (error instanceof ManagementError && 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.`);
+                announced = true;
+            }
+            await Bun.sleep(POLL_MS);
+        }
+    }
+}
+
+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,
+    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 }),
+            ),
+        );
+    return items.find((entry) => entry.name === name);
+}
+
+/**
+ * A secret's name for one value: its base and a short digest of the value.
+ * A name then holds one value only, so a secret that exists is the value
+ * .env holds, and a changed key gets a secret of its own while every row
+ * presenting the old one keeps it.
+ */
+function secretFor(base: string, value: string) {
+    return `${base}-${createHash("sha256").update(value).digest("hex").slice(0, 8)}`;
+}
+
+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 });
+}
+
+/**
+ * A row under the name .env gives that calls another URL belongs to
+ * something else: setup changes none of it and sends it no key.
+ */
+function failCallsElsewhere(what: string, calls: string | null, wanted: string, rename: string) {
+    return report.fail({
+        what: `${what} in Cortex calls ${calls ?? "no URL"}, not .env's ${wanted}`,
+        blocks: [
+            `It belongs to something else, so setup leaves it alone. Give this project's\nanother ${rename} in .env.`,
+        ],
+    });
+}
+
+/**
+ * The provider, on its key's secret. One that exists takes a changed key and
+ * the .env model as well; one that calls another URL ends the run.
+ */
+async function ensureProvider(profile: Profile, provider: Provider) {
+    const found = await findByName(profile, "model-providers", provider.name, providerRowSchema);
+    if (found && found.baseUrl !== provider.baseUrl) {
+        failCallsElsewhere(
+            `Provider ${provider.name}`,
+            found.baseUrl,
+            provider.baseUrl,
+            "MODEL_PROVIDER_NAME",
+        );
+    }
+    const secretName = secretFor(`${provider.name}-api-key`, provider.apiKey);
+    await ensureSecret(profile, secretName, provider.apiKey);
+
+    if (!found) {
+        await call(profile, "post", "/model-providers/create", {
+            name: provider.name,
+            baseUrl: provider.baseUrl,
+            secretName,
+            models: [provider.model],
+            efforts: [],
+        });
+        report.input("Provider", `${provider.name} · created`);
+        return;
+    }
+    if (found.secretName === secretName && found.models.includes(provider.model)) {
+        report.input("Provider", `${provider.name} · kept`);
+        return;
+    }
+    await call(profile, "post", "/model-providers/update", {
+        id: found.id,
+        baseUrl: found.baseUrl,
+        secretName,
+        // Added, never replaced: a model a server still runs on stays offered.
+        models: [...new Set([...found.models, provider.model])],
+        efforts: found.efforts,
+    });
+    report.input("Provider", `${provider.name} · updated`);
+}
+
+/**
+ * The server, on its key's secret and created on the provider's model. One
+ * that exists takes a changed key, and the provider's model when it has
+ * none, which is how a provider added later reaches its agents; one that
+ * calls another URL ends the run.
+ */
+async function ensureServer(
+    profile: Profile,
+    project: z.output<typeof projectSchema>,
+    provider: Provider | undefined,
+) {
+    const name = project.CORTEX_SERVER_NAME;
+    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 }))
+        : undefined;
+    if (server && server.url !== url) {
+        failCallsElsewhere(`Server ${name}`, server.url, url, "CORTEX_SERVER_NAME");
+    }
+    const keySecretName = secretFor(`${name}-server-key`, project.CORTEX_SERVER_KEY);
+    await ensureSecret(profile, keySecretName, project.CORTEX_SERVER_KEY);
+
+    const model = {
+        modelProvider: provider?.name ?? null,
+        modelName: provider?.model ?? null,
+        modelEffort: null,
+    };
+    if (!server) {
+        const created = serverSchema.parse(
+            await call(profile, "post", "/servers/create", {
+                name,
+                description: "",
+                url,
+                keySecretName,
+                ...model,
+            }),
+        );
+        report.input("Server", `${name} · created`);
+        return created;
+    }
+
+    const takesModel = server.modelProvider === null && provider !== undefined;
+    if (server.keySecretName === keySecretName && !takesModel) {
+        report.input("Server", `${name} · kept`);
+        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,
+                  }),
+        }),
+    );
+    report.input("Server", `${name} · updated`);
+    return updated;
+}
+
+/**
+ * Reads the backend's manifest into Cortex, which the apply needs: the
+ * agent's prompt reads a variable only a synced server declares. A backend
+ * Cortex cannot reach yet is asked again until `SYNC_WAIT_MS` passes.
+ */
+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 });
+            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";
+            if (starting && Date.now() < deadline) {
+                await Bun.sleep(POLL_MS);
+                continue;
+            }
+            if (!starting) failCall(profile, error);
+            report.fail({
+                what: `Cortex could not reach ${url}/cortex`,
+                error,
+                blocks: [
+                    "Nothing was applied. Check that the backend is running (`bun run dev:server`),\nthen run setup again.",
+                ],
+            });
+        }
+    }
+}
+
+/** Asked on a terminal when .env names no provider, then kept in .env for every later run. */
+async function askAndSave() {
+    const { provider, env } = await askProvider();
+    if (existsSync(".env")) writeFileSync(".env", withEnvValues(readFileSync(".env", "utf8"), env));
+    if ("EMBEDDING_API_KEY" in env) {
+        report.note("Restart cortex in `bun run dev` so Cortex embeds with this provider too.");
+    }
+    return provider;
+}
+
+/**
+ * The model provider's details, asked one at a time, then checked with one
+ * chat message to the model. A provider that fails the check is kept only if
+ * the user says so; otherwise it is asked again. Returns the provider and the
+ * .env lines that hold it, the embedding settings too when the provider
+ * serves the stack's embedding model.
+ */
+export async function askProvider() {
+    for (;;) {
+        const name = (
+            await prompts.askValue("Model provider name", "openai", issue("MODEL_PROVIDER_NAME"))
+        ).trim();
+        const baseUrl = (
+            await prompts.askValue(
+                "Base URL",
+                "Any OpenAI-compatible URL, e.g. https://api.openai.com/v1",
+                issue("MODEL_PROVIDER_URL"),
+            )
+        )
+            .trim()
+            .replace(/\/+$/, "");
+        const apiKey = await prompts.askSecret("API key", issue("MODEL_PROVIDER_API_KEY"));
+        const model = (
+            await prompts.askValue("Model", "gpt-5-mini", issue("MODEL_PROVIDER_MODEL"))
+        ).trim();
+        const provider = { name, baseUrl, apiKey, model };
+
+        const { host } = new URL(baseUrl);
+        const check = checkProvider(provider);
+        await prompts.runSteps([
+            {
+                title: `Checking ${host}`,
+                run: async function () {
+                    const { chat, embeddings } = await check;
+                    if (!chat.ok) return undefined;
+                    return `Checked ${host} · ${model} replied · ${embeddings ? "embeddings work" : "no embeddings"}`;
+                },
+            },
+        ]);
+        const { chat, embeddings } = await check;
+
+        if (!chat.ok) {
+            prompts.log.warn(`${model} at ${host} did not answer: ${chat.reason}`);
+            if (!(await prompts.askConfirm("Use these details anyway?"))) continue;
+        } else if (!embeddings) {
+            prompts.log.info(
+                "Tool search and knowledge stay off until EMBEDDING_* in .env is set.",
+            );
+        }
+
+        return {
+            provider,
+            env: {
+                MODEL_PROVIDER_NAME: name,
+                MODEL_PROVIDER_URL: baseUrl,
+                MODEL_PROVIDER_API_KEY: apiKey,
+                MODEL_PROVIDER_MODEL: model,
+                ...(embeddings ? { EMBEDDING_BASE_URL: baseUrl, EMBEDDING_API_KEY: apiKey } : {}),
+            },
+        };
+    }
+}
+
+/** What setup would refuse in an answer, as the prompt says it. */
+function issue(field: keyof z.input<typeof providerFields>) {
+    return (value: string) =>
+        ENV_SAFE.test(value)
+            ? providerFields.shape[field].safeParse(value).error?.issues[0]?.message
+            : "No spaces, quotes, $, # or \\: .env would not keep it as typed.";
+}
+
+/**
+ * The private hosts the stack's egress policy admits, from .env. Before a
+ * project has one (`cortex new` asks first), the default it will hold.
+ */
+function admittedHosts() {
+    return process.env["EGRESS_ALLOWED_HOSTS"] === undefined ? [DOCKER_HOST] : egressAllowedHosts();
+}
+
+/** A URL the key may travel to under the stack's egress policy; where it resolves is `unreachable`'s. */
+function checkBaseUrl(value: string) {
+    if (!URL.canParse(value)) return "A full URL, like https://api.openai.com/v1.";
+    if (!canCarrySecret(value, admittedHosts())) {
+        return "https, or http to a host EGRESS_ALLOWED_HOSTS admits, like host.docker.internal.";
+    }
+    return undefined;
+}
+
+/**
+ * Why Cortex's containers could not call the provider, or undefined. They
+ * run in Docker, where localhost is the container, and their egress policy
+ * refuses every private address but the hosts it admits; a hostname is
+ * judged by what it resolves to here.
+ */
+async function unreachable(baseUrl: string) {
+    const host = normalizeHost(new URL(baseUrl).hostname);
+    if (isEgressAllowedHost(host, admittedHosts())) return undefined;
+    const addresses = await lookup(host, { all: true }).catch(() => []);
+    if (!addresses.some(({ address }) => isPrivateAddress(address))) return undefined;
+    return `${host} is on this machine or a private network, which Cortex's containers do not call. Use ${DOCKER_HOST} for this machine, or add the host to EGRESS_ALLOWED_HOSTS in .env and restart cortex in \`bun run dev\`.`;
+}
+
+async function requireReachable(baseUrl: string) {
+    const reason = await unreachable(baseUrl);
+    if (reason) report.fail({ what: "Cortex cannot call MODEL_PROVIDER_URL", blocks: [reason] });
+}
+
+/**
+ * One chat message to the model, and whether the provider also serves the
+ * stack's embedding model at the stack's dimension.
+ */
+async function checkProvider(provider: Provider) {
+    const blocked = await unreachable(provider.baseUrl);
+    if (blocked) return { chat: { ok: false as const, reason: blocked }, embeddings: false };
+
+    const [chat, embeddings] = await Promise.all([
+        post(provider, "/chat/completions", {
+            model: provider.model,
+            messages: [{ role: "user", content: "Reply with ok." }],
+        }),
+        post(provider, "/embeddings", {
+            model: EMBEDDING.model,
+            input: ["ok"],
+            dimensions: EMBEDDING.dimension,
+        }),
+    ]);
+    return {
+        // A 200 from a catch-all page is no reply from a model.
+        chat:
+            chat.ok && !chatSchema.safeParse(chat.body).success
+                ? { ok: false as const, reason: "it answered, but not with a chat completion" }
+                : chat,
+        embeddings: chat.ok && embeddings.ok && embeddingsSchema.safeParse(embeddings.body).success,
+    };
+}
+
+/**
+ * One OpenAI-style call with the provider's key. A refusal's reason is the
+ * provider's own message, with any spelling of the key it echoes redacted.
+ */
+async function post(provider: Provider, path: string, body: unknown) {
+    const scrub = (text: string) =>
+        String(scrubCredentialStrings(text, credentialForms(provider.apiKey)));
+    // The check runs on this machine, where Docker's name for it does not resolve.
+    const url = new URL(`${provider.baseUrl}${path}`);
+    if (url.hostname === DOCKER_HOST) url.hostname = "localhost";
+    try {
+        const response = await fetch(url, {
+            method: "POST",
+            headers: {
+                Authorization: `Bearer ${provider.apiKey}`,
+                "Content-Type": "application/json",
+            },
+            body: JSON.stringify(body),
+            signal: AbortSignal.timeout(30_000),
+        });
+        const answer: unknown = await response.json().catch(() => null);
+        if (response.ok) return { ok: true as const, body: answer };
+        const message = z.object({ error: z.object({ message: z.string() }) }).safeParse(answer)
+            .data?.error.message;
+        return {
+            ok: false as const,
+            reason: scrub(`${response.status} ${message ?? response.statusText}`),
+        };
+    } catch (error) {
+        return {
+            ok: false as const,
+            reason: scrub(error instanceof Error ? error.message : String(error)),
+        };
+    }
+}
+
+/**
+ * Shown once, on the run that first applied: the console's first admin, from
+ * .env. The password only reaches a terminal, never a log that captures it.
+ */
+function printSignIn(url: string) {
+    const email = process.env["DEFAULT_ADMIN_EMAIL"];
+    const password = process.env["DEFAULT_ADMIN_PASSWORD"];
+    if (!email || !password) return;
+    report.note(
+        process.stdout.isTTY === true
+            ? `Sign in to ${url} as ${email}, password ${password}. Both are in .env.`
+            : `Sign in to ${url} with DEFAULT_ADMIN_EMAIL and DEFAULT_ADMIN_PASSWORD from .env.`,
+    );
+}

package/src/contracts/charts/chart-spec.ts

@@ -1,6 +1,6 @@
 /*
  * The boundary on a Vega-Lite spec the model wrote, shared by the widget
- * (which draws it live) and the server (which describes it to the model):
+ * (which draws it live) and Cortex (which describes it to the model):
  * inline data only, no fetches, no interactivity, bounded work.
  */
 

package/src/contracts/client-tools/index.ts

@@ -43,9 +43,9 @@ export type ClientToolHandshake = ClientToolOutcome & {
 };
 
 /*
- * Built-in input tools: static client tools the server package exports and
- * the widget answers with a component of its own, keyed by tool name. A
- * consumer's `toolComponents` entry under the same name replaces the built-in.
+ * Built-in input tools: client tools Cortex declares and the widget answers
+ * with a component of its own, keyed by tool name. A consumer's
+ * `toolComponents` entry under the same name replaces the built-in.
  */
 
 export const REQUEST_LOCATION_TOOL = "requestLocation";