@m6d/cortex-cli 0.12.1 → 0.14.0

package/src/scaffold/ports.ts

@@ -1,17 +1,16 @@
 /**
- * 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. The backend listens on the third. Fixed ports would collide with
+ * the next project scaffolded on the same machine, so each project draws its
+ * own. Container ports stay canonical.
  *
  * 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 +50,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 +60,12 @@ export function allocatePorts() {
         return port;
     }
 
-    return {
-        postgres: next(),
-        redis: next(),
-        minio: next(),
-        minioConsole: next(),
-        neo4j: next(),
-        neo4jBolt: next(),
-    };
+    return { cortex: next(), engine: next(), server: next() };
 }
 
 export type Ports = ReturnType<typeof allocatePorts>;
 
-/** Fills in `{{port.postgres}}` and friends. Applied to every file, once, at the end. */
+/** Fills in every `{{port.<name>}}`. 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/cspell.json.txt

@@ -0,0 +1,41 @@
+{
+    "version": "0.2",
+    "language": "en",
+    "words": ["mprocs"],
+    "ignorePaths": [
+        "node_modules/**",
+        "out/**",
+        "build/**",
+        "**/dist/**",
+        "coverage/**",
+        "*.tsbuildinfo",
+        "bun.lock",
+        "package-lock.json",
+        "pnpm-lock.yaml",
+        "yarn.lock",
+        "*.db",
+        "*.sqlite",
+        "scratch.*",
+        ".env*",
+        "**/*.min.js",
+        "**/*.min.css",
+        "**/db/migrations/**",
+        "**/i18n/**",
+        "docs",
+        ".claude",
+        ".angular",
+        ".vercel/**",
+        "vendor/**",
+        ".gitignore"
+    ],
+    "dictionaries": [
+        "typescript",
+        "node",
+        "npm",
+        "html",
+        "css",
+        "bash",
+        "companies",
+        "softwareTerms"
+    ]
+}

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,6 @@
+# .env never goes into an image: it holds this checkout's secrets. With
+# .env.example left out too, setup.ts writes none during the image's own
+# `bun install`.
+.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,7 +1,7 @@
 # Dependencies
 node_modules/
 
-# Environment variables — .env.example is the committed one
+# Environment variables: .env.example is the committed one
 .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,44 @@
+import { randomBytes } from "node:crypto";
+import { chmodSync, existsSync, readFileSync, writeFileSync } from "node:fs";
+
+/*
+ * Writes .env on every `bun install`: it starts from the committed
+ * .env.example, or from .env when there is one, and each value left blank
+ * that is listed below 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. Without either file, 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 = [
+    ["COMPOSE_PROJECT_NAME", () => `${project}-${randomBytes(4).toString("hex")}`],
+    ["CORTEX_SERVER_KEY", token],
+    ["DEFAULT_ADMIN_PASSWORD", token],
+    // Cortex takes management keys only under this prefix. cspell:ignore mgmt
+    ["BOOTSTRAP_MANAGEMENT_KEY", () => `cortex_mgmt_${token()}`],
+    ["BETTER_AUTH_SECRET", key],
+    ["SECRETS_MASTER_KEY", key],
+] as const;
+
+const source = existsSync(".env") ? ".env" : ".env.example";
+if (existsSync(source)) {
+    // Only its owner reads a file of secrets, however it was first created.
+    if (source === ".env") chmodSync(".env", 0o600);
+    let text = readFileSync(source, "utf8");
+    for (const [variable, generate] of GENERATED) {
+        text = text.replace(new RegExp(`^${variable}=$`, "m"), `${variable}=${generate()}`);
+    }
+    writeFileSync(".env", 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,52 +50,42 @@ 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 caller says otherwise. */
+export function askConfirm(message: string, initialValue = false) {
+    return orExit(confirm({ message, initialValue }));
 }
 
-/** A required value a command was not given: asked by name, re-asked while empty. */
-export function askValue(name: string, hint?: string) {
+/**
+ * A required value a command was not given: asked by name, re-asked while
+ * empty or while `check` returns a complaint about the trimmed value.
+ */
+export function askValue(
+    name: string,
+    hint?: string,
+    check: (value: string) => string | undefined = () => undefined,
+) {
     return orExit(
         text({
             message: name,
             placeholder: hint,
-            validate: (value) =>
-                (value ?? "").trim().length === 0 ? `${name} is required.` : undefined,
+            validate: function (value) {
+                const candidate = (value ?? "").trim();
+                return candidate.length === 0 ? `${name} is required.` : check(candidate);
+            },
         }),
     );
 }
 
-/** A credential: typed masked, never echoed. */
-export function askSecret(name: string) {
+/** A credential: typed masked, never echoed, and re-asked while `check` complains. */
+export function askSecret(
+    name: string,
+    check: (value: string) => string | undefined = () => undefined,
+) {
     return orExit(
         password({
             message: name,
-            validate: (value) => ((value ?? "").length === 0 ? `${name} is required.` : undefined),
+            validate: (value) =>
+                (value ?? "").length === 0 ? `${name} is required.` : check(value ?? ""),
         }),
     );
 }

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