@m6d/cortex-cli 1.0.0

package/src/commands/new.ts

@@ -0,0 +1,333 @@
+import { spawnSync } from "node:child_process";
+import { mkdirSync, readdirSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+
+import { Option, type Command } from "@commander-js/extra-typings";
+
+import pkg from "../../package.json";
+import { FEATURE_NAMES, FEATURES, type Feature } from "@/scaffold/features";
+import { scaffoldFiles, type Database } from "@/scaffold/files";
+import { allocatePorts } from "@/scaffold/ports";
+import { askDatabase, askFeatures, askName, intro, log, outro, runSteps } from "@/ui/prompts";
+import * as report from "@/ui/report";
+
+/** npm's rule for an unscoped package name. The name is the directory too. */
+const VALID_NAME = /^[a-z0-9][a-z0-9._-]*$/;
+const MAX_NAME = 214;
+
+/** The two names npm rejects outright, however well-formed they otherwise are. */
+const RESERVED_NAMES = ["node_modules", "favicon.ico"];
+
+export function registerNew(program: Command) {
+    const command = program
+        .command("new")
+        .helpGroup("Project:")
+        .description("Scaffold a new Cortex server")
+        .argument("[name]", "Directory to create, and the generated package name")
+        .addOption(
+            new Option("--database <type>", "Database the project is configured for")
+                .choices(["postgres", "mssql"] as const)
+                .default("postgres" as const),
+        )
+        // Both halves of every toggle, so a flag can answer its question either
+        // way and `--yes` is not the only way to say "no". Declaring the positive
+        // first leaves the value `undefined` when neither is passed, which is
+        // what marks the question as still unanswered.
+        .option("--attachments", FEATURES.attachments.hint)
+        .option("--no-attachments", "Leave attachments out")
+        .option("--redis", FEATURES.redis.hint)
+        .option("--no-redis", "Leave Redis out")
+        .option("--auth", FEATURES.auth.hint)
+        .option("--no-auth", "Leave auth out")
+        .option("--knowledge", FEATURES.knowledge.hint)
+        .option("--no-knowledge", "Leave the knowledge graph out")
+        .option("--control-center", FEATURES.controlCenter.hint)
+        .option("--no-control-center", "Leave the Control Center out")
+        .option("--yes", "Accept the defaults instead of asking");
+
+    command.action(async function (name, options) {
+        // The globals live on the root command, which reaches this file untyped —
+        // `Command` here is the parameter type, not cli.ts's inferred one.
+        const { verbose = false } = program.opts() as { verbose?: boolean };
+
+        await scaffold(name, {
+            ...options,
+            verbose,
+            databasePassed: command.getOptionValueSource("database") !== "default",
+        });
+    });
+}
+
+type Options = {
+    database: Database;
+    yes?: boolean;
+    verbose: boolean;
+    databasePassed: boolean;
+} & Partial<Record<Feature, boolean>>;
+
+async function scaffold(name: string | undefined, options: Options) {
+    const { verbose, databasePassed } = options;
+
+    // No TTY ⇒ never prompt and behave as `--yes` (design spec §5.3). On Bun a
+    // piped stdin reports `undefined` rather than `false`, which is why this
+    // compares against `true`.
+    const interactive = process.stdin.isTTY === true && options.yes !== true;
+
+    if (name === undefined && !interactive) missingName();
+
+    // A name that came from a flag is checked before anything prints; one that
+    // is prompted for is checked by the prompt, which can ask again.
+    if (name !== undefined && !isValidName(name)) failInvalidName(name);
+    if (name !== undefined && isTaken(resolve(process.cwd(), name))) failTaken(name);
+
+    const started = Date.now();
+    intro(`cortex new  ·  ${pkg.name} ${pkg.version}`);
+
+    const project = name ?? (await askName(checkName)).trim();
+
+    const database = interactive && !databasePassed ? await askDatabase() : options.database;
+    const features = await chooseFeatures(options, interactive);
+
+    const target = resolve(process.cwd(), project);
+
+    // Allocated here rather than inside the generators, which stay pure: picking a
+    // port means probing the machine for a free one.
+    const ports = allocatePorts();
+    const files = scaffoldFiles(project, database, features, ports);
+    let failedInstall: string | undefined;
+
+    await runSteps([
+        {
+            title: `Writing ${Object.keys(files).length} files`,
+            run: function () {
+                for (const [path, contents] of Object.entries(files)) {
+                    const file = join(target, path);
+                    mkdirSync(dirname(file), { recursive: true });
+                    writeFileSync(file, contents);
+                }
+
+                const summary = [database, ...features, "model"].join(" · ");
+                return `Wrote ${Object.keys(files).length} files to ./${project}\n${summary}`;
+            },
+        },
+        {
+            // Always, no flag: running it is what separates a scaffold from a
+            // template dump.
+            title: "Installing dependencies",
+            run: async function () {
+                // Timed from here, not from the run: the prompts above are the
+                // user's time, and "in 41.0s" of which 38 were spent answering
+                // questions is a number nobody can act on.
+                const startedInstall = Date.now();
+                const result = await install(target);
+
+                if (!result.ok) {
+                    failedInstall = result.output;
+                    // What went wrong is reported below, once the run is over;
+                    // --verbose still owes the reader the command that failed.
+                    return verbose ? "$ bun install" : undefined;
+                }
+
+                const packages = /(\d+) packages? installed/.exec(result.output)?.[1];
+                const what = packages === undefined ? "dependencies" : `${packages} packages`;
+                const done = `Installed ${what} in ${seconds(startedInstall)}`;
+                return verbose ? `$ bun install\n${done}` : done;
+            },
+        },
+        {
+            // A repo nested inside another is a mess to discover later, and the
+            // .gitignore just written is inert without one. Silent either way,
+            // which is why this step reports nothing.
+            title: "Initializing git",
+            run: function () {
+                if (isInsideWorkTree(target)) {
+                    return verbose ? "git init skipped — already inside a work tree" : undefined;
+                }
+
+                spawnSync("git", ["init"], { cwd: target, stdio: "ignore" });
+                return verbose ? "$ git init" : undefined;
+            },
+        },
+    ]);
+
+    if (failedInstall !== undefined) warnInstall(project, failedInstall, verbose);
+
+    outro(`Done in ${seconds(started)}`);
+    process.stdout.write(nextSteps(project, features, files));
+}
+
+/**
+ * The files are correct; only the install did not happen, so this warns and the
+ * run still exits 0. What bun said is the whole diagnosis, so it is kept: the
+ * last line by default, the captured log under --verbose.
+ */
+function warnInstall(project: string, output: string, verbose: boolean) {
+    const detail = verbose ? output.trim() : lastLine(output);
+
+    log.warn(
+        // clack indents continuation lines by 3, so 2 more puts the command in
+        // the same column the error grammar uses.
+        `bun install did not finish. The files are written — run it yourself:\n\n` +
+            `  cd ${project} && bun install` +
+            (detail === "" ? "" : `\n\n${detail}`),
+    );
+}
+
+function nextSteps(project: string, features: Feature[], files: ReturnType<typeof scaffoldFiles>) {
+    const keys = [
+        "CORTEX_DATABASE_URL",
+        "CORTEX_MODEL_*",
+        ...features.map((feature) => FEATURES[feature].secrets).filter((key) => key !== undefined),
+    ];
+
+    return (
+        `\nNext steps:\n\n` +
+        step(`cd ${project}`) +
+        step("edit .env", `fill in ${keys.length === 2 ? keys.join(" and ") : keys.join(", ")}`) +
+        (files["docker-compose.yml"] === undefined ? "" : step("docker compose up -d")) +
+        // The `port` the generated cortex.config.ts sets, which is the server's
+        // own default. Service ports move at scaffold time; this one does not.
+        step("bun run dev", "→ http://localhost:3331") +
+        `\n`
+    );
+}
+
+/**
+ * One multi-select for the whole catalogue, minus whatever the flags already
+ * settled: a passed flag suppresses its question, the rest are still asked.
+ */
+async function chooseFeatures(options: Options, interactive: boolean) {
+    const chosen = new Set(FEATURE_NAMES.filter((feature) => options[feature] === true));
+    const undecided = FEATURE_NAMES.filter((feature) => options[feature] === undefined);
+
+    if (interactive && undecided.length > 0) {
+        for (const feature of await askFeatures(undecided)) chosen.add(feature);
+    }
+
+    // Catalogue order, not the order the flags or the checkboxes came in.
+    return FEATURE_NAMES.filter((feature) => chosen.has(feature));
+}
+
+async function install(cwd: string) {
+    try {
+        // Piped rather than inherited: the spinner owns the screen while this runs.
+        // bun prints its summary to stderr, so both streams are read.
+        const child = Bun.spawn(["bun", "install"], { cwd, stdout: "pipe", stderr: "pipe" });
+        const output = await Promise.all([
+            new Response(child.stdout).text(),
+            new Response(child.stderr).text(),
+        ]);
+
+        return { ok: (await child.exited) === 0, output: output.join("") };
+    } catch (error) {
+        // A spawn that never starts — EACCES, EMFILE — is still just an install
+        // that did not happen, and the files are already written. It takes the
+        // same warn-and-exit-0 path as a bun install that ran and failed, rather
+        // than surfacing as "cortex hit an unexpected error".
+        return { ok: false, output: error instanceof Error ? error.message : String(error) };
+    }
+}
+
+function step(command: string, annotation?: string) {
+    // 27 puts the annotation column where cli-output.md §3 has it.
+    return annotation ? `  ${command.padEnd(27)}${annotation}\n` : `  ${command}\n`;
+}
+
+function seconds(started: number) {
+    return `${((Date.now() - started) / 1000).toFixed(1)}s`;
+}
+
+/** bun puts the reason last, and that one line is what gets pasted into a search. */
+function lastLine(output: string) {
+    return output.trim().split("\n").at(-1)?.trim() ?? "";
+}
+
+function isValidName(name: string) {
+    return name.length <= MAX_NAME && VALID_NAME.test(name) && !RESERVED_NAMES.includes(name);
+}
+
+/** The prompt's rules, which are the flag path's two failures asked one at a time. */
+function checkName(candidate: string) {
+    // One line each: clack prints them inside the prompt, which will not wrap.
+    if (RESERVED_NAMES.includes(candidate)) return `npm does not allow the name ${candidate}.`;
+    if (!isValidName(candidate)) return "Lowercase letters, digits, and . _ - only.";
+    if (isTaken(resolve(process.cwd(), candidate))) {
+        return `./${candidate} already exists and is not an empty directory.`;
+    }
+    return undefined;
+}
+
+/** `My App` → `my-app`, so the suggested command is one the user can paste. */
+function slugify(name: string) {
+    const slug = name
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9._-]+/g, "-")
+        .replace(/^[^a-z0-9]+/, "")
+        .slice(0, MAX_NAME);
+
+    return slug === "" || RESERVED_NAMES.includes(slug) ? "my-app" : slug;
+}
+
+/**
+ * A missing path is the only clean go-ahead, and an empty directory the one
+ * tolerated exception. Anything else — a regular file of that name, a directory
+ * with contents, one we lack permission to read — is a conflict: swallowing it
+ * scaffolds halfway and then dies on the first write.
+ */
+function isTaken(target: string) {
+    try {
+        return readdirSync(target).length > 0;
+    } catch (error) {
+        return !(error instanceof Error && "code" in error && error.code === "ENOENT");
+    }
+}
+
+function isInsideWorkTree(target: string) {
+    return (
+        spawnSync("git", ["rev-parse", "--is-inside-work-tree"], {
+            cwd: target,
+            stdio: "ignore",
+        }).status === 0
+    );
+}
+
+function missingName(): never {
+    // No TTY ⇒ never prompt, so a missing required argument is a hard error
+    // (design spec §5.3). With a TTY this branch is only reached under `--yes`,
+    // which answers every question including the one that has no default.
+    report.fail({
+        what:
+            process.stdin.isTTY === true
+                ? "cortex new needs a project name."
+                : "cortex new needs a project name when stdin is not a TTY.",
+        blocks: [
+            "Pass it as an argument, and --yes to accept defaults for the rest:",
+            "  cortex new my-app --yes",
+        ],
+    });
+}
+
+function failTaken(name: string): never {
+    report.fail({
+        what: `./${name} already exists and is not an empty directory.`,
+        blocks: [
+            "cortex new never merges into an existing project. Pick another name,\nor remove it first:",
+            `  rm -rf ${name}`,
+        ],
+    });
+}
+
+/**
+ * The name is the directory *and* the generated `package.json` name, so an
+ * illegal one produces a project npm refuses and a `cd` that does not parse.
+ */
+function failInvalidName(name: string): never {
+    report.fail({
+        what: `"${name}" is not a usable project name`,
+        blocks: [
+            "It becomes the directory and the generated package.json `name`, so it has\nto be one npm accepts: lowercase, no spaces, not a name npm reserves. Try:",
+            `  cortex new ${slugify(name)}`,
+        ],
+    });
+}

package/src/commands/swagger.ts

@@ -0,0 +1,285 @@
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+
+import { type Command, Option } from "@commander-js/extra-typings";
+
+import { configLabel, findConfig, loadConfig } from "@/config/load";
+import { validateConfig } from "@/config/validate";
+import { extractEndpoints } from "@/swagger/extract-endpoints";
+import * as report from "@/ui/report";
+
+/** A convention, not config: `KnowledgeConfig` has no `domainsDir` (design spec §5.5). */
+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.",
+        )
+        // 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 () {
+                // The globals live on the root command, which reaches this file
+                // untyped — `Command` here is the parameter type, not cli.ts's
+                // inferred one.
+                const { config: path, verbose = false } = program.opts() as {
+                    config: string;
+                    verbose?: boolean;
+                };
+
+                await run({
+                    verb,
+                    path,
+                    explicit: program.getOptionValueSource("config") !== "default",
+                    verbose,
+                    domainsDir: swagger.opts().domainsDir,
+                });
+            });
+    }
+}
+
+async function run(options: {
+    verb: "sync" | "check";
+    path: string;
+    explicit: boolean;
+    verbose: boolean;
+    domainsDir: string;
+}) {
+    const { verb, verbose } = options;
+    const title = `cortex swagger ${verb}`;
+
+    // Discovery runs before the box opens: with no config there is no run to
+    // report on, only the reason there isn't one.
+    const configPath = findConfig({ ...options, command: title });
+
+    report.header(title);
+    const loaded = await loadConfig(configPath, verbose);
+    validateConfig(loaded, configPath);
+    report.input("Config", configLabel(configPath));
+
+    // 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), options.domainsDir);
+    if (!existsSync(domainsDir)) failMissingDomainsDir(domainsDir, verb);
+
+    const urls = swaggerUrls(loaded);
+    for (const url of urls) report.input("Swagger", url);
+
+    const startedAt = Date.now();
+    const result = await runExtract(urls, domainsDir, verb).catch(function (error: unknown): never {
+        return failExtract({ error, configPath, verbose, verb });
+    });
+
+    // 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(options));
+}
+
+/**
+ * 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, read back the way the server's own file walk
+ * reads it. 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 source = readFileSync(filePath, "utf8");
+    const method = source.match(/^\s*method:\s*(['"])([^'"]+)\1/m)?.[2] ?? "?";
+    const route = source.match(/^\s*path:\s*(['"])([^'"]+)\1/m)?.[2] ?? "?";
+    return `${method} ${route}`;
+}
+
+/**
+ * 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.
+ */
+async function runExtract(swaggerUrls: string[], domainsDir: string, verb: "sync" | "check") {
+    if (!swaggerUrls.length) throw new Error("No swagger URLs found in knowledge config");
+
+    return await extractEndpoints({ swaggerUrls, domainsDir, write: verb === "sync" });
+}
+
+/** 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`,
+        ],
+    });
+}
+
+/**
+ * Section requirements are `runExtract`'s to enforce — it already throws
+ * `"No swagger URLs found in knowledge config"`. This renders what it threw.
+ */
+function failExtract(options: {
+    error: unknown;
+    configPath: string;
+    verbose: boolean;
+    verb: string;
+}): never {
+    const { error, configPath, verbose, verb } = options;
+    const label = configLabel(configPath);
+    const message = error instanceof Error ? error.message : String(error);
+
+    if (message === "No swagger URLs found in knowledge config") {
+        report.fail({
+            what: `${label} 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#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.
+    report.fail({
+        what: "Could not read the Swagger spec",
+        error,
+        blocks: [`Is the API running? Otherwise check knowledge.swagger.url in\n${label}.`],
+        verbose,
+    });
+}