@m6d/cortex-cli 0.1.0

package/src/cc/flags.ts

@@ -0,0 +1,135 @@
+import { InvalidArgumentError, Option } from "@commander-js/extra-typings";
+
+import type { JsonSchema, OpenApiDocument } from "./client";
+
+export type Flag = {
+    name: string;
+    required: boolean;
+    kind: "string" | "number" | "boolean" | "enum" | "array" | "json";
+    choices?: string[];
+    description: string;
+    /** A secret: never an argv flag (argv is world-readable), prompted masked or read from stdin. */
+    sensitive: boolean;
+};
+
+/** Follows a local `$ref` into `components/schemas`; anything else is returned as is. */
+function resolve(schema: JsonSchema, document: OpenApiDocument) {
+    const ref = schema.$ref?.match(/^#\/components\/schemas\/(.+)$/)?.[1];
+    return ref ? (document.components?.schemas?.[ref] ?? schema) : schema;
+}
+
+function typeOf(schema: JsonSchema) {
+    const type = Array.isArray(schema.type) ? schema.type.find((t) => t !== "null") : schema.type;
+    if (type) return type;
+    const alternative = schema.anyOf?.find((s) => s.type !== "null");
+    return alternative && !Array.isArray(alternative.type) ? alternative.type : undefined;
+}
+
+/**
+ * A secret is `format: password`, on the property itself or, for a nullable
+ * or optional one, on the non-null alternative zod puts inside `anyOf`.
+ */
+function isSensitive(property: JsonSchema, document: OpenApiDocument): boolean {
+    if (property.format === "password") return true;
+    return (property.anyOf ?? []).some((alternative) =>
+        isSensitive(resolve(alternative, document), document),
+    );
+}
+
+/** The flag kind a property's schema maps to; scalars and scalar arrays get typed flags, the rest is JSON. */
+function kindOf(property: JsonSchema, document: OpenApiDocument) {
+    if (property.enum) return "enum" as const;
+    const type = typeOf(property);
+    if (type === "string") return "string" as const;
+    if (type === "number" || type === "integer") return "number" as const;
+    if (type === "boolean") return "boolean" as const;
+    if (type === "array") {
+        const item = property.items ? resolve(property.items, document) : undefined;
+        const scalar = item && ["string", "number", "integer"].includes(typeOf(item) ?? "");
+        return scalar ? ("array" as const) : ("json" as const);
+    }
+    return "json" as const;
+}
+
+/**
+ * One flag per top-level property of an object input. Scalars, enums, and
+ * arrays of scalars become typed flags; anything nested is taken as JSON,
+ * with `--json <file|->` (see the command builder) as the way to pass a
+ * whole body. A property named `id` is what `[id]` positionals map to.
+ */
+export function flagsFor(input: JsonSchema, document: OpenApiDocument) {
+    const schema = resolve(input, document);
+    if (typeOf(schema) !== "object" || !schema.properties) return [];
+    const required = new Set(schema.required ?? []);
+    return Object.entries(schema.properties).map(([name, raw]) => {
+        const property = resolve(raw, document);
+        return {
+            name,
+            required: required.has(name),
+            kind: kindOf(property, document),
+            choices: property.enum?.map(String),
+            description: property.description ?? "",
+            sensitive: isSensitive(property, document),
+        } satisfies Flag;
+    });
+}
+
+/**
+ * A prompted answer, parsed and checked exactly as the flag's option would
+ * be; `undefined` when it does not fit, so the caller can ask again.
+ */
+export function parseAnswer(flag: Flag, answer: string) {
+    // A string is taken verbatim: a secret's whitespace is part of it. Every
+    // other kind is lexical and trimmed before parsing.
+    const text = flag.kind === "string" ? answer : answer.trim();
+    if (text === "") return undefined;
+    return ANSWER_PARSERS[flag.kind](text, flag);
+}
+
+const finite = (text: string) => (Number.isFinite(Number(text)) ? Number(text) : undefined);
+const json = (text: string) => {
+    try {
+        return JSON.parse(text) as unknown;
+    } catch {
+        return undefined;
+    }
+};
+
+/** One parser per flag kind; booleans and enums must match a choice, arrays split on commas. */
+const ANSWER_PARSERS = {
+    boolean: (text) => ({ true: true, false: false })[text],
+    enum: (text, flag) => (flag.choices?.includes(text) ? text : undefined),
+    number: finite,
+    array: (text) => text.split(",").map((item) => item.trim()),
+    json,
+    string: (text) => text,
+} satisfies Record<Flag["kind"], (text: string, flag: Flag) => unknown>;
+
+export function toOption(flag: Flag) {
+    const long = `--${flag.name}`;
+    const label = flag.description || `${flag.kind}${flag.required ? "" : " (optional)"}`;
+    switch (flag.kind) {
+        case "boolean":
+            return new Option(`${long} <true|false>`, label)
+                .choices(["true", "false"])
+                .argParser((value: string) => value === "true");
+        case "enum":
+            return new Option(`${long} <value>`, label).choices(flag.choices ?? []);
+        case "number":
+            return new Option(`${long} <number>`, label).argParser(Number);
+        case "array":
+            return new Option(`${long} <value...>`, `${label} (repeatable)`);
+        case "json":
+            return new Option(`${long} <json>`, `${label} (JSON)`).argParser((value: string) => {
+                try {
+                    return JSON.parse(value) as unknown;
+                } catch (error) {
+                    throw new InvalidArgumentError(
+                        error instanceof Error ? error.message : String(error),
+                    );
+                }
+            });
+        default:
+            return new Option(`${long} <value>`, label);
+    }
+}

package/src/cc/output.ts

@@ -0,0 +1,77 @@
+import * as report from "@/ui/report";
+
+type Listing = { items: Array<Record<string, unknown>>; count: number; filteredCount: number };
+
+function isListing(value: unknown): value is Listing {
+    return (
+        typeof value === "object" &&
+        value !== null &&
+        "items" in value &&
+        Array.isArray(value.items)
+    );
+}
+
+/**
+ * One table cell. Whatever the value's type, the rendered text is whatever a
+ * resource writer stored, so control characters (escape sequences, newlines)
+ * are flattened to spaces before they reach the terminal. JSON.stringify
+ * escapes only the C0 range, so the sweep runs on the final text; `-o json`
+ * hands the raw value to the pipe instead.
+ */
+function cell(value: unknown) {
+    if (value === null || value === undefined) return "";
+    const text =
+        typeof value === "string"
+            ? value
+            : typeof value === "number" || typeof value === "boolean" || typeof value === "bigint"
+              ? String(value)
+              : (JSON.stringify(value) ?? "");
+    return text.replace(/\p{Cc}/gu, " ");
+}
+
+/**
+ * `-o json` prints the raw result for pipes. Otherwise a listing is a table
+ * of its first-level scalar columns and an object is key/value rows; the
+ * report grammar every other command uses.
+ */
+export function print(result: unknown, format: "json" | "table") {
+    if (format === "json") {
+        process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+        return;
+    }
+    if (isListing(result)) {
+        const columns = Object.keys(result.items[0] ?? {}).filter(
+            (key) => typeof result.items[0]?.[key] !== "object" || result.items[0]?.[key] === null,
+        );
+        const widths = columns.map((column) =>
+            Math.min(
+                40,
+                Math.max(column.length, ...result.items.map((row) => cell(row[column]).length)),
+            ),
+        );
+        report.row("", columns.map((column, i) => column.padEnd(widths[i] ?? 0)).join("  "), 4);
+        for (const item of result.items) {
+            report.row(
+                "",
+                columns
+                    .map((column, i) =>
+                        cell(item[column])
+                            .slice(0, 40)
+                            .padEnd(widths[i] ?? 0),
+                    )
+                    .join("  "),
+                4,
+            );
+        }
+        report.footer(`${result.items.length} of ${result.filteredCount} (${result.count} total)`);
+        return;
+    }
+    if (typeof result === "object" && result !== null) {
+        const entries = Object.entries(result as Record<string, unknown>);
+        const width = Math.max(10, ...entries.map(([key]) => key.length + 2));
+        for (const [key, value] of entries) report.row(key, cell(value), width);
+        report.footer("done");
+        return;
+    }
+    report.footer(cell(result));
+}

package/src/cc/profiles.ts

@@ -0,0 +1,105 @@
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+type Profile = { url: string; key: string };
+type Store = { current: string; profiles: Record<string, Profile> };
+
+/** `~/.cortex/cc.json`; `CORTEX_HOME` relocates it (tests, CI). */
+export function profilesPath() {
+    return join(process.env["CORTEX_HOME"] ?? join(homedir(), ".cortex"), "cc.json");
+}
+
+/** Thrown when the profile file exists but is not one this CLI wrote. */
+export class ProfileFileError extends Error {
+    public constructor(path: string, reason: string) {
+        super(`${path} is not a valid profile file: ${reason}`);
+        this.name = "ProfileFileError";
+    }
+}
+
+function isProfile(value: unknown): value is Profile {
+    return (
+        typeof value === "object" &&
+        value !== null &&
+        typeof (value as Record<string, unknown>)["url"] === "string" &&
+        typeof (value as Record<string, unknown>)["key"] === "string"
+    );
+}
+
+function isStore(value: unknown): value is Store {
+    if (typeof value !== "object" || value === null) return false;
+    const { current, profiles } = value as Record<string, unknown>;
+    return (
+        typeof current === "string" &&
+        typeof profiles === "object" &&
+        profiles !== null &&
+        !Array.isArray(profiles) &&
+        Object.values(profiles).every(isProfile)
+    );
+}
+
+/** A profile by name, own properties only: a name like `constructor` is not a profile. */
+function lookup(store: Store, name: string) {
+    return Object.hasOwn(store.profiles, name) ? store.profiles[name] : undefined;
+}
+
+function readStore() {
+    const path = profilesPath();
+    if (!existsSync(path)) return { current: "default", profiles: {} } satisfies Store;
+    let parsed: unknown;
+    try {
+        parsed = JSON.parse(readFileSync(path, "utf8"));
+    } catch (error) {
+        throw new ProfileFileError(path, error instanceof Error ? error.message : String(error));
+    }
+    if (!isStore(parsed)) throw new ProfileFileError(path, "unexpected shape");
+    return parsed;
+}
+
+/** The key is a credential, so the file and its directory are owner-only. */
+function writeStore(store: Store) {
+    const path = profilesPath();
+    mkdirSync(join(path, ".."), { recursive: true, mode: 0o700 });
+    writeFileSync(path, `${JSON.stringify(store, null, 2)}\n`, { mode: 0o600 });
+    chmodSync(path, 0o600);
+}
+
+// Names are user input, so the store is rebuilt from entries rather than
+// assigned into: `__proto__` and friends stay ordinary keys.
+export function saveProfile(name: string, profile: Profile) {
+    const store = readStore();
+    writeStore({
+        current: name,
+        profiles: Object.fromEntries([
+            ...Object.entries(store.profiles).filter(([key]) => key !== name),
+            [name, profile],
+        ]),
+    });
+}
+
+export function removeProfile(name: string) {
+    const store = readStore();
+    const existed = lookup(store, name) !== undefined;
+    const remaining = Object.entries(store.profiles).filter(([key]) => key !== name);
+    writeStore({
+        current: store.current === name ? (remaining[0]?.[0] ?? "default") : store.current,
+        profiles: Object.fromEntries(remaining),
+    });
+    return existed;
+}
+
+/**
+ * The profile a `cc` command runs against: `CORTEX_CC_URL` + `CORTEX_CC_KEY`
+ * when both are set (CI, containers), else the named or current entry from
+ * the file. `undefined` means nobody has logged in.
+ */
+export function resolveProfile(name?: string) {
+    const url = process.env["CORTEX_CC_URL"];
+    const key = process.env["CORTEX_CC_KEY"];
+    if (url && key) return { name: "env", url: url.replace(/\/+$/, ""), key };
+    const store = readStore();
+    const chosen = name ?? store.current;
+    const profile = lookup(store, chosen);
+    return profile ? { name: chosen, ...profile } : undefined;
+}

package/src/cli.ts

@@ -0,0 +1,56 @@
+import { Command, Help } from "@commander-js/extra-typings";
+
+import pkg from "../package.json";
+import { registerCc } from "@/commands/cc";
+import { registerGraph } from "@/commands/graph";
+import { registerNew } from "@/commands/new";
+import { registerSwagger } from "@/commands/swagger";
+import * as report from "@/ui/report";
+
+const program = new Command()
+    .name("cortex")
+    .description("Scaffold and operate Cortex servers.")
+    .option("-v, --verbose", "Print full errors and the commands being run")
+    .version(pkg.version, "-V, --version", "Output the version number")
+    .helpOption("-h, --help", "Display help for command")
+    // The implicit `help [command]` would print as a third, ungrouped section and
+    // break the two-group help screen. `cortex <cmd> --help` covers it.
+    .helpCommand(false)
+    // Commander appends ` [options]` to any command that has some. Left in, the
+    // first command to grow a flag widens the whole list and the two-group screen
+    // stops matching. `cortex <command> --help` lists them.
+    .configureHelp({
+        subcommandTerm: function (cmd) {
+            return new Help().subcommandTerm(cmd).replace(" [options]", "");
+        },
+    })
+    .addHelpText("after", "\nRun `cortex <resource> --help` to see what you can do with one.");
+
+// Each command owns its help group, so the two headings survive these files being
+// rewritten. Registration order fixes the order the groups print in.
+registerNew(program);
+registerSwagger(program);
+registerGraph(program);
+// The Control Center's commands come from its API, so this one may fetch
+// before parsing; it looks at argv to decide whether it needs to.
+await registerCc(program, process.argv.slice(2));
+
+// Commander's own errors print and exit on their own, and every failure the
+// commands predict goes through `report.fail`. Anything still reaching here is a
+// bug — in the CLI, or in the project's server — and it gets the same grammar
+// rather than a raw Bun stack dump.
+await program.parseAsync().catch(function (error: unknown) {
+    const verbose = program.opts().verbose === true;
+    const rerun = process.argv.slice(2);
+    if (!verbose) rerun.push("--verbose");
+
+    report.fail({
+        what: "cortex hit an unexpected error",
+        error,
+        blocks: [
+            "That is a bug — the CLI should have explained this. Report it at\nhttps://github.com/boring91/cortex/issues with the output of:",
+            `  cortex ${rerun.join(" ")}`,
+        ],
+        verbose,
+    });
+});