@m6d/cortex-cli 1.0.0

package/src/scaffold/files.ts

@@ -0,0 +1,568 @@
+/**
+ * Every file `cortex new` writes, as one pure function. The tooling configs are
+ * inlined rather than pulled from `@m6d/eslint-config`, `@m6d/prettier-config`
+ * and `@m6d/tsconfig`: those are `private: true` at `0.0.0` and resolvable only
+ * through this workspace, and a standalone scaffold has no workspace. See
+ * docs/design/cortex-cli.md §7.5-§7.6.
+ */
+
+import { FEATURE_NAMES, FEATURES, type Feature } from "@/scaffold/features";
+import { applyPorts, type Ports } from "@/scaffold/ports";
+
+export type Database = "postgres" | "mssql";
+
+// The generated project depends on these directly, not transitively: its own code
+// imports `zod` for tool schemas and `hono` for extra routes on `server.app`.
+// Ranges come from packages/cortex-server's peers, which is the compatibility
+// statement the server itself publishes.
+const DEPENDENCIES = {
+    "@m6d/cortex-server": ">=0.1.0",
+    "@tanstack/ai": "^0.43.1",
+    "@tanstack/ai-openai": "^0.18.0",
+    hono: "^4.12.3",
+    jose: "^6.1.3",
+    openai: "^6",
+    zod: "^4.3.6",
+};
+
+const DEV_DEPENDENCIES = {
+    "@types/bun": "latest",
+    cspell: "^9.6.4",
+    eslint: "^9",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-prettier": "^5.5.5",
+    fallow: "^3.9.1",
+    prettier: "^3.6.2",
+    typescript: "^5",
+    "typescript-eslint": "^8.65.0",
+};
+
+// Postgres is the one we run, so it gets a scaffolded port. MSSQL is normally an
+// existing instance nobody moved, which is why it keeps 1433 and has no service.
+const CONNECTION_STRING: Record<Database, string> = {
+    postgres: "postgres://postgres:postgres@localhost:{{port.postgres}}/cortex",
+    mssql: "Server=localhost,1433;Database=cortex;User Id=sa;Password=your-password;Encrypt=false",
+};
+
+function packageJson(name: string) {
+    return `${JSON.stringify(
+        {
+            name,
+            version: "0.1.0",
+            private: true,
+            type: "module",
+            scripts: {
+                // Not `fallow audit`: it scopes itself to files changed against a
+                // base branch, and a project on line one has no commits and no
+                // remote to derive one from. Bare `fallow` runs the same three
+                // analyses — dead code, duplication, complexity — over everything.
+                audit: "fallow",
+                check: "tsc --noEmit",
+                dev: "bun run --hot index.ts",
+                format: "prettier --write .",
+                "format:check": "prettier --check .",
+                lint: "eslint",
+                spellcheck: 'cspell "**/*.{ts,mjs,json,md}"',
+                verify: "bun run format:check && bun run lint && bun run spellcheck && bun run check && bun run audit",
+            },
+            dependencies: DEPENDENCIES,
+            devDependencies: DEV_DEPENDENCIES,
+        },
+        null,
+        4,
+    )}\n`;
+}
+
+/**
+ * Never toggled, so they only ever appear commented out: `context` is fully
+ * defaulted, and the other two are what you reach for once a real problem shows
+ * up — noisy graph retrieval, a cheap-model path — not on day one.
+ */
+const NEVER_SCAFFOLDED: [note: string, config: string][] = [
+    [
+        "A cheaper, faster model for auxiliary passes. Same shape as `model`.",
+        `fastModel: {
+    baseURL: process.env["CORTEX_FAST_MODEL_URL"]!,
+    apiKey: process.env["CORTEX_FAST_MODEL_KEY"]!,
+    modelName: process.env["CORTEX_FAST_MODEL_NAME"]!,
+},`,
+    ],
+    [
+        "Re-ranks knowledge-graph retrieval when it comes back noisy.",
+        `reranker: {
+    url: process.env["CORTEX_RERANKER_URL"]!,
+    apiKey: process.env["CORTEX_RERANKER_KEY"]!,
+},`,
+    ],
+    [
+        "Context-window tuning. Every field is defaulted, so override only what you\nhave measured a reason to change.",
+        `context: {
+    maxContextTokens: 120_000,
+    recentMessagesToKeep: 6,
+},`,
+    ],
+];
+
+/** Fragments are authored at zero indentation and placed by these two. */
+function indented(block: string) {
+    return block.replace(/^(?!$)/gm, "    ");
+}
+
+function commented(block: string) {
+    return block.replace(/^(?!$)/gm, "    // ");
+}
+
+/** A note, then its fragment — written live, or written disabled. */
+function block(note: string, config: string, enabled: boolean) {
+    return `\n${commented(note)}\n${enabled ? indented(config) : commented(config)}\n`;
+}
+
+function cortexConfig(database: Database, features: Feature[]) {
+    const fragment = (feature: Feature) =>
+        block(FEATURES[feature].note, FEATURES[feature].config, features.includes(feature));
+
+    const on = FEATURE_NAMES.filter((feature) => features.includes(feature))
+        .map(fragment)
+        .join("");
+    const off = FEATURE_NAMES.filter((feature) => !features.includes(feature))
+        .map(fragment)
+        .join("");
+    const never = NEVER_SCAFFOLDED.map(([note, config]) => block(note, config, false)).join("");
+
+    // cspell.json ships an empty word list on purpose, so the Cortex jargon the
+    // config names teaches the checker from the file that uses it.
+    return `import { defineAgent } from "@m6d/cortex-server";
+import type { CortexConfig } from "@m6d/cortex-server";
+
+// cspell:words reranker
+
+/**
+ * Inert on purpose: this file default-exports data and nothing else, so importing
+ * it never opens a connection or binds a port. Construction lives in index.ts,
+ * which is what lets tooling read this config without booting the server.
+ */
+export default {
+    port: 3331,
+    database: {
+        type: "${database}",
+        connectionString: process.env["CORTEX_DATABASE_URL"]!,
+    },
+    model: {
+        baseURL: process.env["CORTEX_MODEL_URL"]!,
+        apiKey: process.env["CORTEX_MODEL_KEY"]!,
+        modelName: process.env["CORTEX_MODEL_NAME"]!,
+    },
+${on === "" ? "" : `${on}\n`}    agents: {
+        assistant: defineAgent({
+            systemPrompt: "You are a helpful assistant.",
+        }),
+    },
+
+    // Everything below is off, written out so the file documents what else the
+    // server does. Uncomment a block and fill in its keys in .env to enable it.
+${off}${never}} satisfies CortexConfig;
+`;
+}
+
+function indexTs() {
+    return `import { createCortex } from "@m6d/cortex-server";
+import config from "./cortex.config";
+
+const cortex = createCortex(config);
+
+const server = await cortex.serve();
+
+// Your own routes hang off the same Hono app the agent runtime serves from:
+// server.app.get("/hello", function (c) {
+//     return c.text("hello");
+// });
+
+export default {
+    port: server.port,
+    fetch: server.fetch,
+    websocket: server.websocket,
+    idleTimeout: 0,
+};
+`;
+}
+
+/**
+ * Whether this selection runs anything of its own — which is the same question as
+ * "did any port get chosen", since a chosen port is always some service's.
+ */
+function hasServices(database: Database, features: Feature[]) {
+    return (
+        database === "postgres" ||
+        features.some((feature) => FEATURES[feature].compose !== undefined)
+    );
+}
+
+function env(database: Database, features: Feature[]) {
+    const blocks = FEATURE_NAMES.filter((feature) => features.includes(feature)).map(
+        (feature) => `\n${FEATURES[feature].env}\n`,
+    );
+
+    // Only the URLs pointing at scaffolded services carry a chosen port, and those
+    // are exactly the ones docker-compose.yml publishes.
+    const note = hasServices(database, features)
+        ? `#
+# The service ports below are not the canonical ones. They were picked when this
+# project was scaffolded, from what was free on the machine, so it does not
+# collide with anything else you run. Change them freely — in step with
+# docker-compose.yml.
+`
+        : "";
+
+    return `# Environment for this Cortex server. Bun loads this file from the directory you
+# run in, so it has to sit next to cortex.config.ts.
+#
+# .env.example is the committed copy. Keep the two in step; keep secrets in .env.
+${note}
+# --- Model -------------------------------------------------------------------
+# Any OpenAI-compatible endpoint: base URL, key, and model name.
+CORTEX_MODEL_URL=https://api.openai.com/v1
+CORTEX_MODEL_KEY=your-model-api-key
+CORTEX_MODEL_NAME=your-model-name
+
+# --- Database ----------------------------------------------------------------
+# The dialect is ${database}, set in cortex.config.ts. Change it there, not here.
+CORTEX_DATABASE_URL=${CONNECTION_STRING[database]}
+${blocks.join("")}`;
+}
+
+/**
+ * Services the selections actually need, and nothing else. `auth` and the
+ * Control Center are external, the embedding endpoint is a URL like the main
+ * model, and MSSQL is normally an existing instance — so with `--yes --database
+ * mssql` there is no service at all, and no file is written.
+ */
+function dockerCompose(name: string, database: Database, features: Feature[]) {
+    const services: string[] = [];
+    const volumes: string[] = [];
+
+    if (database === "postgres") {
+        services.push(`    postgres:
+        image: postgres:17-alpine
+        environment:
+            POSTGRES_USER: postgres
+            POSTGRES_PASSWORD: postgres
+            POSTGRES_DB: cortex
+        ports:
+            - "{{port.postgres}}:5432"
+        volumes:
+            - postgres-data:/var/lib/postgresql/data`);
+        volumes.push("postgres-data");
+    }
+
+    for (const feature of FEATURE_NAMES.filter((feature) => features.includes(feature))) {
+        const { compose, volume } = FEATURES[feature];
+        if (compose === undefined) continue;
+        services.push(compose);
+        if (volume !== undefined) volumes.push(volume);
+    }
+
+    if (services.length === 0) return undefined;
+
+    const volumeBlock =
+        volumes.length === 0
+            ? ""
+            : `\nvolumes:\n${volumes.map((name) => `    ${name}:\n`).join("")}`;
+
+    return `# Local infrastructure for this project. The .env this was scaffolded with
+# already points at these, so \`docker compose up -d\` is enough.
+#
+# The host ports were picked at scaffold time from what was free on the machine —
+# the container ports next to them are the canonical ones and should stay put.
+# Move a host port and .env has to follow.
+
+# Explicit so the project never collides with another checkout whose directory
+# happens to share this one's name (Compose defaults to the directory name, and
+# a name clash silently replaces the other project's containers and volumes).
+name: ${name}-cortex-server
+
+services:
+${services.join("\n\n")}
+${volumeBlock}`;
+}
+
+/**
+ * `--knowledge` scaffolds the directory `domainsDir` defaults to, which is what
+ * makes the convention true by construction: `cortex swagger sync` finds it with
+ * no config key.
+ */
+function domainsReadme() {
+    return `# Domains
+
+Domain definitions live here, one directory each, and are what \`cortex graph seed\` loads into Neo4j.
+
+\`\`\`
+src/domains/
+  leaves/
+    index.ts                            defineDomain({ concepts, endpoints, rules, services })
+    concepts/leave.concept.ts
+    endpoints/listLeaves.endpoint.ts
+    services/leaveRequests.service.ts
+\`\`\`
+
+Export each domain from its \`index.ts\`, then list it under \`knowledge.domains\` in
+\`cortex.config.ts\`. \`cortex swagger sync\` fills in the params, body, and response of every
+\`.endpoint.ts\` from your Swagger spec.
+`;
+}
+
+function tsconfig() {
+    return `{
+    "compilerOptions": {
+        // Environment setup & latest features
+        "lib": ["ESNext"],
+        // Named explicitly rather than left to @types auto-inclusion, which is an
+        // editor-dependent heuristic. The \`Bun\` global comes from here.
+        "types": ["bun"],
+        "target": "ESNext",
+        "module": "Preserve",
+        "moduleDetection": "force",
+
+        // Bundler mode
+        "moduleResolution": "bundler",
+        "verbatimModuleSyntax": true,
+        "noEmit": true,
+
+        // Best practices
+        "strict": true,
+        "skipLibCheck": true,
+        "noFallthroughCasesInSwitch": true,
+        "noImplicitOverride": true,
+        "noUncheckedIndexedAccess": true
+    },
+    "include": ["**/*.ts"]
+}
+`;
+}
+
+function gitignore() {
+    return `# Dependencies
+node_modules/
+
+# Environment variables — .env.example is the committed one
+.env
+.env.local
+.env.*.local
+
+# TypeScript
+*.tsbuildinfo
+
+# Tooling caches
+.fallow/
+
+# Logs
+*.log
+
+# OS files
+.DS_Store
+`;
+}
+
+function eslintConfig() {
+    return `import { defineConfig, globalIgnores } from "eslint/config";
+import prettierConfig from "eslint-config-prettier";
+import prettierPlugin from "eslint-plugin-prettier";
+import tseslint from "typescript-eslint";
+
+export default defineConfig([
+    globalIgnores(["**/node_modules/**", "**/dist/**", "**/.fallow/**"]),
+    prettierConfig,
+    {
+        plugins: { prettier: prettierPlugin },
+        rules: { "prettier/prettier": "error" },
+    },
+    {
+        files: ["**/*.ts"],
+        extends: [tseslint.configs.recommendedTypeChecked],
+        languageOptions: {
+            parserOptions: { projectService: true, tsconfigRootDir: import.meta.dirname },
+        },
+    },
+]);
+`;
+}
+
+function prettierConfig() {
+    return `export default {
+    printWidth: 100,
+    singleQuote: false,
+    tabWidth: 4,
+};
+`;
+}
+
+function cspellConfig() {
+    return `${JSON.stringify(
+        {
+            version: "0.2",
+            language: "en",
+            // Yours to fill in. Project jargon belongs here; nothing is seeded,
+            // because a stranger's vocabulary is noise in your repo.
+            words: [],
+            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",
+                "**/domains/**/*.concept.ts",
+            ],
+            dictionaries: [
+                "typescript",
+                "node",
+                "npm",
+                "html",
+                "css",
+                "bash",
+                "companies",
+                "softwareTerms",
+            ],
+        },
+        null,
+        4,
+    )}\n`;
+}
+
+function fallowrc() {
+    return `{
+    "$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"],
+
+    // 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"],
+
+    "duplicates": {
+        // fallow's default is 0, which means "no limit": clone groups get printed
+        // and the run still exits 0, so duplication would be reported and never
+        // blocked. A percentage is the only gate duplication has.
+        //
+        // Read it knowing the denominator is your whole project: 10% of a young
+        // one is a handful of lines, so early on this is close to "no copy-paste
+        // at all", which is the right setting for code nobody has had time to
+        // duplicate yet. Raise it once the number stops meaning anything.
+        "threshold": 10,
+    },
+
+    "health": {
+        // fallow's defaults, kept as-is: they are the standard we want to hold.
+        "maxCyclomatic": 20,
+        "maxCognitive": 15,
+
+        // CRAP is complexity weighted by test coverage, and a project with no
+        // coverage scores 0% everywhere, which collapses it to
+        // \`cyclomatic² + cyclomatic\`. 420 is what cyclomatic 20 scores at zero
+        // coverage, so this ceiling sits exactly on maxCyclomatic and adds nothing
+        // of its own. Give it coverage and lower it.
+        "maxCrap": 420,
+    },
+}
+`;
+}
+
+function readme(name: string, database: Database, features: Feature[], compose: boolean) {
+    const enabled = FEATURE_NAMES.filter((feature) => features.includes(feature));
+
+    return `# ${name}
+
+A Cortex server: one agent, a ${database} database, and an OpenAI-compatible model.${
+        enabled.length === 0 ? "" : ` Also on: ${enabled.join(", ")}.`
+    }
+
+## Getting started
+
+\`\`\`sh
+bun install
+${compose ? "docker compose up -d\n" : ""}# fill in CORTEX_MODEL_* in .env
+bun run dev
+\`\`\`
+
+The server listens on http://localhost:3331. Change \`port\` in \`cortex.config.ts\` to move it.${
+        compose
+            ? `
+
+The service ports in \`docker-compose.yml\` are not the canonical ones: they were picked at scaffold
+time from what was free on this machine, so this project does not fight whatever else you run.
+\`.env\` already points at them.`
+            : ""
+    }
+
+## Layout
+
+- \`cortex.config.ts\` — inert data. It default-exports a \`CortexConfig\` and never constructs
+  anything, so tooling can import it without booting a server.
+- \`index.ts\` — construction. It reads the config, calls \`createCortex\`, serves, and is where your
+  own routes go.
+- \`.env\` — local secrets, loaded by Bun from the directory you run in. \`.env.example\` is the
+  committed copy.
+
+Commented-out sections in \`cortex.config.ts\` document what else the server can do.
+
+## Checks
+
+\`bun run verify\` runs formatting, lint, spelling, types, and the fallow audit — the same set a
+pre-commit hook or CI job should run. Each is also available on its own: \`format:check\`, \`lint\`,
+\`spellcheck\`, \`check\`, \`audit\`.
+`;
+}
+
+/** Relative path → contents. Nothing here touches the filesystem. */
+export function scaffoldFiles(name: string, database: Database, features: Feature[], ports: Ports) {
+    const envFile = env(database, features);
+    const compose = dockerCompose(name, database, features);
+
+    const files: Record<string, string> = {
+        "cortex.config.ts": cortexConfig(database, features),
+        "index.ts": indexTs(),
+        "package.json": packageJson(name),
+        "tsconfig.json": tsconfig(),
+        ".env": envFile,
+        ".env.example": envFile,
+        ".gitignore": gitignore(),
+        "README.md": readme(name, database, features, compose !== undefined),
+        "eslint.config.mjs": eslintConfig(),
+        "prettier.config.mjs": prettierConfig(),
+        "cspell.json": cspellConfig(),
+        ".fallowrc.jsonc": fallowrc(),
+        ...(compose === undefined ? {} : { "docker-compose.yml": compose }),
+        ...(features.includes("knowledge") ? { "src/domains/README.md": domainsReadme() } : {}),
+    };
+
+    // One pass at the end, over everything: no generator holds a port number of
+    // its own, so compose, .env and the README cannot disagree about one.
+    return Object.fromEntries(
+        Object.entries(files).map(([path, contents]) => [path, applyPorts(contents, ports)]),
+    );
+}

package/src/scaffold/ports.ts

@@ -0,0 +1,86 @@
+/**
+ * Host ports for the services 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.
+ *
+ * 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.
+ */
+
+/** High, unprivileged, and clear of the ephemeral range macOS and Linux hand out. */
+const FIRST = 20_000;
+const LAST = 39_999;
+
+/** Enough tries to step over a busy port. Not a retry framework. */
+const ATTEMPTS = 20;
+
+/**
+ * A bind that succeeds is the only honest answer about a port, and it costs one
+ * syscall. Anything that stops the bind from being meaningful — no socket
+ * permission, a host that is not Bun — reads as "not free" and leaves the caller
+ * on its random pick, which is the fallback either way.
+ */
+function isFree(port: number) {
+    try {
+        Bun.listen({ hostname: "0.0.0.0", port, socket: { data() {} } }).stop(true);
+        return true;
+    } catch {
+        return false;
+    }
+}
+
+/** A random free port, or — if nothing probes free — the first one we picked. */
+function allocate(taken: Set<number>) {
+    let first: number | undefined;
+
+    for (let attempt = 0; attempt < ATTEMPTS; attempt++) {
+        const port = FIRST + Math.floor(Math.random() * (LAST - FIRST + 1));
+        if (taken.has(port)) continue;
+
+        first ??= port;
+        if (isFree(port)) return port;
+    }
+
+    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.
+ */
+export function allocatePorts() {
+    const taken = new Set<number>();
+
+    function next() {
+        const port = allocate(taken);
+        taken.add(port);
+        return port;
+    }
+
+    return {
+        postgres: next(),
+        redis: next(),
+        minio: next(),
+        minioConsole: next(),
+        neo4j: next(),
+        neo4jBolt: next(),
+    };
+}
+
+export type Ports = ReturnType<typeof allocatePorts>;
+
+/** Fills in `{{port.postgres}}` and friends. 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)),
+        contents,
+    );
+}