@m6d/cortex-cli 0.12.1 → 0.13.0

package/src/commands/swagger.ts

@@ -1,247 +0,0 @@
-import { existsSync, readFileSync } from "node:fs";
-import { dirname, join, resolve } from "node:path";
-
-import { type Command, Option } from "@commander-js/extra-typings";
-
-import { configLabel, configOption, openProject } from "@/config/load";
-import { declaredRoute, extractEndpoints } from "@/swagger/extract-endpoints";
-import * as report from "@/ui/report";
-
-/** A convention, not config: `KnowledgeConfig` has no `domainsDir`. */
-const DEFAULT_DOMAINS_DIR = "src/domains";
-
-/** Only the parts of a loaded config `swagger` reads to report its inputs. */
-type ProjectConfig = {
-    knowledge?: { swagger?: { url?: string } };
-    agents?: Record<string, { knowledge?: { swagger?: { url?: string } } | null } | undefined>;
-};
-
-export function registerSwagger(program: Command) {
-    const swagger = program
-        .command("swagger")
-        .helpGroup("Resources:")
-        .summary("Endpoint schemas, from your Swagger spec")
-        .description(
-            "Endpoint schemas, from your Swagger spec.\n\nReads `knowledge.swagger.url` from your cortex.config.ts and the .endpoint.ts\nfiles under src/domains.",
-        )
-        .addOption(configOption())
-        // Declared once, on the group: the two verbs read the same directory, and
-        // commander hands a verb's unknown options back to its parent, so
-        // `swagger -d x sync` and `swagger sync -d x` both land here.
-        .addOption(
-            new Option(
-                "-d, --domains-dir <path>",
-                "Domains root, relative to the config file",
-            ).default(DEFAULT_DOMAINS_DIR, DEFAULT_DOMAINS_DIR),
-        )
-        .helpCommand(false);
-
-    for (const verb of ["sync", "check"] as const) {
-        swagger
-            .command(verb)
-            .description(
-                verb === "sync"
-                    ? "Update .endpoint.ts files in place"
-                    : "Report drift without writing (exit 2 if stale)",
-            )
-            .action(async function () {
-                await run(swagger, verb, swagger.opts().domainsDir);
-            });
-    }
-}
-
-async function run(group: Command, verb: "sync" | "check", domainsDirOption: string) {
-    const title = `cortex swagger ${verb}`;
-    const { config: loaded, configPath, path, explicit, verbose } = await openProject(group, title);
-
-    // Relative to the config file, never to the cwd — the domains tree belongs to
-    // the project, and `--config ../other/cortex.config.ts` must still find it.
-    const domainsDir = resolve(dirname(configPath), domainsDirOption);
-    if (!existsSync(domainsDir)) failMissingDomainsDir(domainsDir, verb);
-
-    const urls = swaggerUrls(loaded);
-    if (!urls.length) failMissingSwaggerUrl(configPath, verb);
-    for (const url of urls) report.input("Swagger", url);
-
-    // Unlike `graph seed`, this needs nothing from the project's server — not
-    // even a version handshake. What it writes is `.endpoint.ts` source whose
-    // generated block has to satisfy that server's own `EndpointDef`, so a
-    // codegen that outran the installed server is a type error in the project's
-    // `bun run check`, loudly, rather than something to detect here.
-    const startedAt = Date.now();
-    const result = await extractEndpoints({
-        swaggerUrls: urls,
-        domainsDir,
-        write: verb === "sync",
-    }).catch(function (error: unknown): never {
-        return failExtract({ error, configPath, verbose });
-    });
-
-    // Reported once the run is over because that is when the count is known —
-    // the total is every file the walk considered, however it ended up.
-    const total =
-        result.matched + result.updated.length + result.drift.length + result.missing.length;
-    report.input(
-        "Domains",
-        `${configLabel(domainsDir)} — ${report.plural(total, "endpoint file")}`,
-    );
-    report.blank();
-
-    const elapsed = `(${((Date.now() - startedAt) / 1000).toFixed(1)}s)`;
-    if (verb === "sync") return renderSync(result, domainsDir, elapsed);
-    renderCheck(
-        result,
-        domainsDir,
-        elapsed,
-        syncCommand({ path, explicit, domainsDir: domainsDirOption }),
-    );
-}
-
-/**
- * The `sync` that fixes what `check` found has to act on the tree `check` read,
- * so it carries whatever flags got it there. Defaults stay off the line — a hint
- * is something to paste, not a transcript.
- */
-function syncCommand(options: { path: string; explicit: boolean; domainsDir: string }) {
-    return [
-        "cortex swagger sync",
-        ...(options.explicit ? [`--config ${options.path}`] : []),
-        ...(options.domainsDir === DEFAULT_DOMAINS_DIR
-            ? []
-            : [`--domains-dir ${options.domainsDir}`]),
-    ].join(" ");
-}
-
-type Report = {
-    matched: number;
-    missing: string[];
-    drift: string[];
-    updated: string[];
-};
-
-/**
- * `sync` says what it did. Only changed files are printed — at 37 files a
- * per-file log is 34 lines of `ok` — and `MISSING` goes last, because it is the
- * one thing left for a human. Writing is the job, so it still exits 0.
- */
-function renderSync(result: Report, domainsDir: string, elapsed: string) {
-    for (const file of result.updated) report.row("updated", file);
-    for (const file of result.missing) {
-        report.row("missing", file);
-        report.row("", `${routeOf(join(domainsDir, file))} — no match in the spec`);
-    }
-    if (result.updated.length || result.missing.length) report.blank();
-
-    const parts = [`${result.updated.length} updated`];
-    if (result.missing.length) parts.push(`${result.missing.length} missing`);
-    parts.push(`${result.matched} unchanged`);
-    if (result.updated.length) parts.push("formatted with prettier");
-    report.footer(`${parts.join(" · ")}  ${elapsed}`);
-
-    if (result.missing.length) {
-        report.note(
-            `${missingLead(result)} no match in the spec. Either the route moved, or the file is\nstale — \`cortex swagger check\` will keep failing until it is resolved.`,
-        );
-    }
-}
-
-/**
- * `check` says what is wrong, and writes nothing. `drift` and `MISSING` are both
- * findings — one is fixed by a tool, the other by a person — so either exits 2.
- */
-function renderCheck(result: Report, domainsDir: string, elapsed: string, sync: string) {
-    for (const file of result.drift) {
-        report.row("drift", file);
-        report.row("", `${routeOf(join(domainsDir, file))} — no longer matches the spec`);
-    }
-    for (const file of result.missing) {
-        report.row("missing", file);
-        report.row("", `${routeOf(join(domainsDir, file))} — no match in the spec`);
-    }
-    if (result.drift.length || result.missing.length) report.blank();
-
-    const parts: string[] = [];
-    if (result.drift.length) parts.push(`${result.drift.length} drifted`);
-    if (result.missing.length) parts.push(`${result.missing.length} missing`);
-    parts.push(`${result.matched} up to date`);
-    report.footer(`${parts.join(" · ")}  ${elapsed}`);
-
-    if (result.drift.length) {
-        report.note(
-            `Run \`${sync}\` to update the ${report.plural(result.drift.length, "drifted file")}.`,
-        );
-    }
-    if (result.missing.length) {
-        report.note(
-            `${missingLead(result)} no match in the spec. Either the route moved, or the file is\nstale — \`cortex swagger sync\` cannot fix it; it needs a human.`,
-        );
-    }
-    if (result.drift.length || result.missing.length) process.exit(2);
-}
-
-/**
- * The route a finding is about. The report is a list of paths; the route is
- * what the reader has to act on, and it lives in the file.
- */
-function routeOf(filePath: string) {
-    const { method = "?", path = "?" } = declaredRoute(readFileSync(filePath, "utf8"));
-    return `${method} ${path}`;
-}
-
-/** Server level, then per agent, deduped — per-agent docs override on a key clash. */
-function swaggerUrls(config: ProjectConfig) {
-    const urls = new Set<string>();
-    if (config.knowledge?.swagger?.url) urls.add(config.knowledge.swagger.url);
-
-    for (const agent of Object.values(config.agents ?? {})) {
-        if (agent?.knowledge?.swagger?.url) urls.add(agent.knowledge.swagger.url);
-    }
-
-    return [...urls];
-}
-
-/** `1 endpoint file has` / `3 endpoint files have` — both notes open with it. */
-function missingLead(result: Report) {
-    return `${report.plural(result.missing.length, "endpoint file")} ${result.missing.length === 1 ? "has" : "have"}`;
-}
-
-/**
- * An absent domains dir is *couldn't run*, not "nothing to do": `extractEndpoints`
- * walks a missing directory as an empty one and would report a clean 0 of 0.
- */
-function failMissingDomainsDir(domainsDir: string, verb: string): never {
-    report.fail({
-        what: `No domains directory at ${configLabel(domainsDir)}`,
-        blocks: [
-            `\`swagger ${verb}\` reads .endpoint.ts files under a domains root — ${DEFAULT_DOMAINS_DIR} by\ndefault — resolved relative to the config file. Point it somewhere else:`,
-            `  cortex swagger ${verb} --domains-dir ./lib/domains`,
-        ],
-    });
-}
-
-function failMissingSwaggerUrl(configPath: string, verb: string): never {
-    report.fail({
-        what: `${configLabel(configPath)} has no knowledge.swagger.url`,
-        blocks: [
-            `\`swagger ${verb}\` generates endpoint schemas from a Swagger spec. Add one:`,
-            '  knowledge: { swagger: { url: "https://api.example.com/swagger/v1/swagger.json" } }',
-            "See https://github.com/boring91/cortex/blob/main/packages/cortex-server/README.md#file-structure-convention",
-        ],
-    });
-}
-
-/**
- * The `◇ Swagger` lines above name every URL that was tried, so the error
- * states the failure and points at the key behind it.
- */
-function failExtract(options: { error: unknown; configPath: string; verbose: boolean }): never {
-    const { error, configPath, verbose } = options;
-    report.fail({
-        what: "Could not read the Swagger spec",
-        error,
-        blocks: [
-            `Is the API running? Otherwise check knowledge.swagger.url in\n${configLabel(configPath)}.`,
-        ],
-        verbose,
-    });
-}

package/src/config/load.ts

@@ -1,122 +0,0 @@
-/**
- * Config discovery and loading. Env needs no step of its own:
- * discovery is cwd-only and Bun's `.env` auto-load is cwd-relative, so the two
- * are always colocated and `process.env` is populated before the config
- * evaluates.
- */
-
-import { existsSync } from "node:fs";
-import { relative, resolve } from "node:path";
-import { pathToFileURL } from "node:url";
-
-import { Option } from "@commander-js/extra-typings";
-import type { Command } from "@commander-js/extra-typings";
-import { isRecord } from "@cortex/contracts/json";
-
-import { validateConfig } from "@/config/validate";
-import * as report from "@/ui/report";
-
-// Discovery is this exact name in the cwd, with no upward walk, so the flag's
-// default *is* the discovery rule.
-const DEFAULT_CONFIG = "./cortex.config.ts";
-
-/**
- * `-c, --config <path>` for a command group that reads the project: declared
- * on the group, so `cortex new` and `cortex cc` never show it. Commander hands
- * a verb's unknown options back to its parent, so `swagger -c x sync` and
- * `swagger sync -c x` both land on the group.
- */
-export function configOption() {
-    // The second argument is what help prints; without it commander would
-    // JSON.stringify the path and show quotes.
-    return new Option("-c, --config <path>", "Path to cortex.config.ts").default(
-        DEFAULT_CONFIG,
-        DEFAULT_CONFIG,
-    );
-}
-
-/** How a config path is printed once found: relative to the cwd, `./`-prefixed. */
-export function configLabel(path: string) {
-    const relativePath = relative(process.cwd(), path);
-    return relativePath.startsWith(".") ? relativePath : `./${relativePath}`;
-}
-
-/**
- * `./cortex.config.ts` in the cwd, that exact name — no upward walk and no
- * extension fallback, so a run from the wrong directory fails loudly instead of
- * silently picking up an ancestor's config. `--config` replaces the path
- * outright and accepts anything Bun can import.
- */
-function findConfig(options: { path: string; explicit: boolean; command: string }) {
-    const { path, explicit, command } = options;
-    const absolute = resolve(process.cwd(), path);
-    if (existsSync(absolute)) return absolute;
-
-    if (explicit) {
-        report.fail({
-            what: `No config file at ${path}`,
-            blocks: [
-                "--config takes a path to a file Bun can import, resolved from the\ndirectory you run in.",
-            ],
-        });
-    }
-
-    report.fail({
-        what: `No cortex.config.ts in ${process.cwd()}`,
-        blocks: [
-            "The CLI looks for exactly ./cortex.config.ts in the directory you run in.\nIt does not search parent directories.",
-            "Run it from the project root, or point at the file:",
-            `  ${command} --config ./server/cortex.config.ts`,
-        ],
-    });
-}
-
-/**
- * What every project command does before its own work: find the config from
- * its group's `--config`, open the report, load and validate it, and report
- * its path as the first input. Discovery runs before the report opens: with
- * no config there is no run to report on, only the reason there isn't one.
- */
-export async function openProject(group: Command, title: string) {
-    // The group and the root reach this file untyped: `Command` here is the
-    // parameter type, not cli.ts's inferred one.
-    const { config: path, verbose = false } = group.optsWithGlobals() as {
-        config: string;
-        verbose?: boolean;
-    };
-    const explicit = group.getOptionValueSource("config") !== "default";
-    const configPath = findConfig({ path, explicit, command: title });
-
-    report.header(title);
-    const config = await loadConfig(configPath, verbose);
-    validateConfig(config, configLabel(configPath));
-    report.input("Config", configLabel(configPath));
-
-    return { config, configPath, path, explicit, verbose };
-}
-
-/** The whole loader: one import, one default export, no unwrap branch. */
-async function loadConfig(path: string, verbose: boolean) {
-    try {
-        const module = (await import(pathToFileURL(path).href)) as { default?: unknown };
-        const config = module.default;
-
-        if (config === undefined) throw new Error("The module has no default export.");
-        if (!isRecord(config)) throw new Error("The default export is not an object.");
-
-        return config;
-    } catch (error) {
-        report.fail({
-            what: `Could not load ${configLabel(path)}`,
-            error,
-            blocks: [
-                // The line above this one is the underlying error, and for the most
-                // common failure it reads `Cannot find package '@m6d/cortex-server'` —
-                // the config imports the server for `defineAgent`. So the install is
-                // named here rather than left to be inferred.
-                "Importing the file has to run cleanly on its own: it default-exports a\nplain CortexConfig object and nothing else, and every package it imports\nhas to be installed — `bun add @m6d/cortex-server` if that is what is\nmissing above.",
-            ],
-            verbose,
-        });
-    }
-}

package/src/config/validate.ts

@@ -1,46 +0,0 @@
-/**
- * One generic rule: a key present with an `undefined` value
- * is a failure, listed by full path. It is essentially always the
- * `process.env["X"]!` pattern, where `!` silences the type error and `undefined`
- * flows on to fail far from its cause. Absent keys are fine — that is how
- * optional sections are expressed.
- *
- * The error names config paths only. Annotating each with the env var behind it
- * is not implementable: the CLI imports an already-evaluated object, so the name
- * is gone. Point at `.env` and stop.
- */
-
-import * as report from "@/ui/report";
-
-/** `label` is how the config file is named in the failure: the `./`-relative path the loader prints. */
-export function validateConfig(config: Record<string, unknown>, label: string) {
-    const paths = findUndefined(config, "", new WeakSet());
-    if (!paths.length) return;
-
-    report.fail({
-        what: `${label} has ${report.plural(paths.length, "undefined value")}`,
-        blocks: [
-            paths.map((entry) => `  ${entry}`).join("\n"),
-            "These keys are present but evaluate to undefined — usually a missing\nenvironment variable. Bun loads .env from the directory you run in; check\nthat ./.env exists and is complete.",
-        ],
-    });
-}
-
-// `seen` guards the domain graph, where concepts and endpoints reference each
-// other in cycles.
-function findUndefined(value: object, prefix: string, seen: WeakSet<object>): string[] {
-    if (seen.has(value)) return [];
-    seen.add(value);
-
-    return (Object.entries(value) as [string, unknown][]).flatMap(([key, child]) => {
-        const path = prefix ? `${prefix}.${key}` : key;
-        if (child === undefined) return [path];
-        if (typeof child !== "object" || child === null) return [];
-        // Domain data is built by the server's `define*` helpers, which write
-        // every optional key whether or not it was passed. `undefined` under a
-        // `__brand` means "this endpoint mutates nothing", never a missing env
-        // var, so the rule stops at the seed data it would otherwise drown in.
-        if ("__brand" in child) return [];
-        return findUndefined(child, path, seen);
-    });
-}

package/src/contracts/credentials/index.ts

@@ -1,183 +0,0 @@
-import { z } from "zod";
-import { canCarrySecret } from "../egress/url";
-
-export { canCarrySecret };
-
-/*
- * A credential is a value Cortex presents to an upstream: one it holds
- * (`static`) or one it acquires (`oauth2-client-credentials`, RFC 6749 §4.4).
- * The definition is the same on both sides; the Control Center stores it,
- * a code config declares it, and each side resolves it to a bearer through
- * the helper and cache below with its own egress-guarded fetch.
- */
-
-export const CREDENTIAL_KINDS = ["static", "oauth2-client-credentials"] as const;
-export type CredentialKind = (typeof CREDENTIAL_KINDS)[number];
-
-export const credentialDefinitionSchema = z.discriminatedUnion("kind", [
-    z.object({
-        kind: z.literal("static"),
-        value: z.string().min(1),
-    }),
-    z.object({
-        kind: z.literal("oauth2-client-credentials"),
-        /** The token endpoint; a client secret travels over TLS, to loopback, or to a host the egress policy admits. */
-        tokenUrl: z
-            .url()
-            .refine(
-                (url) => canCarrySecret(url),
-                "token URL must be https, or http to loopback or to a host the egress policy admits",
-            ),
-        clientId: z.string().min(1),
-        clientSecret: z.string().min(1),
-        scope: z.string().min(1).optional(),
-    }),
-]);
-export type CredentialDefinition = z.infer<typeof credentialDefinitionSchema>;
-export type OAuth2ClientCredentials = Extract<
-    CredentialDefinition,
-    { kind: "oauth2-client-credentials" }
->;
-
-/** One POST to the token endpoint through the caller's guarded fetch; `null` when the transport failed. */
-export type TokenPost = (
-    url: string,
-    init: { headers: Record<string, string>; body: string },
-) => Promise<{ status: number; body: string } | null>;
-
-/** A bearer and when it stops being one; `null` when the issuer did not say. */
-export type AcquiredToken = { token: string; expiresAt: number | null };
-
-export type AcquireResult =
-    | { ok: true; value: AcquiredToken }
-    | {
-          ok: false;
-          error:
-              | "token_url_insecure"
-              | "token_request_failed"
-              | "token_rejected"
-              | "token_response_invalid";
-      };
-
-const tokenResponseSchema = z.object({
-    access_token: z.string().min(1),
-    token_type: z.string().optional(),
-    // Some issuers (Azure AD v1 among them) send the lifetime as a string.
-    expires_in: z
-        .union([z.number(), z.string().regex(/^\d+$/).transform(Number)])
-        .pipe(z.number().nonnegative())
-        .optional(),
-});
-
-/**
- * The client credentials grant: a form-encoded POST with the client
- * authenticated by `client_secret_basic` (RFC 6749 §2.3.1, each half
- * form-encoded before base64). The endpoint's body never leaves this
- * function: a failure is one of three literals, since the body may echo
- * the client secret or carry the issuer's own error detail.
- */
-export async function acquireOAuth2ClientCredentials(
-    definition: OAuth2ClientCredentials,
-    post: TokenPost,
-) {
-    // Judged again here, not only when the definition was saved: the policy
-    // may have tightened since, and a secret never travels where it may not.
-    if (!canCarrySecret(definition.tokenUrl)) {
-        return { ok: false, error: "token_url_insecure" } satisfies AcquireResult;
-    }
-    const basic = Buffer.from(
-        `${encodeURIComponent(definition.clientId)}:${encodeURIComponent(definition.clientSecret)}`,
-    ).toString("base64");
-    const answer = await post(definition.tokenUrl, {
-        headers: {
-            Authorization: `Basic ${basic}`,
-            "Content-Type": "application/x-www-form-urlencoded",
-            Accept: "application/json",
-        },
-        body: new URLSearchParams({
-            grant_type: "client_credentials",
-            ...(definition.scope ? { scope: definition.scope } : {}),
-        }).toString(),
-    });
-    if (!answer) return { ok: false, error: "token_request_failed" } satisfies AcquireResult;
-    if (answer.status < 200 || answer.status >= 300) {
-        return { ok: false, error: "token_rejected" } satisfies AcquireResult;
-    }
-    let parsed: z.ZodSafeParseResult<z.infer<typeof tokenResponseSchema>>;
-    try {
-        parsed = tokenResponseSchema.safeParse(JSON.parse(answer.body));
-    } catch {
-        return { ok: false, error: "token_response_invalid" } satisfies AcquireResult;
-    }
-    if (!parsed.success || (parsed.data.token_type ?? "bearer").toLowerCase() !== "bearer") {
-        return { ok: false, error: "token_response_invalid" } satisfies AcquireResult;
-    }
-    const issuedAt = Date.now();
-    return {
-        ok: true as const,
-        value: {
-            token: parsed.data.access_token,
-            expiresAt:
-                parsed.data.expires_in === undefined
-                    ? null
-                    : issuedAt + parsed.data.expires_in * 1000,
-        },
-    } satisfies AcquireResult;
-}
-
-/** A token is not reused inside this margin of its expiry: the call it is presented on still has to complete. */
-const EXPIRY_MARGIN_MS = 30_000;
-
-/** Equal definitions share one key; a rotated secret is another definition and another token. Kept in memory only, like the definitions themselves. */
-function keyOf(definition: CredentialDefinition) {
-    return JSON.stringify(definition);
-}
-
-/**
- * Acquired tokens by definition, reused until their expiry margin. Concurrent
- * acquisitions of one definition share a single request; a token the issuer
- * gave no expiry for is answered but not kept, since nothing says when it
- * stops working. `invalidate` is for the caller that saw a 401: the next
- * resolve acquires again. Pure, so the console's client bundle may import
- * the schemas beside it.
- */
-export function createCredentialCache(now: () => number = Date.now) {
-    const tokens = new Map<string, AcquiredToken>();
-    const inFlight = new Map<string, Promise<AcquireResult>>();
-
-    return {
-        async get(definition: CredentialDefinition, acquire: () => Promise<AcquireResult>) {
-            const key = keyOf(definition);
-            const cached = tokens.get(key);
-            if (
-                cached &&
-                cached.expiresAt !== null &&
-                cached.expiresAt - EXPIRY_MARGIN_MS > now()
-            ) {
-                return { ok: true, value: cached } satisfies AcquireResult;
-            }
-            tokens.delete(key);
-            const pending = inFlight.get(key);
-            if (pending) return pending;
-            const acquiring = acquire()
-                .then((result) => {
-                    if (
-                        result.ok &&
-                        result.value.expiresAt !== null &&
-                        result.value.expiresAt - EXPIRY_MARGIN_MS > now()
-                    ) {
-                        tokens.set(key, result.value);
-                    }
-                    return result;
-                })
-                .finally(() => inFlight.delete(key));
-            inFlight.set(key, acquiring);
-            return acquiring;
-        },
-        invalidate(definition: CredentialDefinition) {
-            tokens.delete(keyOf(definition));
-        },
-    };
-}
-
-export type CredentialCache = ReturnType<typeof createCredentialCache>;