@m6d/cortex-cli 0.1.0

package/README.md

@@ -0,0 +1,175 @@
+# @m6d/cortex-cli
+
+The `cortex` command line: scaffold Cortex servers, and run the generators that otherwise need a
+hand-written script.
+
+```sh
+bunx @m6d/cortex-cli new my-app   # from nowhere — scaffolds a project
+bunx cortex swagger sync          # inside a project — reads its cortex.config.ts
+bunx cortex graph seed
+```
+
+Commands are noun-first — `cortex <resource> <verb>` — except `new`, which acts on no existing
+resource. Run `cortex --help`, then `cortex <resource> --help`.
+
+```sh
+bun add -d @m6d/cortex-cli
+```
+
+Requires [Bun](https://bun.sh). The binary re-execs itself under Bun when Node started it, and tells
+you how to install Bun when it is genuinely absent.
+
+## `cortex new`
+
+Scaffolds `./<name>`: a standalone project with `cortex.config.ts`, `index.ts`, `.env` and
+`.env.example`, inlined eslint/prettier/cspell/fallow config, and a `docker-compose.yml` when a
+selection contributes a service. It then runs `bun install`, and `git init` unless the target is
+already inside a work tree. An existing non-empty directory is an error.
+
+```sh
+bunx @m6d/cortex-cli new widget-backend --knowledge --redis
+```
+
+On a TTY it asks only what the flags left open — the name, the database, and one multi-select over
+the undecided features. With no TTY it never prompts and behaves as `--yes`, so a missing name is a
+hard error rather than a hang.
+
+| Flag                                       | Default    | Writes                                                                    |
+| ------------------------------------------ | ---------- | ------------------------------------------------------------------------- |
+| `--database <postgres\|mssql>`             | `postgres` | The `database` block. `postgres` also gets a compose service; `mssql` not |
+| `--attachments` / `--no-attachments`       | off        | `storage` + `vision` — MinIO uploads, described by a vision model         |
+| `--redis` / `--no-redis`                   | off        | `redis` — resumable streams across restarts                               |
+| `--auth` / `--no-auth`                     | off        | `auth` — JWT verification via JWKS                                        |
+| `--knowledge` / `--no-knowledge`           | off        | `neo4j` + `embedding` + `knowledge`, plus a `src/domains/` tree           |
+| `--control-center` / `--no-control-center` | off        | `controlCenter`                                                           |
+| `--yes`                                    |            | Accept the defaults instead of asking                                     |
+
+Unselected features are still written to `cortex.config.ts`, commented out, alongside `fastModel`,
+`reranker`, and `context` — the generated config documents what else exists. Every credential and
+URL is a placeholder in `.env`; none of them is prompted for.
+
+## `cortex swagger sync` / `check`
+
+Fetches every Swagger URL the config names — server-level and per-agent, deduped — and reconciles
+the `.endpoint.ts` files under the domains directory against it.
+
+```sh
+bunx cortex swagger sync
+bunx cortex swagger check
+bunx cortex swagger sync --domains-dir ./server/src/domains
+```
+
+`sync` rewrites each endpoint's params, body, and response schemas in place and prints only the
+files it changed; unchanged ones live in the footer count. `check` writes nothing, reports the drift
+it found, and exits 2 — which is what makes it a CI step.
+
+An endpoint file pointing at a route the spec no longer serves is `MISSING`. `sync` prints those
+last, so they are the thing you read, and still exits 0: writing is its job. `check` counts them as
+a finding, same as drift.
+
+`-d, --domains-dir <path>` is declared on the `swagger` group, so it works on either side of the
+verb. It defaults to `src/domains`, resolved relative to the config file.
+
+## `cortex graph seed`
+
+Loads every domain the config declares — server-level `knowledge.domains` and per-agent ones,
+deduped — and seeds Neo4j with the concepts, endpoints, services, and rules they declare, then
+embeds them. Reports per domain, because a domain is the unit you edit. No
+flags.
+
+```sh
+bunx cortex graph seed
+```
+
+Seeding is `MERGE`-based, so re-running is safe. If any statement failed, the graph is partially
+seeded and the command exits 1 — a half-seeded graph should not pass as success.
+
+## `cortex cc`
+
+Manage a Control Center without its console. The commands come from the
+Control Center's own management API (`/api/management/openapi.json`), fetched
+on each run and cached, so the tree always matches the deployment you point
+at and a new procedure needs no CLI release.
+
+```sh
+cortex cc login                          # asks for the URL and a management key
+cortex cc status
+cortex cc agents list
+cortex cc agents create --slug support --name Support --serverId <uuid>
+cortex cc tools create --json tool.json --publish
+cortex cc tools list -o json | jq '.items[].name'
+cortex cc logout
+```
+
+Profiles live in `~/.cortex/cc.json` (owner-only). `--profile <name>` picks
+one; `CORTEX_CC_URL` and `CORTEX_CC_KEY`, both set, win over the file for CI.
+`CORTEX_HOME` relocates the directory.
+
+The grammar is `cortex cc <router> <procedure> [id] [flags]`. Each top-level
+input field is a flag typed from the API's schema; nested values take JSON,
+and `--json <file|->` supplies a whole body that flags then override. A
+required field left out is asked for on a terminal and named as the missing
+flag otherwise. Listings take `--pageIndex`, `--pageSize`, `--q`, and `--all`
+to walk every page. `-o json` prints the raw result for pipes.
+
+Writes to agents, tools, services, skills, triggers, and dataset hosts save
+drafts.
+`--publish` on a write the API marks publishable (`update`, and a `create`
+whose result is complete enough) runs that entity's publish procedure right
+after; without it the command says so and names the command. Live fields bind
+on the server's next config revalidation without a publish: a trigger's
+`credential` (a secret, so it is prompted for or piped in with `--json -`
+rather than passed as a flag) and a dataset host's url, access fields, and
+timeout. `cortex cc dataset-hosts sync <id>` reads a host's manifest, and a
+draft host publishes only after `dataset-hosts test` reached it once.
+
+## Global options
+
+| Option          | Description                                  |
+| --------------- | -------------------------------------------- |
+| `-v, --verbose` | Print full errors and the commands being run |
+| `-V, --version` | Output the version number                    |
+| `-h, --help`    | Display help for command                     |
+
+`swagger` and `graph` read the project and take `-c, --config <path>` (default
+`./cortex.config.ts`) on the group or the verb. `new` and `cc` do not touch a
+project and have no such flag.
+
+Config discovery is that exact filename in the directory you run in, with no upward search. There is
+no `--cwd`: Bun auto-loads `.env` relative to the process cwd before any of our code runs, so
+reading another directory's config from here would pair it with the wrong environment. `cd` first,
+or point `--config` at the file.
+
+The config is inert data — a plain object literal the CLI imports. Any key that is present but
+evaluates to `undefined`, usually a missing environment variable, is listed by path and stops the
+run.
+
+`graph seed` runs standalone: it never constructs or serves your `@m6d/cortex-server` — it only
+imports your `cortex.config.ts` (whose own imports may pull the server's modules in, inertly).
+Its Neo4j client, its embedder and its `GRAPH_SCHEMA` come from the graph contract the server
+reads the graph back with (each package vendors its own copy at pack time; the server re-exports
+it) — one contract, shared from both ends. Seeding stamps the schema
+version it wrote onto the graph; if that graph already carries a different one, the CLI says so and
+seeds anyway, noting that nodes from the old schema are not removed. Skew is caught on the reading
+side, where it matters: the server checks the stamp on its first resolve and refuses a graph it
+cannot read.
+
+`swagger` writes `.endpoint.ts` source whose generated block has to satisfy the server's own
+`EndpointDef`, so a codegen that outran the installed version is a loud type error in your
+`bun run check`.
+
+Your `cortex.config.ts` imports `@m6d/cortex-server` for `defineAgent`, so a project without it
+installed fails on the import — reported as an unloadable config, with the missing package named.
+
+## Exit codes
+
+| Command         | 0                                             | 1                                   | 2                      |
+| --------------- | --------------------------------------------- | ----------------------------------- | ---------------------- |
+| `new`           | Files written — even if `bun install` failed  | Bad target, missing name, cancelled | —                      |
+| `swagger sync`  | Wrote what it could, `MISSING` files included | Couldn't run                        | —                      |
+| `swagger check` | Every endpoint file matched and in sync       | Couldn't run                        | Drift and/or `MISSING` |
+| `graph seed`    | Everything seeded                             | A statement failed, or couldn't run | —                      |
+
+_Couldn't run_ means no config file, an unloadable config (a missing `@m6d/cortex-server` in the
+project reads as one), undefined values in it, an absent domains directory, or an unreachable
+Swagger host or Neo4j.

package/bin/cortex.js

@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+
+// Plain JavaScript, and a Node shebang, on purpose: `bunx` honours the shebang
+// unless you pass `--bun`, so Node parses this file on the normal path. A
+// `#!/usr/bin/env bun` shebang would give a user without Bun
+// `env: bun: No such file or directory` — unrecoverable, because none of our
+// code ever runs.
+
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+
+if (process.versions.bun) {
+    await import("../src/cli");
+} else {
+    const cli = fileURLToPath(new URL("../src/cli.ts", import.meta.url));
+    const args = [cli, ...process.argv.slice(2)];
+    let result = spawnSync("bun", args, { stdio: "inherit" });
+
+    // Node's CVE-2024-27980 fix refuses to spawn a `.cmd` file directly, which is
+    // exactly what an npm-installed Bun is on Windows: the user has Bun and still
+    // gets EINVAL. `shell: true` is the documented way through; every argument is
+    // quoted because cmd.exe splits on the spaces in a Windows path otherwise.
+    if (result.error?.code === "EINVAL" && process.platform === "win32") {
+        result = spawnSync("bun", args.map(quote), { stdio: "inherit", shell: true });
+    }
+
+    // Any spawn error at all means Bun did not run, and the reason matters less
+    // than the fix — a raw `Error: spawnSync bun EACCES` helps nobody.
+    if (result.error) {
+        process.stderr.write(
+            "\n■  cortex needs Bun.\n" +
+                (result.error.code === "ENOENT" ? "" : `\n   ${result.error.message}\n`) +
+                "\n     curl -fsSL https://bun.sh/install | bash\n" +
+                "\n   Then:  bunx @m6d/cortex-cli new\n\n",
+        );
+        process.exit(1);
+    }
+
+    // A signal-killed child reports `status: null`. Exiting 1 would turn the
+    // user's Ctrl-C into a generic failure, so the signal is re-raised on
+    // ourselves and the shell sees the 130/143 it expects. If the signal is
+    // ignored or blocked and we survive it, the exit below still runs.
+    if (result.signal) {
+        process.kill(process.pid, result.signal);
+    }
+
+    process.exit(result.status ?? 1);
+}
+
+function quote(argument) {
+    return `"${argument}"`;
+}

package/package.json

@@ -0,0 +1,41 @@
+{
+    "name": "@m6d/cortex-cli",
+    "version": "0.1.0",
+    "description": "Scaffold and operate Cortex servers",
+    "license": "MIT",
+    "type": "module",
+    "bin": {
+        "cortex": "./bin/cortex.js"
+    },
+    "files": [
+        "bin",
+        "src",
+        "!src/**/*.test.ts",
+        "tsconfig.json",
+        "README.md"
+    ],
+    "scripts": {
+        "check": "tsc --noEmit",
+        "prepack": "rm -rf src/contracts && cp -R ../../internal/contracts/src src/contracts",
+        "postpack": "rm -rf src/contracts",
+        "test": "bun test"
+    },
+    "dependencies": {
+        "@clack/prompts": "^1.7.0",
+        "@commander-js/extra-typings": "^15.0.0",
+        "commander": "^15.0.0",
+        "picocolors": "^1.1.1"
+    },
+    "devDependencies": {
+        "@cortex/contracts": "workspace:*",
+        "@types/bun": "1.3.14",
+        "typescript": "~6.0.3"
+    },
+    "publishConfig": {
+        "access": "public"
+    },
+    "releaseWatchPaths": [
+        "internal/contracts",
+        "packages/cortex-server"
+    ]
+}

package/src/cc/client.ts

@@ -0,0 +1,295 @@
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+import { profilesPath } from "./profiles";
+
+export type OpenApiOperation = {
+    operationId: string;
+    summary?: string;
+    tags?: string[];
+    /** The Control Center's own semantics, so nothing here is inferred from names or prose. */
+    "x-destructive"?: true;
+    "x-publish-procedure"?: string;
+    "x-live-fields"?: string[];
+    /** A query's input, one parameter per field; a field the URL cannot carry as a scalar has JSON `content` instead of a `schema`. */
+    parameters?: Array<{
+        name: string;
+        in: string;
+        required?: boolean;
+        schema?: JsonSchema;
+        content?: Record<string, { schema: JsonSchema }>;
+    }>;
+    requestBody?: { content: Record<string, { schema: JsonSchema }> };
+};
+export type JsonSchema = {
+    type?: string | string[];
+    properties?: Record<string, JsonSchema>;
+    required?: string[];
+    enum?: unknown[];
+    items?: JsonSchema;
+    anyOf?: JsonSchema[];
+    default?: unknown;
+    description?: string;
+    format?: string;
+    $ref?: string;
+};
+export type OpenApiDocument = {
+    info: { version: string };
+    paths: Record<string, Record<string, OpenApiOperation>>;
+    components?: { schemas?: Record<string, JsonSchema> };
+};
+
+type Cached = { etag: string; document: OpenApiDocument };
+
+/**
+ * One cache entry per Control Center base URL (scheme, host, port, path),
+ * so an http and an https profile, or two deployments under one host, never
+ * read each other's document. The host keeps the file recognizable; a hash
+ * of the whole URL keeps two URLs from ever sharing a name.
+ */
+function cachePath(url: string) {
+    const { host } = new URL(url);
+    const digest = createHash("sha256").update(url).digest("base64url").slice(0, 16);
+    return join(
+        dirname(profilesPath()),
+        "cache",
+        `${host.replace(/[^\w.-]+/g, "_")}-${digest}.json`,
+    );
+}
+
+/**
+ * Enough of an OpenAPI document to build commands from: `info.version`, a
+ * `paths` object whose every operation has an `operationId` and, where
+ * present, object-shaped `parameters`, `requestBody`, and `components`.
+ * Deeper schema shapes are read defensively by the flag builder.
+ */
+function isOpenApiDocument(value: unknown): value is OpenApiDocument {
+    if (!isRecord(value)) return false;
+    const { info, paths, components } = value;
+    if (!isRecord(info) || typeof info["version"] !== "string") return false;
+    if (components !== undefined) {
+        if (!isRecord(components)) return false;
+        const { schemas } = components;
+        if (
+            schemas !== undefined &&
+            !(isRecord(schemas) && Object.values(schemas).every(isJsonSchema))
+        )
+            return false;
+    }
+    return (
+        isRecord(paths) &&
+        Object.values(paths).every(
+            (methods) => isRecord(methods) && Object.values(methods).every(isOperation),
+        )
+    );
+}
+
+/**
+ * The schema subset the flag builder reads: `type`, `properties`, `required`,
+ * `enum`, `items`, `anyOf`, `description`, `format`, `$ref`, each of its
+ * declared shape when present. Checked recursively so a nested `null` never
+ * reaches it.
+ */
+function isJsonSchema(value: unknown): value is JsonSchema {
+    return isRecord(value) && Object.entries(SCHEMA_FIELDS).every(([key, ok]) => ok(value[key]));
+}
+
+const isString = (value: unknown) => typeof value === "string";
+const isStrings = (value: unknown) => Array.isArray(value) && value.every(isString);
+const optional = (check: (value: unknown) => boolean) => (value: unknown) =>
+    value === undefined || check(value);
+
+/** One check per field the flag builder reads; anything else in the schema is ignored. */
+const SCHEMA_FIELDS = {
+    type: optional((v) => isString(v) || isStrings(v)),
+    properties: optional((v) => isRecord(v) && Object.values(v).every(isJsonSchema)),
+    required: optional(isStrings),
+    enum: optional(Array.isArray),
+    items: optional(isJsonSchema),
+    anyOf: optional((v) => Array.isArray(v) && v.every(isJsonSchema)),
+    description: optional(isString),
+    format: optional(isString),
+    $ref: optional(isString),
+} satisfies Record<string, (value: unknown) => boolean>;
+
+function isContent(value: unknown): value is Record<string, { schema: JsonSchema }> {
+    return (
+        isRecord(value) &&
+        Object.values(value).every((media) => isRecord(media) && isJsonSchema(media["schema"]))
+    );
+}
+
+function isOperation(value: unknown): value is OpenApiOperation {
+    if (!isRecord(value) || typeof value["operationId"] !== "string") return false;
+    const { summary, tags, parameters, requestBody } = value;
+    const publishProcedure = value["x-publish-procedure"];
+    const liveFields = value["x-live-fields"];
+    if (summary !== undefined && typeof summary !== "string") return false;
+    if (publishProcedure !== undefined && typeof publishProcedure !== "string") return false;
+    if (
+        liveFields !== undefined &&
+        !(Array.isArray(liveFields) && liveFields.every((f) => typeof f === "string"))
+    )
+        return false;
+    if (tags !== undefined && !(Array.isArray(tags) && tags.every((t) => typeof t === "string")))
+        return false;
+    if (
+        parameters !== undefined &&
+        !(
+            Array.isArray(parameters) &&
+            parameters.every(
+                (p) =>
+                    isRecord(p) &&
+                    typeof p["name"] === "string" &&
+                    typeof p["in"] === "string" &&
+                    (p["required"] === undefined || typeof p["required"] === "boolean") &&
+                    (p["schema"] === undefined || isJsonSchema(p["schema"])) &&
+                    (p["content"] === undefined || isContent(p["content"])),
+            )
+        )
+    )
+        return false;
+    return (
+        requestBody === undefined || (isRecord(requestBody) && isContent(requestBody["content"]))
+    );
+}
+
+function isCached(value: unknown): value is Cached {
+    return (
+        isRecord(value) && typeof value["etag"] === "string" && isOpenApiDocument(value["document"])
+    );
+}
+
+export function isRecord(value: unknown): value is Record<string, unknown> {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** A cache entry that fails to parse or has the wrong shape is treated as absent. */
+function readCache(path: string) {
+    if (!existsSync(path)) return undefined;
+    try {
+        const parsed: unknown = JSON.parse(readFileSync(path, "utf8"));
+        return isCached(parsed) ? parsed : undefined;
+    } catch {
+        return undefined;
+    }
+}
+
+/**
+ * The management API's OpenAPI document, which is what the command tree is
+ * built from. Revalidated with `If-None-Match` on every run and cached beside
+ * the profiles, so a second run costs one 304 and an offline run still has
+ * commands. `null` when neither the network nor the cache can supply it.
+ */
+export async function loadOpenApi(url: string) {
+    const path = cachePath(url);
+    const cached = readCache(path);
+    try {
+        const response = await fetch(`${url}/api/management/openapi.json`, {
+            headers: cached ? { "If-None-Match": cached.etag } : {},
+        });
+        if (response.status === 304 && cached)
+            return { document: cached.document, from: "cache" as const };
+        if (!response.ok) throw new Error(`HTTP ${response.status}`);
+        const document: unknown = await response.json();
+        if (!isOpenApiDocument(document)) throw new Error("not an OpenAPI document");
+        writeCache(path, { etag: response.headers.get("etag") ?? "", document });
+        return { document, from: "network" as const };
+    } catch (error) {
+        if (cached) return { document: cached.document, from: "stale" as const, error };
+        throw error;
+    }
+}
+
+/** Best-effort: a cache that cannot be written costs the next run a fetch, nothing more. */
+function writeCache(path: string, entry: Cached) {
+    try {
+        mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+        writeFileSync(path, JSON.stringify(entry));
+    } catch {
+        // The document in hand is still good; the next run refetches.
+    }
+}
+
+/**
+ * The input schema of one operation as a single object schema, whichever way
+ * the document spells it: a query's parameters are folded back into the
+ * object they were spread from, a mutation's request body is taken as is.
+ */
+export function inputSchemaOf(operation: OpenApiOperation) {
+    if (operation.requestBody) {
+        return operation.requestBody.content["application/json"]?.schema;
+    }
+    const parameters = operation.parameters?.filter((p) => p.in === "query") ?? [];
+    if (parameters.length === 0) return undefined;
+    const properties: Record<string, JsonSchema> = {};
+    const required: string[] = [];
+    for (const parameter of parameters) {
+        const schema = parameter.schema ?? parameter.content?.["application/json"]?.schema;
+        if (!schema) continue;
+        properties[parameter.name] = schema;
+        if (parameter.required) required.push(parameter.name);
+    }
+    return { type: "object", properties, required } satisfies JsonSchema;
+}
+
+/**
+ * One management call. A query's input object is spread over the query
+ * string, one parameter per field, with a scalar written plainly and
+ * anything else JSON-encoded, which is how the document declares it. A
+ * mutation posts its input as the JSON body. The error body's message on
+ * failure.
+ */
+export async function callManagement(
+    profile: { url: string; key: string },
+    method: "get" | "post",
+    path: string,
+    input: unknown,
+) {
+    const base = `${profile.url}/api/management${path}`;
+    const url = method === "get" && isRecord(input) ? `${base}${queryString(input)}` : base;
+    const response = await fetch(url, {
+        method: method.toUpperCase(),
+        headers: {
+            Authorization: `Bearer ${profile.key}`,
+            ...(method === "post" ? { "Content-Type": "application/json" } : {}),
+        },
+        body: method === "post" && input !== undefined ? JSON.stringify(input) : undefined,
+    });
+    const body: unknown = await response.json().catch(() => null);
+    if (!response.ok) {
+        const { code, message } = (body ?? {}) as { code?: string; message?: string };
+        throw new ManagementError(response.status, code ?? "error", message ?? response.statusText);
+    }
+    return body;
+}
+
+function isScalar(value: unknown): value is string | number | boolean | null {
+    return value === null || ["string", "number", "boolean"].includes(typeof value);
+}
+
+/** A scalar as itself, an array of scalars as a repeated parameter, anything else as JSON, matching what the document declares. */
+function queryString(input: Record<string, unknown>) {
+    const params = new URLSearchParams();
+    for (const [name, value] of Object.entries(input)) {
+        if (value === undefined) continue;
+        if (isScalar(value)) params.set(name, String(value));
+        else if (Array.isArray(value) && value.length > 0 && value.every(isScalar)) {
+            for (const item of value) params.append(name, String(item));
+        } else params.set(name, JSON.stringify(value));
+    }
+    const encoded = params.toString();
+    return encoded === "" ? "" : `?${encoded}`;
+}
+
+export class ManagementError extends Error {
+    public constructor(
+        public readonly status: number,
+        public readonly code: string,
+        message: string,
+    ) {
+        super(message);
+        this.name = "ManagementError";
+    }
+}