@m6d/cortex-cli 0.12.1 → 0.14.0

package/src/commands/{cc.ts → management.ts}

@@ -1,74 +1,74 @@
 import { readFileSync } from "node:fs";
 
 import { type Command, Option } from "@commander-js/extra-typings";
-import { canCarrySecret } from "@cortex/contracts/egress";
+import { canCarrySecret } from "@cortex/contracts/egress-policy";
 import { isRecord } from "@cortex/contracts/json";
 
-import { callManagement, inputSchemaOf, loadOpenApi, ManagementError } from "@/cc/client";
-import type { OpenApiDocument, OpenApiOperation } from "@/cc/client";
-import { flagsFor, parseAnswer, toOption } from "@/cc/flags";
-import type { Flag } from "@/cc/flags";
-import { print } from "@/cc/output";
+import {
+    callManagement,
+    inputSchemaOf,
+    loadOpenApi,
+    ManagementError,
+    UnreachableError,
+} from "@/management/client";
+import type { OpenApiDocument, OpenApiOperation } from "@/management/client";
+import { flagsFor, parseAnswer, toOption } from "@/management/flags";
+import type { Flag } from "@/management/flags";
+import { print } from "@/management/output";
 import {
     ProfileFileError,
     profilesPath,
     removeProfile,
     resolveProfile,
     saveProfile,
-} from "@/cc/profiles";
+} from "@/management/profiles";
 import * as prompts from "@/ui/prompts";
 import * as report from "@/ui/report";
 
-const PROFILE_COMMANDS = new Set(["login", "logout", "status"]);
 const MAX_PAGES = 1000;
 
+/** The root command; `--profile` names the saved Cortex every command here talks to. */
+type Program = Command<[], { profile?: string }>;
+
 /**
- * `cortex cc <router> <procedure> [id] [flags]`: the Control Center's
- * management API as commands. The tree is built from the CC's own OpenAPI
- * document on each run, so it always matches the deployment it points at
- * and a new procedure needs no CLI work. Profiles hold the URL and key.
+ * `cortex <router> <procedure> [id] [flags]`: Cortex's management API as
+ * commands, beside `login`, `logout` and `status`. The tree is built from
+ * Cortex's own OpenAPI document on each run, so it always matches the
+ * deployment it points at and a new procedure needs no CLI work. Profiles
+ * hold the URL and key. Registered after every other command, since any
+ * name argv gives that none of them claims is a router's.
  */
-export function registerCc(program: Command, argv: string[]) {
-    const cc = program
-        .command("cc")
-        .helpGroup("Control Center:")
-        .summary("Manage a Control Center without its console")
-        .description(
-            "Manage a Control Center without its console.\n\nCommands come from the CC's management API: `cortex cc <router> <procedure>`.\nLog in once with a management key; profiles live in ~/.cortex/cc.json.",
-        )
-        .option("-p, --profile <name>", "Which saved Control Center to talk to")
-        .addOption(
-            new Option("-o, --output <format>", "Output format")
-                .choices(["table", "json"])
-                .default("table"),
-        )
-        .helpCommand(false);
-
-    cc.command("login")
-        .description("Save a Control Center URL and management key as a profile")
+export function registerManagement(program: Program, argv: string[]) {
+    program
+        .command("login")
+        .helpGroup("Cortex:")
+        .description("Save a Cortex URL and key as a profile")
         .option("--url <url>")
-        .option("--name <name>", "Profile name", "default")
         .action(async function (options) {
-            await login(options);
+            await login(options.url, program.opts().profile ?? "default");
         });
 
-    cc.command("logout")
+    program
+        .command("logout")
+        .helpGroup("Cortex:")
         .description("Forget a profile")
-        .option("--name <name>", "Profile name", "default")
-        .action(function (options) {
-            report.header("cortex cc logout");
+        .action(function () {
+            const name = program.opts().profile ?? "default";
+            report.header("cortex logout");
             report.footer(
-                withProfileFile(() => removeProfile(options.name))
-                    ? `removed ${options.name}`
-                    : `no profile ${options.name}`,
+                withProfileFile(() => removeProfile(name))
+                    ? `removed ${name}`
+                    : `no profile ${name}`,
             );
         });
 
-    cc.command("status")
-        .description("Which Control Center commands run against, and with which key")
+    program
+        .command("status")
+        .helpGroup("Cortex:")
+        .description("Show the Cortex URL and key commands use")
         .action(async function () {
-            const profile = requireProfile(cc.opts().profile);
-            report.header("cortex cc status");
+            const profile = requireProfile(program.opts().profile);
+            report.header("cortex status");
             report.input("Profile", profile.name);
             report.input("URL", profile.url);
             const me = await whoami(profile);
@@ -76,56 +76,56 @@ export function registerCc(program: Command, argv: string[]) {
         });
 
     // The resource tree needs the document, which needs a profile, so it is
-    // built only when argv actually names a resource command: the first
-    // operand after `cc`. Commander parses the group's own options here, so
-    // every spelling it accepts (`-p x`, `-px`, `--profile=x`) names the same
-    // profile the commands then run against. Root options may precede `cc`.
-    const at = argv.findIndex((word) => !word.startsWith("-"));
-    if (at === -1 || argv[at] !== "cc") return;
-    const { operands } = cc.parseOptions(argv.slice(at + 1));
-    const first = operands[0];
-    if (first === undefined || PROFILE_COMMANDS.has(first)) return;
-    return buildResourceCommands(cc, requireProfile(cc.opts().profile));
+    // built only when argv's first operand names no command registered so
+    // far. Commander parses the root's own options here, so every spelling
+    // it accepts (`-p x`, `-px`, `--profile=x`) names the same profile the
+    // commands then run against.
+    const first = program.parseOptions(argv).operands[0];
+    if (first === undefined || program.commands.some((command) => command.name() === first)) {
+        return;
+    }
+    return buildResourceCommands(program, requireProfile(program.opts().profile));
 }
 
 /**
  * The key is never a flag (argv is visible to other processes and lands in
- * shell history): it is prompted for masked, or read from `CORTEX_CC_KEY`
+ * shell history): it is prompted for masked, or read from `CORTEX_KEY`
  * when there is no terminal to ask.
  */
-async function login(options: { url?: string; name: string }) {
+async function login(given: string | undefined, name: string) {
     const url = requireTls(
-        (
-            options.url ?? (await prompts.askValue("Control Center URL", "https://cc.example.com"))
-        ).replace(/\/+$/, ""),
+        (given ?? (await prompts.askValue("Cortex URL", "https://cortex.example.com"))).replace(
+            /\/+$/,
+            "",
+        ),
     );
     const key = process.stdin.isTTY
         ? await prompts.askSecret("Management key")
-        : (process.env["CORTEX_CC_KEY"] ??
+        : (process.env["CORTEX_KEY"] ??
           report.fail({
               what: "No terminal to ask for the management key",
-              blocks: ["Set CORTEX_CC_KEY in the environment and run login again."],
+              blocks: ["Set CORTEX_KEY in the environment and run login again."],
           }));
     const me = await whoami({ url, key });
     if (!me) {
         report.fail({
-            what: "The Control Center rejected that key",
+            what: "Cortex rejected that key",
             blocks: [
                 "Mint one on your account page, or set BOOTSTRAP_MANAGEMENT_KEY on a headless deployment.",
             ],
         });
     }
-    withProfileFile(() => saveProfile(options.name, { url, key }));
-    report.header("cortex cc login");
-    report.input("Profile", options.name);
+    withProfileFile(() => saveProfile(name, { url, key }));
+    report.header("cortex login");
+    report.input("Profile", name);
     report.input("URL", url);
     report.input("Key", me);
     report.footer(`saved to ${profilesPath()}`);
 }
 
 /**
- * The key the Control Center recognized the bearer as, or null when it does
- * not authenticate. A Control Center that cannot be reached, or answers with
+ * The key Cortex recognized the bearer as, or null when it does not
+ * authenticate. A Cortex that cannot be reached, or answers with
  * anything but 200/401, is the run's outcome, not a CLI bug.
  */
 async function whoami(profile: { url: string; key: string }) {
@@ -145,7 +145,7 @@ async function whoami(profile: { url: string; key: string }) {
         report.fail({
             what: `Could not reach ${profile.url}`,
             error,
-            blocks: ["Check the URL and that the Control Center is up."],
+            blocks: ["Check the URL and that Cortex is up."],
         });
     }
 }
@@ -158,7 +158,7 @@ function withProfileFile<T>(operation: () => T) {
         if (error instanceof ProfileFileError) {
             report.fail({
                 what: error.message,
-                blocks: ["Fix or delete the file, then log in again:", "  cortex cc login"],
+                blocks: ["Fix or delete the file, then log in again:", "  cortex login"],
             });
         }
         throw error;
@@ -176,15 +176,17 @@ function requireTls(url: string) {
     });
 }
 
-function requireProfile(name: string | undefined) {
+/** The named profile, or the current one; a missing or plain-http one ends the run with how to fix it. */
+export function requireProfile(name: string | undefined) {
     const profile = withProfileFile(() => resolveProfile(name));
     if (!profile) {
         report.fail({
-            what: "No Control Center to talk to",
+            what: "No Cortex to talk to",
             blocks: [
                 "Log in once:",
-                "  cortex cc login",
-                "or set CORTEX_CC_URL and CORTEX_CC_KEY in the environment.",
+                "  cortex login",
+                "or set CORTEX_URL and CORTEX_KEY in the environment.",
+                "`cortex --help` lists the commands that need neither.",
             ],
         });
     }
@@ -194,11 +196,9 @@ function requireProfile(name: string | undefined) {
 
 type ResolvedProfile = NonNullable<ReturnType<typeof resolveProfile>>;
 
-type CcGroup = Command<[], { profile?: string; output: "table" | "json" }>;
-
 type Operation = { path: string; method: "get" | "post"; operation: OpenApiOperation };
 
-async function buildResourceCommands(cc: CcGroup, profile: ResolvedProfile) {
+async function buildResourceCommands(program: Program, profile: ResolvedProfile) {
     const loaded = await loadOpenApi(profile.url).catch((error: unknown) =>
         report.fail({
             what: `Could not read the management API at ${profile.url}`,
@@ -220,9 +220,12 @@ async function buildResourceCommands(cc: CcGroup, profile: ResolvedProfile) {
         [...byRouter.values()].flat().map((o) => [o.operation.operationId, o]),
     );
     for (const [router, operations] of byRouter) {
-        const group = cc.command(router).description(`${router} procedures`).helpCommand(false);
+        const group = program
+            .command(router)
+            .description(`${router} procedures`)
+            .helpCommand(false);
         for (const operation of operations) {
-            registerOperation({ cc, group, router, operation, byProcedure, document, profile });
+            registerOperation({ group, router, operation, byProcedure, document, profile });
         }
     }
 }
@@ -248,7 +251,6 @@ function groupByRouter(document: OpenApiDocument) {
  * on writes to a publishable router.
  */
 function registerOperation(scope: {
-    cc: CcGroup;
     group: Command;
     router: string;
     operation: Operation;
@@ -256,7 +258,7 @@ function registerOperation(scope: {
     document: OpenApiDocument;
     profile: ResolvedProfile;
 }) {
-    const { cc, group, router, byProcedure, document, profile } = scope;
+    const { group, router, byProcedure, document, profile } = scope;
     const { path, method, operation } = scope.operation;
     const name = operation.operationId.split(".")[1] ?? path;
     const input = inputSchemaOf(operation);
@@ -266,7 +268,7 @@ function registerOperation(scope: {
     // (`x-publish-procedure`); a create that leaves the publication content
     // blank carries none, since publishing it would only fail. Fields the
     // document marks live (`x-live-fields`) are reported as such after the
-    // write instead of as part of the draft.
+    // write, apart from the draft.
     const publishWith = operation["x-publish-procedure"];
     const publisher = publishWith === undefined ? undefined : byProcedure.get(publishWith);
     const canPublish = publisher !== undefined;
@@ -279,6 +281,7 @@ function registerOperation(scope: {
 
     command.action(async function (...args) {
         const options = command.opts() as Record<string, unknown> & {
+            output: "table" | "json";
             json?: string;
             all?: boolean;
             publish?: boolean;
@@ -286,14 +289,13 @@ function registerOperation(scope: {
         // Commander passes the options object first when the command declares
         // no argument, so only a string is the `[id]` positional.
         const positional = typeof args[0] === "string" ? args[0] : undefined;
-        const { json, all, publish, ...given } = options;
+        const { output: format, json, all, publish, ...given } = options;
         const body = await collectInput(flags, given, json, positional, name);
-        const format = cc.opts().output;
         // `-o json` promises stdout holds only the result; prose moves to stderr.
         const note = format === "json" ? report.aside : report.note;
         if (format === "table") {
-            report.header(`cortex cc ${router} ${name}`);
-            report.input("Control Center", profile.url);
+            report.header(`cortex ${router} ${name}`);
+            report.input("Cortex", profile.url);
         }
         const result = await callOrFail(profile, () =>
             all
@@ -320,9 +322,26 @@ function declareCommand(
     flags: Flag[],
     shape: { paginated: boolean; canPublish: boolean },
 ) {
-    const command = group.command(name).description(summary);
+    const command = group
+        .command(name)
+        .description(summary)
+        .addOption(
+            new Option("-o, --output <format>", "Output format")
+                .choices(["table", "json"])
+                .default("table"),
+        );
+    // Optional to Commander even when the input requires it: `--json` may hold
+    // it, and collecting the input asks for, or names, a required field left
+    // out. So the help says which it is.
     const idFlag = flags.find((flag) => flag.name === "id");
-    if (idFlag) command.argument(idFlag.required ? "<id>" : "[id]");
+    if (idFlag) {
+        command.argument(
+            "[id]",
+            idFlag.required
+                ? "Required, here or in --json, or asked for on a terminal"
+                : "Optional",
+        );
+    }
     // A sensitive field never becomes a flag: argv is visible to every
     // process on the machine and lands in shell history. It is prompted for
     // masked on a terminal, or supplied through `--json -` from stdin.
@@ -339,7 +358,7 @@ function declareCommand(
 
 /**
  * A write to a publishable router is a draft: publish it now, or say how to.
- * Fields the server reads live are already in effect and are named as such,
+ * Fields Cortex reads live are already in effect and are named as such,
  * since "draft" would understate what just happened.
  */
 async function publishAfterWrite(
@@ -351,11 +370,11 @@ async function publishAfterWrite(
 ) {
     const id = (result as { id?: string } | null)?.id;
     if (!id) return;
-    const command = `cortex cc ${publisher.operation.operationId.replace(".", " ")} ${id}`;
+    const command = `cortex ${publisher.operation.operationId.replace(".", " ")} ${id}`;
     const live = options.liveFields.length > 0;
     if (live) {
         options.note(
-            `${options.liveFields.join(", ")} ${options.liveFields.length === 1 ? "is" : "are"} live: bound on the server's next config revalidation, no publish needed.`,
+            `${options.liveFields.join(", ")} ${options.liveFields.length === 1 ? "is" : "are"} live: agents use them from their next turn, no publish needed.`,
         );
     }
     if (publish) {
@@ -370,32 +389,70 @@ async function publishAfterWrite(
     }
 }
 
-/**
- * A management refusal, or a Control Center that cannot be reached, is the
- * run's outcome, in the error grammar; anything else is a bug.
- */
-async function callOrFail<T>(profile: ResolvedProfile, call: () => Promise<T>) {
+/** `call`'s result, or the run ended by `failCall`. */
+export async function callOrFail<T>(profile: ResolvedProfile, call: () => Promise<T>) {
     try {
         return await call();
     } catch (error) {
-        if (error instanceof ManagementError) {
-            report.fail({ what: `${error.status} ${error.code}: ${error.message}` });
-        }
-        if (error instanceof TypeError) {
-            report.fail({
-                what: `Could not reach ${profile.url}`,
-                error,
-                blocks: ["Check the URL and that the Control Center is up."],
-            });
-        }
-        throw error;
+        return failCall(profile, error);
     }
 }
 
+/**
+ * A management refusal, or a Cortex that cannot be reached, is the
+ * run's outcome, in the error grammar, with whatever the refusal names;
+ * anything else is a bug, and rethrown.
+ */
+export function failCall(profile: { url: string }, error: unknown): never {
+    if (error instanceof ManagementError) {
+        report.fail({
+            what: `${error.status} ${error.code}: ${error.message}`,
+            blocks: refusalBlocks(error.detail ?? {}),
+        });
+    }
+    if (error instanceof UnreachableError) {
+        report.fail({
+            what: `Could not reach ${profile.url}`,
+            error,
+            blocks: ["Check the URL and that Cortex is up."],
+        });
+    }
+    throw error;
+}
+
+/**
+ * What a refusal names, a block each: the manifest entry it is about (its
+ * kind and name), each issue at its path in that entry, then every other
+ * field (who holds a name, what is missing) as `field: value`.
+ */
+function refusalBlocks({ error: _literal, kind, name, issues, ...rest }: Record<string, unknown>) {
+    const entry = typeof kind === "string" && typeof name === "string";
+    const fields = {
+        ...(entry ? {} : { kind, name }),
+        ...(Array.isArray(issues) ? {} : { issues }),
+        ...rest,
+    };
+    return [
+        entry ? `${kind} ${JSON.stringify(name)}` : "",
+        Array.isArray(issues) ? issues.map(issueLine).join("\n") : "",
+        Object.entries(fields)
+            .filter(([, value]) => value !== undefined)
+            .map(([key, value]) => `${key}: ${JSON.stringify(value)}`)
+            .join("\n"),
+    ].filter((block) => block !== "");
+}
+
+/** One issue at its path in the entry, or at the entry itself when the path is empty. */
+function issueLine(issue: unknown) {
+    if (!isRecord(issue)) return JSON.stringify(issue);
+    const path = issue["path"];
+    return `${typeof path === "string" && path !== "" ? path : "(entry)"}: ${String(issue["message"])}`;
+}
+
 /**
  * The body: `--json` first, flags layered over it, the positional as `id`.
- * A required field still missing is asked for on a TTY and named as the
- * flag to add otherwise.
+ * A required field left missing is asked for on a TTY and named as the
+ * flag, or the positional, to add otherwise.
  */
 async function collectInput(
     flags: Flag[],
@@ -413,7 +470,11 @@ async function collectInput(
     const missing = flags.filter((flag) => flag.required && body.get(flag.name) === undefined);
     if (missing.length > 0 && !process.stdin.isTTY) {
         const named = (flag: Flag) =>
-            flag.sensitive ? `${flag.name} (via --json -)` : `--${flag.name}`;
+            flag.name === "id"
+                ? "<id>"
+                : flag.sensitive
+                  ? `${flag.name} (via --json -)`
+                  : `--${flag.name}`;
         report.fail({
             what: `${verb} needs ${named(missing[0]!)}`,
             blocks: [
@@ -455,7 +516,7 @@ function readJsonBody(source: string) {
     if (source === "-" && process.stdin.isTTY) {
         report.fail({
             what: "--json - reads the body from stdin, but nothing is piped in",
-            blocks: ["Pipe a JSON document:", "  cat body.json | cortex cc ... --json -"],
+            blocks: ["Pipe a JSON document:", "  cat body.json | cortex ... --json -"],
         });
     }
     const label = source === "-" ? "stdin" : source;
@@ -477,7 +538,7 @@ function readJsonBody(source: string) {
     return parsed;
 }
 
-async function walkPages(
+export async function walkPages(
     profile: ResolvedProfile,
     method: "get" | "post",
     path: string,
@@ -488,8 +549,8 @@ async function walkPages(
     const items = new Array<unknown>();
     let count = 0;
     let filteredCount = 0;
-    // Bounded: a server that reports more rows than it serves must not spin,
-    // and a listing the bound cannot cover is an error, never a short result.
+    // 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,