@m6d/cortex-cli 0.1.0

package/src/commands/cc.ts

@@ -0,0 +1,504 @@
+import { readFileSync } from "node:fs";
+
+import { type Command, Option } from "@commander-js/extra-typings";
+import { isTlsOrLoopback } from "@cortex/contracts/egress";
+
+import { callManagement, inputSchemaOf, isRecord, 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 {
+    ProfileFileError,
+    profilesPath,
+    removeProfile,
+    resolveProfile,
+    saveProfile,
+} from "@/cc/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;
+
+/**
+ * `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.
+ */
+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")
+        .option("--url <url>")
+        .option("--name <name>", "Profile name", "default")
+        .action(async function (options) {
+            await login(options);
+        });
+
+    cc.command("logout")
+        .description("Forget a profile")
+        .option("--name <name>", "Profile name", "default")
+        .action(function (options) {
+            report.header("cortex cc logout");
+            report.footer(
+                withProfileFile(() => removeProfile(options.name))
+                    ? `removed ${options.name}`
+                    : `no profile ${options.name}`,
+            );
+        });
+
+    cc.command("status")
+        .description("Which Control Center commands run against, and with which key")
+        .action(async function () {
+            const profile = requireProfile(cc.opts().profile);
+            report.header("cortex cc status");
+            report.input("Profile", profile.name);
+            report.input("URL", profile.url);
+            const me = await whoami(profile);
+            report.footer(me ? `authenticated with ${me}` : "key rejected");
+        });
+
+    // 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));
+}
+
+/**
+ * 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`
+ * when there is no terminal to ask.
+ */
+async function login(options: { url?: string; name: string }) {
+    const url = requireTls(
+        (
+            options.url ?? (await prompts.askValue("Control Center URL", "https://cc.example.com"))
+        ).replace(/\/+$/, ""),
+    );
+    const key = process.stdin.isTTY
+        ? await prompts.askSecret("Management key")
+        : (process.env["CORTEX_CC_KEY"] ??
+          report.fail({
+              what: "No terminal to ask for the management key",
+              blocks: ["Set CORTEX_CC_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",
+            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);
+    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
+ * anything but 200/401, is the run's outcome, not a CLI bug.
+ */
+async function whoami(profile: { url: string; key: string }) {
+    try {
+        const me = (await callManagement(profile, "get", "/management-keys/mine", undefined)) as {
+            name: string;
+            fingerprint: string;
+        };
+        return `key "${me.name}" (${me.fingerprint})`;
+    } catch (error) {
+        if (error instanceof ManagementError && error.status === 401) return null;
+        if (error instanceof ManagementError) {
+            report.fail({
+                what: `${profile.url} answered ${error.status} ${error.code}: ${error.message}`,
+            });
+        }
+        report.fail({
+            what: `Could not reach ${profile.url}`,
+            error,
+            blocks: ["Check the URL and that the Control Center is up."],
+        });
+    }
+}
+
+/** Runs a profile-file operation; a file this CLI cannot read is an input error, not a crash. */
+function withProfileFile<T>(operation: () => T) {
+    try {
+        return operation();
+    } catch (error) {
+        if (error instanceof ProfileFileError) {
+            report.fail({
+                what: error.message,
+                blocks: ["Fix or delete the file, then log in again:", "  cortex cc login"],
+            });
+        }
+        throw error;
+    }
+}
+
+/** The key rides on every call, so the URL it goes to must be https (or loopback). */
+function requireTls(url: string) {
+    if (isTlsOrLoopback(url)) return url;
+    return report.fail({
+        what: `${url} is not https`,
+        blocks: [
+            "The management key would travel in the clear. Use an https URL (http is allowed on localhost only).",
+        ],
+    });
+}
+
+function requireProfile(name: string | undefined) {
+    const profile = withProfileFile(() => resolveProfile(name));
+    if (!profile) {
+        report.fail({
+            what: "No Control Center to talk to",
+            blocks: [
+                "Log in once:",
+                "  cortex cc login",
+                "or set CORTEX_CC_URL and CORTEX_CC_KEY in the environment.",
+            ],
+        });
+    }
+    requireTls(profile.url);
+    return profile;
+}
+
+type Resolved = 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: Resolved) {
+    const loaded = await loadOpenApi(profile.url).catch((error: unknown) =>
+        report.fail({
+            what: `Could not read the management API at ${profile.url}`,
+            error,
+            blocks: [
+                "The command list comes from /api/management/openapi.json; nothing is cached yet.",
+            ],
+        }),
+    );
+    if (loaded.from === "stale")
+        report.aside(`Using cached commands; ${profile.url} is unreachable.`);
+    const { document } = loaded;
+
+    // Every operation by procedure path, so a write can find the operation
+    // its `x-publish-procedure` names and invoke it by that operation's own
+    // method and path.
+    const byProcedure = new Map(
+        [...groupByRouter(document).values()].flat().map((o) => [o.operation.operationId, o]),
+    );
+    for (const [router, operations] of groupByRouter(document)) {
+        const group = cc.command(router).description(`${router} procedures`).helpCommand(false);
+        for (const operation of operations) {
+            registerOperation({ cc, group, router, operation, byProcedure, document, profile });
+        }
+    }
+}
+
+/** Operations by their router tag, the first path segment when untagged. */
+function groupByRouter(document: OpenApiDocument) {
+    const byRouter = new Map<string, Operation[]>();
+    for (const [path, methods] of Object.entries(document.paths)) {
+        for (const [method, operation] of Object.entries(methods)) {
+            const router = operation.tags?.[0] ?? path.split("/")[1] ?? "";
+            byRouter.set(router, [
+                ...(byRouter.get(router) ?? []),
+                { path, method: method as "get" | "post", operation },
+            ]);
+        }
+    }
+    return byRouter;
+}
+
+/**
+ * One procedure as one command: a positional for `id`, a typed flag per
+ * field, `--json` for a whole body, `--all` on paginated reads, `--publish`
+ * on writes to a publishable router.
+ */
+function registerOperation(scope: {
+    cc: CcGroup;
+    group: Command;
+    router: string;
+    operation: Operation;
+    byProcedure: Map<string, Operation>;
+    document: OpenApiDocument;
+    profile: Resolved;
+}) {
+    const { cc, group, router, byProcedure, document, profile } = scope;
+    const { path, method, operation } = scope.operation;
+    const name = operation.operationId.split(".")[1] ?? path;
+    const input = inputSchemaOf(operation);
+    const flags = input ? flagsFor(input, document) : [];
+    const paginated = method === "get" && flags.some((flag) => flag.name === "pageIndex");
+    // `--publish` rides only on writes the document says can be published
+    // (`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.
+    const publishWith = operation["x-publish-procedure"];
+    const publisher = publishWith === undefined ? undefined : byProcedure.get(publishWith);
+    const canPublish = publisher !== undefined;
+    const liveFields = operation["x-live-fields"] ?? [];
+
+    const command = declareCommand(group, name, operation.summary ?? "", flags, {
+        paginated,
+        canPublish,
+    });
+
+    command.action(async function (...args) {
+        const options = command.opts() as Record<string, unknown> & {
+            json?: string;
+            all?: boolean;
+            publish?: boolean;
+        };
+        // 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 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);
+        }
+        const result = await callOrFail(profile, () =>
+            all
+                ? walkPages(profile, method, path, body)
+                : callManagement(profile, method, path, body),
+        );
+        print(result, format);
+        if (publisher) {
+            await publishAfterWrite(profile, publisher, result, publish === true, {
+                note,
+                liveFields: liveFields.filter(
+                    (field) => isRecord(body) && body[field] !== undefined,
+                ),
+            });
+        }
+    });
+}
+
+/** The command's arguments and options, from what its input schema admits. */
+function declareCommand(
+    group: Command,
+    name: string,
+    summary: string,
+    flags: Flag[],
+    shape: { paginated: boolean; canPublish: boolean },
+) {
+    const command = group.command(name).description(summary);
+    const idFlag = flags.find((flag) => flag.name === "id");
+    if (idFlag) command.argument(idFlag.required ? "<id>" : "[id]");
+    // 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.
+    for (const flag of flags) {
+        if (flag.name !== "id" && !flag.sensitive) command.addOption(toOption(flag));
+    }
+    if (flags.length > 0) {
+        command.option("--json <file>", "Read the whole input from a JSON file, or - for stdin");
+    }
+    if (shape.paginated) command.option("--all", "Walk every page");
+    if (shape.canPublish) command.option("--publish", "Publish the entity right after saving");
+    return command;
+}
+
+/**
+ * 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,
+ * since "draft" would understate what just happened.
+ */
+async function publishAfterWrite(
+    profile: Resolved,
+    publisher: Operation,
+    result: unknown,
+    publish: boolean,
+    options: { note: (text: string) => void; liveFields: string[] },
+) {
+    const id = (result as { id?: string } | null)?.id;
+    if (!id) return;
+    const command = `cortex cc ${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.`,
+        );
+    }
+    if (publish) {
+        await callOrFail(profile, () =>
+            callManagement(profile, publisher.method, publisher.path, { id }),
+        );
+        options.note(`Published ${id}.`);
+    } else {
+        options.note(
+            `${live ? "The rest is" : "Saved as"} a draft. Add --publish, or run: ${command}`,
+        );
+    }
+}
+
+/**
+ * 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: Resolved, 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;
+    }
+}
+
+/**
+ * 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.
+ */
+async function collectInput(
+    flags: Flag[],
+    given: Record<string, unknown>,
+    jsonSource: string | undefined,
+    positional: string | undefined,
+    verb: string,
+) {
+    const body = new Map(Object.entries(jsonSource ? readJsonBody(jsonSource) : {}));
+    for (const flag of flags) {
+        if (given[flag.name] !== undefined) body.set(flag.name, given[flag.name]);
+    }
+    if (positional !== undefined) body.set("id", positional);
+
+    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}`;
+        report.fail({
+            what: `${verb} needs ${named(missing[0]!)}`,
+            blocks: [
+                `Required: ${missing.map(named).join(" ")}`,
+                ...(missing.some((flag) => flag.sensitive)
+                    ? ["Secrets are not flags. Pipe them in a JSON body: ... --json -"]
+                    : []),
+            ],
+        });
+    }
+    for (const flag of missing) body.set(flag.name, await askUntilValid(flag));
+    return Object.fromEntries(body);
+}
+
+/** Asks for one field until the answer parses the way the flag would. */
+async function askUntilValid(flag: Flag) {
+    const hint = flag.choices?.join(" | ") ?? flag.description ?? flag.kind;
+    for (;;) {
+        const answer = flag.sensitive
+            ? await prompts.askSecret(flag.name)
+            : await prompts.askValue(flag.name, hint);
+        const value = parseAnswer(flag, answer);
+        if (value !== undefined) return value;
+        report.note(`${flag.name} must be ${flag.choices ? `one of ${hint}` : `a ${flag.kind}`}.`);
+    }
+}
+
+/** JSON the user supplied; a parse failure is their input, not a crash. */
+function parseJson(text: string, what: string) {
+    try {
+        return JSON.parse(text) as unknown;
+    } catch (error) {
+        return report.fail({ what: `${what} is not valid JSON`, error });
+    }
+}
+
+/** The `--json` body: an object, since flags and the positional layer over it. */
+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 -"],
+        });
+    }
+    const label = source === "-" ? "stdin" : source;
+    let text: string;
+    try {
+        text = readFileSync(source === "-" ? 0 : source, "utf8");
+    } catch (error) {
+        return report.fail({ what: `Could not read ${label}`, error });
+    }
+    const parsed = parseJson(text, label);
+    if (!isRecord(parsed)) {
+        report.fail({
+            what: `${label} must hold a JSON object`,
+            blocks: [
+                "Flags and the positional id are layered over it, so it cannot be a bare value.",
+            ],
+        });
+    }
+    return parsed;
+}
+
+async function walkPages(profile: Resolved, method: "get" | "post", path: string, body: unknown) {
+    const given = isRecord(body) ? body : {};
+    const pageSize = typeof given["pageSize"] === "number" ? given["pageSize"] : 100;
+    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.
+    for (let pageIndex = 0; pageIndex < MAX_PAGES; pageIndex += 1) {
+        const page = (await callManagement(profile, method, path, {
+            ...given,
+            pageIndex,
+            pageSize,
+        })) as { items?: unknown[]; count?: number; filteredCount?: number };
+        if (!Array.isArray(page.items)) return page;
+        items.push(...page.items);
+        count = page.count ?? items.length;
+        filteredCount = page.filteredCount ?? items.length;
+        if (page.items.length < pageSize || items.length >= filteredCount) {
+            return { items, count, filteredCount };
+        }
+    }
+    return report.fail({
+        what: `--all stopped after ${MAX_PAGES} pages with ${items.length} of ${filteredCount} rows`,
+        blocks: ["Narrow the listing with a filter, or raise --pageSize."],
+    });
+}