@m6d/cortex-cli 0.12.0 → 0.13.0

package/src/scaffold/ports.ts

@@ -1,17 +1,17 @@
 /**
- * Host ports for the services a generated project runs, chosen once at scaffold
- * time.
+ * Host ports for the Cortex stack a generated project runs, chosen once at
+ * scaffold time.
  *
- * The canonical ports — 5432, 6379, 9000/9001, 7474/7687 — are precisely the ones
- * a developer already running Postgres or Redis has bound, so a scaffold that
- * hardcoded them collides on its first `docker compose up -d`. Only the host side
- * moves: container ports stay canonical, so images, health checks and anything
- * inside the compose network are unaffected. The server's own port is not one of
- * these — it is the project's to choose, and stays the documented default.
+ * Only the app and the engine are published: the browser and this
+ * project's callers reach them, and nothing outside the stack reaches its
+ * databases. A fixed pair would collide with the next project scaffolded on
+ * the same machine, so each project draws its own. Container ports stay
+ * canonical. The backend's own port is not one of these: it is the project's
+ * to choose, and stays the documented default.
  *
  * Every generated file spells its ports `{{port.<name>}}` and gets them filled in
- * by `applyPorts`. That is the point of the token: compose and `.env` cannot
- * drift apart, because neither holds a number of its own.
+ * by `applyPorts`. That is the point of the token: compose and the README
+ * cannot drift apart, because neither holds a number of its own.
  */
 
 /** High, unprivileged, and clear of the ephemeral range macOS and Linux hand out. */
@@ -51,11 +51,7 @@ function allocate(taken: Set<number>) {
     return first ?? FIRST;
 }
 
-/**
- * Every port a generated project can need, allocated together so they are
- * distinct within the project. Features that were not selected simply never
- * mention theirs.
- */
+/** Every port a generated project publishes, allocated together so they are distinct. */
 export function allocatePorts() {
     const taken = new Set<number>();
 
@@ -65,19 +61,12 @@ export function allocatePorts() {
         return port;
     }
 
-    return {
-        postgres: next(),
-        redis: next(),
-        minio: next(),
-        minioConsole: next(),
-        neo4j: next(),
-        neo4jBolt: next(),
-    };
+    return { cortex: next(), engine: next() };
 }
 
 export type Ports = ReturnType<typeof allocatePorts>;
 
-/** Fills in `{{port.postgres}}` and friends. Applied to every file, once, at the end. */
+/** Fills in `{{port.cortex}}` and `{{port.engine}}`. Applied to every file, once, at the end. */
 export function applyPorts(contents: string, ports: Ports) {
     return Object.entries(ports).reduce(
         (text, [name, port]) => text.replaceAll(`{{port.${name}}}`, String(port)),

package/src/scaffold/templates/datasets.ts.txt

@@ -0,0 +1,52 @@
+import { Database } from "bun:sqlite";
+import { defineDatasetHost } from "@m6d/cortex";
+import { drizzleDataset } from "@m6d/cortex/drizzle";
+import { drizzle } from "drizzle-orm/bun-sqlite";
+import { integer, real, sqliteTable, text } from "drizzle-orm/sqlite-core";
+
+/*
+ * This backend as a dataset host: an `orders` table agents ask grouped
+ * questions of, such as revenue per product by month. It lives in memory and
+ * is seeded on every boot; point `db` and the table at your own database.
+ * The host answers whoever reaches its URL, so `resolveUser` is where yours
+ * verifies the token Cortex forwards, and `scoped` narrows rows to that user.
+ */
+
+const orders = sqliteTable("orders", {
+    id: integer().primaryKey(),
+    product: text().notNull(),
+    quantity: integer().notNull(),
+    total: real().notNull(),
+    /** ISO text, which the dataset reads as a date. */
+    placedAt: text().notNull(),
+});
+
+const sqlite = new Database(":memory:");
+sqlite.run(
+    "create table orders (id integer primary key, product text not null, quantity integer not null, total real not null, placed_at text not null)",
+);
+const db = drizzle({ client: sqlite, casing: "snake_case" });
+db.insert(orders)
+    .values([
+        { product: "Notebook", quantity: 3, total: 12, placedAt: "2026-01-05" },
+        { product: "Pen", quantity: 10, total: 15, placedAt: "2026-01-19" },
+        { product: "Notebook", quantity: 1, total: 4, placedAt: "2026-02-02" },
+        { product: "Backpack", quantity: 1, total: 49, placedAt: "2026-02-14" },
+        { product: "Pen", quantity: 4, total: 6, placedAt: "2026-03-08" },
+    ])
+    .run();
+
+export const datasets = defineDatasetHost({
+    expose: [
+        drizzleDataset({
+            name: "orders",
+            description: "One row per order: what was bought, how many, for how much, and when.",
+            table: orders,
+            dialect: "sqlite",
+            db,
+            types: { placedAt: "date" },
+            scoped: () => undefined,
+        }),
+    ],
+    resolveUser: () => ({}),
+});

package/src/scaffold/templates/dockerignore.txt

@@ -0,0 +1,7 @@
+# The env files never go into an image: they hold this checkout's secrets.
+# With their example copies left out too, setup.ts writes none during the
+# image's own `bun install`.
+.env*
+cortex.env*
+node_modules/
+.git/

package/src/scaffold/templates/fallowrc.jsonc.txt

@@ -1,19 +1,15 @@
 {
     "$schema": "https://raw.githubusercontent.com/fallow-rs/fallow/main/schema.json",
 
-    // The single root everything else hangs off. Left to auto-detection, framework
-    // heuristics mark far too much as reachable and unused exports stop being
-    // reportable at all.
-    "entry": ["index.ts"],
+    // The roots everything else hangs off: the backend, the manifest
+    // `cortex apply` loads, and the env setup `bun install` runs. Left to
+    // auto-detection, framework heuristics mark far too much as reachable and
+    // unused exports stop being reportable.
+    "entry": ["index.ts", "cortex.manifest.ts", "setup.ts"],
 
-    // These are @m6d/cortex-server's peer dependencies. The server needs them
-    // resolvable and it is this package.json's job to install them, but nothing
-    // here imports them until you write the code that does — a tool schema in
-    // zod, an extra route on `server.app`. A requirement that lives in another
-    // package's `peerDependencies` is not something reachability analysis can
-    // see, so it is stated here instead. Once your own code imports one, its
-    // entry is doing nothing and can go.
-    "ignoreDependencies": ["@tanstack/ai", "@tanstack/ai-openai", "hono", "jose", "openai", "zod"],
+    // The CLI is run as `cortex`, a binary nothing here imports, so
+    // reachability analysis cannot see that the project uses it.
+    "ignoreDependencies": ["@m6d/cortex-cli"],
 
     "duplicates": {
         // fallow's default is 0, which means "no limit": clone groups get printed

package/src/scaffold/templates/gitignore.txt

@@ -1,8 +1,9 @@
 # Dependencies
 node_modules/
 
-# Environment variables — .env.example is the committed one
+# Environment variables: the .example files are the committed ones
 .env
+cortex.env
 .env.local
 .env.*.local
 

package/src/scaffold/templates/server.ts.txt

@@ -0,0 +1,40 @@
+import { defineServer } from "@m6d/cortex";
+import { z } from "zod";
+
+/**
+ * This backend as a Cortex server: the variable its agents' prompts read,
+ * and the native tool it runs for them. Cortex presents CORTEX_SERVER_KEY as
+ * the bearer of every call, and nothing below runs for any other.
+ */
+export const server = defineServer({
+    key: process.env["CORTEX_SERVER_KEY"]!,
+    variables: {
+        // Resolved once per thread; prompts read it as {{userName}}.
+        userName: {
+            description: "Display name of the signed-in user",
+            example: "Sara",
+            type: "string",
+            resolve: ({ user }) => {
+                const name = user?.claims["name"];
+                return typeof name === "string" ? name : "guest";
+            },
+        },
+    },
+    tools: {
+        rollDice: {
+            description: "Roll dice and report each face and the total.",
+            input: z.object({
+                count: z.number().int().min(1).max(10).describe("How many dice to roll"),
+                sides: z.number().int().min(2).max(100).default(6).describe("Faces per die"),
+            }),
+            readOnly: true,
+            run: ({ count, sides }) => {
+                const faces = Array.from(
+                    { length: count },
+                    () => 1 + Math.floor(Math.random() * sides),
+                );
+                return { faces, total: faces.reduce((sum, face) => sum + face, 0) };
+            },
+        },
+    },
+});

package/src/scaffold/templates/setup.ts.txt

@@ -0,0 +1,52 @@
+import { randomBytes } from "node:crypto";
+import { chmodSync, existsSync, readFileSync, writeFileSync } from "node:fs";
+
+/*
+ * Writes .env and cortex.env on every `bun install`: each starts from its
+ * committed .example copy, and each value the copy leaves blank is
+ * generated here, the Compose project this checkout's stack runs as among
+ * them. A value already set is never changed, so a fresh clone gets a stack
+ * and secrets of its own, and a rerun changes nothing. The one exception: a
+ * cortex.env written now holds new keys, which cannot read the volumes of the
+ * stack .env names, so the stack gets a new name too. Without the example
+ * copies, as in an image build, it writes nothing.
+ */
+
+const token = () => randomBytes(32).toString("base64url");
+const key = () => randomBytes(32).toString("base64");
+
+/** The package name as Compose takes a project name: lowercase words and hyphens. */
+const { name } = JSON.parse(readFileSync("package.json", "utf8")) as { name: string };
+const project =
+    name
+        .replace(/[^a-z0-9]+/g, "-")
+        .slice(0, 40)
+        .replace(/^-+|-+$/g, "") || "cortex";
+
+const GENERATED = [
+    [".env", "COMPOSE_PROJECT_NAME", () => `${project}-${randomBytes(4).toString("hex")}`],
+    [".env", "CORTEX_SERVER_KEY", token],
+    ["cortex.env", "DEFAULT_ADMIN_PASSWORD", token],
+    // Cortex takes management keys only under this prefix. cspell:ignore mgmt
+    ["cortex.env", "BOOTSTRAP_MANAGEMENT_KEY", () => `cortex_mgmt_${token()}`],
+    ["cortex.env", "BETTER_AUTH_SECRET", key],
+    ["cortex.env", "SECRETS_MASTER_KEY", key],
+] as const;
+
+const freshKeys = !existsSync("cortex.env") && existsSync("cortex.env.example");
+
+for (const file of [".env", "cortex.env"]) {
+    const source = existsSync(file) ? file : `${file}.example`;
+    if (!existsSync(source)) continue;
+    // Only its owner reads a file of secrets, however it was first created.
+    if (source === file) chmodSync(file, 0o600);
+    let text = readFileSync(source, "utf8");
+    if (file === ".env" && freshKeys) {
+        text = text.replace(/^COMPOSE_PROJECT_NAME=.*$/m, "COMPOSE_PROJECT_NAME=");
+    }
+    for (const [target, variable, generate] of GENERATED) {
+        if (target !== file) continue;
+        text = text.replace(new RegExp(`^${variable}=$`, "m"), `${variable}=${generate()}`);
+    }
+    writeFileSync(file, text, { mode: 0o600 });
+}

package/src/ui/prompts.ts

@@ -8,20 +8,16 @@
 
 import {
     cancel,
+    confirm,
     intro,
     isCancel,
     log,
-    multiselect,
     outro,
     password,
-    select,
     spinner,
     text,
 } from "@clack/prompts";
 
-import { FEATURES, type Feature } from "@/scaffold/features";
-import type { Database } from "@/scaffold/files";
-
 export { intro, log, outro };
 
 async function orExit<T>(answer: Promise<T | symbol>) {
@@ -54,32 +50,9 @@ export function askName(check: (name: string) => string | undefined) {
     );
 }
 
-/**
- * The one structural pick: it changes a `cortex.config.ts` line and decides
- * whether the generated compose file has a database service at all.
- */
-export function askDatabase() {
-    return orExit(
-        select<Database>({
-            message: "Database",
-            initialValue: "postgres",
-            options: [
-                { value: "postgres", hint: "docker-compose.yml runs one for you" },
-                { value: "mssql", hint: "normally an existing external instance" },
-            ],
-        }),
-    );
-}
-
-/** One multi-select for the whole catalogue — minus anything a flag settled. */
-export function askFeatures(undecided: Feature[]) {
-    return orExit(
-        multiselect<Feature>({
-            message: "Which optional features?",
-            required: false,
-            options: undecided.map((feature) => ({ value: feature, hint: FEATURES[feature].hint })),
-        }),
-    );
+/** A yes-or-no question a flag left open, answered no unless the user says otherwise. */
+export function askConfirm(message: string) {
+    return orExit(confirm({ message, initialValue: false }));
 }
 
 /** A required value a command was not given: asked by name, re-asked while empty. */

package/src/ui/report.ts

@@ -1,5 +1,5 @@
 /**
- * The output grammar, shared by every command that runs against a project.
+ * The output grammar, shared by every command.
  * The report layout is deliberately frozen; this file is the only
  * place that knows the box characters.
  */
@@ -31,12 +31,7 @@ function describe(error: unknown) {
 // anything opened the box above it.
 let open = false;
 
-/** `1 node` / `3 nodes` — every count the box prints goes through this. */
-export function plural(count: number, noun: string) {
-    return `${count} ${noun}${count === 1 ? "" : "s"}`;
-}
-
-/** `┌  cortex graph seed` — opens a run. */
+/** `┌  cortex login` — opens a run. */
 export function header(title: string) {
     open = true;
     write(process.stdout, ["", `${pc.gray("┌")}  ${title}`, BAR]);
@@ -50,20 +45,15 @@ export function input(label: string, value: string) {
     write(process.stdout, [`${pc.green("◇")}  ${label.padEnd(9)}  ${value}`]);
 }
 
-export function blank() {
-    write(process.stdout, [BAR]);
-}
-
 /**
- * `│  updated   leaves/listLeaves.endpoint.ts` — a row in the body. An empty
- * label indents to the same gutter, for the second line a finding gets. `width`
- * is the label column: findings fit in 10, domain names need 14.
+ * `│  name      orders` — a row in the body. An empty label indents to the same
+ * gutter, for a continuation line. `width` is the label column.
  */
 export function row(label: string, text: string, width = 10) {
     write(process.stdout, [`${BAR}  ${label.padEnd(width - 2)}  ${text}`]);
 }
 
-/** `└  87 nodes · 124 edges  (6.2s)` — closes a run. */
+/** `└  authenticated with ada@example.com` — closes a run. */
 export function footer(text: string) {
     write(process.stdout, [`${pc.gray("└")}  ${text}`, ""]);
 }

package/tsconfig.json

@@ -5,8 +5,7 @@
         // Environment setup & latest features
         "lib": ["ESNext"],
         // Named explicitly: auto-inclusion of @types/* is an editor-dependent
-        // heuristic, and `Bun`/`Response` come from here. See @cortex/contracts'
-        // tsconfig for the same fix.
+        // heuristic, and `Bun`/`Response` come from here.
         "types": ["bun"],
         "target": "ESNext",
         "module": "Preserve",
@@ -18,7 +17,7 @@
         "resolveJsonModule": true,
         "noEmit": true,
         "paths": {
-            // The graph contract is @cortex/contracts, a private workspace package
+            // @cortex/contracts is a private workspace package
             // that never publishes, so the CLI carries its own copy: `prepack`
             // vendors it into src/contracts, where the first candidate finds it in
             // the published tarball. Inside the repo that copy doesn't exist and

package/src/commands/graph.ts

@@ -1,228 +0,0 @@
-import type { Command } from "@commander-js/extra-typings";
-import {
-    GRAPH_SCHEMA,
-    GRAPH_SCHEMA_VERSION,
-    createEmbedder,
-    createNeo4jClient,
-    type DomainDef,
-    type EmbeddingProviderConfig,
-    type Neo4jClient,
-    type Neo4jConfig,
-} from "@cortex/contracts/graph";
-import pc from "picocolors";
-
-import { configLabel, configOption, openProject } from "@/config/load";
-import { seedGraph } from "@/graph/seed";
-import * as report from "@/ui/report";
-
-const TITLE = "cortex graph seed";
-
-/** Domain names are longer than swagger's finding labels, so the body is wider. */
-const DOMAIN_COLUMN = 14;
-
-/** A failing statement is worth one line: enough to identify, not enough to drown. */
-const DETAIL_WIDTH = 60;
-
-/** Only the parts of a loaded config `graph seed` reads. */
-type ProjectConfig = {
-    neo4j?: Neo4jConfig;
-    embedding?: EmbeddingProviderConfig & { dimension: number };
-    knowledge?: { domains?: Record<string, DomainDef> };
-    agents?: Record<string, { knowledge?: { domains?: Record<string, DomainDef> } | null }>;
-};
-
-// Connection failures reach us as whatever `fetch` threw, so match on shape
-// rather than on a driver's error class.
-const UNREACHABLE =
-    /unable to connect|connection refused|econnrefused|failed to fetch|fetch failed|enotfound|getaddrinfo|timed out/i;
-
-export function registerGraph(program: Command) {
-    const graph = program
-        .command("graph")
-        .helpGroup("Resources:")
-        .summary("The Neo4j knowledge graph")
-        .description(
-            "The Neo4j knowledge graph.\n\nReads `knowledge.domains` and `neo4j` from your cortex.config.ts.",
-        )
-        .addOption(configOption())
-        .helpCommand(false);
-
-    // No flags. `--domain <name>` is flag-shaped design work, not a flag:
-    // `expandDomains` resolves cross-domain references and the node pass creates every
-    // node before any edge, so a subset seed risks dangling edges.
-    graph
-        .command("seed")
-        .description("Load concepts, endpoints, services, and rules into Neo4j")
-        .action(async function () {
-            await seed(graph);
-        });
-}
-
-async function seed(group: Command) {
-    const { config: loaded, configPath, verbose } = await openProject(group, TITLE);
-    const config = loaded as ProjectConfig;
-
-    // Inputs are reported as they resolve. With no domains there is nothing to
-    // seed; an absent neo4j or embedding section is `runSeed`'s error to throw.
-    if (config.neo4j?.url) report.input("Neo4j", config.neo4j.url);
-    const domains = collectDomains(config);
-    const names = Object.keys(domains);
-    if (!names.length) failMissingDomains(configPath);
-    report.input("Domains", `${names.length} — ${names.join(", ")}`);
-
-    const startedAt = Date.now();
-    const result = await runSeed(config, domains).catch(function (error: unknown): never {
-        return failSeed({ error, config, configPath, verbose });
-    });
-
-    // A domain is the unit the user edits, so it is the unit the report counts
-    // against: a wrong number next to `attendance` points at src/domains/attendance/.
-    report.blank();
-    for (const [name, domain] of Object.entries(result.domains)) {
-        const counts = [report.plural(domain.nodes, "node"), report.plural(domain.edges, "edge")];
-        if (domain.failed) counts.push(`${domain.failed} failed`);
-        report.row(name, counts.join(" · "), DOMAIN_COLUMN);
-
-        // The first failure only: enough to identify what broke, not enough to
-        // drown the run — the count above says how many followed it.
-        const failure = domain.failures[0];
-        if (failure) {
-            report.row("", `${pc.red("✗")} ${truncate(failure.error)}`, DOMAIN_COLUMN);
-            report.row("", `  ${truncate(oneLine(failure.statement))}`, DOMAIN_COLUMN);
-        }
-    }
-
-    // Embeddings are a second pass over the whole graph, so they get their own
-    // step rather than a row among the counts.
-    report.blank();
-    report.input(
-        "Embeddings",
-        `${report.plural(result.embeddings.concepts, "concept")}, dimension ${result.embeddings.dimension}`,
-    );
-    report.blank();
-
-    const counts = [report.plural(result.nodes, "node"), report.plural(result.edges, "edge")];
-    if (result.failed) counts.push(`${result.failed} failed`);
-    report.footer(`${counts.join(" · ")}  (${((Date.now() - startedAt) / 1000).toFixed(1)}s)`);
-
-    if (result.failed) {
-        report.note("The graph is partially seeded. Re-running is safe — seeding is MERGE-based.");
-        process.exit(1);
-    }
-}
-
-/** Cypher is generated multi-line and indented; a report row is neither. */
-function oneLine(statement: string) {
-    return statement.replace(/\s+/g, " ").trim();
-}
-
-function truncate(text: string) {
-    return text.length > DETAIL_WIDTH ? `${text.slice(0, DETAIL_WIDTH - 2)} …` : text;
-}
-
-/** Server level first, then per agent — an agent's domain of the same name wins. */
-function collectDomains(config: ProjectConfig) {
-    const all = { ...config.knowledge?.domains };
-
-    for (const agent of Object.values(config.agents ?? {})) {
-        Object.assign(all, agent.knowledge?.domains);
-    }
-
-    return all;
-}
-
-/**
- * The whole pipeline is the CLI's, built on the graph contract it depends on:
- * `@cortex/contracts/graph` is where the vocabulary, the Neo4j client and the embedder
- * come from, and the version it seeds at is the version of that dependency.
- */
-async function runSeed(config: ProjectConfig, domains: Record<string, DomainDef>) {
-    if (!config.neo4j) throw new Error("neo4j config is required for graph seed");
-    if (!config.embedding) throw new Error("embedding config is required for graph seed");
-
-    const embed = createEmbedder(config.embedding);
-    const neo4j = createNeo4jClient(config.neo4j, embed);
-
-    await warnOnRestamp(neo4j);
-
-    return await seedGraph(
-        {
-            neo4j,
-            embedding: { embed, dimension: config.embedding.dimension },
-            schema: GRAPH_SCHEMA,
-            schemaVersion: GRAPH_SCHEMA_VERSION,
-        },
-        domains,
-    );
-}
-
-/**
- * Seeding is MERGE-based, so a graph written under an older schema is not cleaned
- * up — its nodes stay, under labels nothing reads. Worth saying out loud; not
- * worth blocking on, since re-seeding is exactly how that graph gets fixed.
- */
-async function warnOnRestamp(neo4j: Neo4jClient) {
-    // An unreachable graph is the seed's to report, far better than a warning could.
-    const rows = await neo4j
-        .query(
-            `MATCH (g:${GRAPH_SCHEMA.label.marker}) RETURN g.${GRAPH_SCHEMA.prop.version} AS version`,
-        )
-        .catch(() => undefined);
-    if (!rows) return;
-
-    const stamped = (rows as { version?: number }[])[0]?.version;
-    if (stamped === undefined || stamped === GRAPH_SCHEMA_VERSION) return;
-
-    report.blank();
-    report.row(
-        "",
-        `${pc.yellow("!")} Graph was written with schema v${stamped}; restamping as v${GRAPH_SCHEMA_VERSION}.`,
-        DOMAIN_COLUMN,
-    );
-    report.row("", "  Nodes from the old schema are not removed.", DOMAIN_COLUMN);
-}
-
-function failMissingDomains(configPath: string): never {
-    report.fail({
-        what: `${configLabel(configPath)} has no knowledge.domains`,
-        blocks: [
-            "`graph seed` loads domain definitions into Neo4j. Add them:",
-            "  knowledge: { domains: { leaves: leavesDomain } }",
-            "See https://github.com/boring91/cortex/blob/main/packages/cortex-server/README.md#file-structure-convention",
-        ],
-    });
-}
-
-/**
- * The neo4j and embedding sections are `runSeed`'s to require — it throws
- * `"neo4j config is required for graph seed"`. This renders what it threw.
- */
-function failSeed(options: {
-    error: unknown;
-    config: ProjectConfig;
-    configPath: string;
-    verbose: boolean;
-}): never {
-    const { error, config, configPath, verbose } = options;
-    const label = configLabel(configPath);
-    const message = error instanceof Error ? error.message : String(error);
-    const url = config.neo4j?.url;
-    if (url !== undefined && UNREACHABLE.test(message)) {
-        report.fail({
-            what: `Cannot reach Neo4j at ${url}`,
-            error,
-            blocks: [
-                "Is it running?  docker compose up -d neo4j",
-                `Otherwise check neo4j.url / neo4j.user / neo4j.password in\n${label}.`,
-            ],
-            verbose,
-        });
-    }
-
-    report.fail({
-        what: "Could not seed the graph",
-        error,
-        blocks: [`Check neo4j, embedding, and knowledge.domains in ${label}.`],
-        verbose,
-    });
-}