@m6d/cortex-cli 0.1.0

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,
+    );
+}

package/src/scaffold/templates/domains-README.md.txt

@@ -0,0 +1,16 @@
+# 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.

package/src/scaffold/templates/eslint.config.mjs.txt

@@ -0,0 +1,20 @@
+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 },
+        },
+    },
+]);

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

@@ -0,0 +1,42 @@
+{
+    "$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,
+    },
+}

package/src/scaffold/templates/gitignore.txt

@@ -0,0 +1,19 @@
+# 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

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

@@ -0,0 +1,18 @@
+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,
+};

package/src/scaffold/templates/prettier.config.mjs.txt

@@ -0,0 +1,5 @@
+export default {
+    printWidth: 100,
+    singleQuote: false,
+    tabWidth: 4,
+};

package/src/scaffold/templates/tsconfig.json.txt

@@ -0,0 +1,25 @@
+{
+    "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"]
+}

package/src/swagger/extract-endpoints.ts

@@ -0,0 +1,266 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { Endpoint, HttpMethod, Prop } from "./types";
+import {
+    dedupe,
+    deref,
+    isObj,
+    obj,
+    pickContent,
+    schemaType,
+    toProp,
+    toProps,
+} from "./openapi-schema";
+import { parseResponse } from "./parse-response";
+import { withGeneratedBlock } from "./generated-block";
+
+type ExtractEndpointsOptions = {
+    swaggerUrls: string[];
+    domainsDir: string;
+    write?: boolean;
+};
+
+const METHODS: Array<[string, HttpMethod]> = [
+    ["get", "GET"],
+    ["post", "POST"],
+    ["put", "PUT"],
+    ["delete", "DELETE"],
+];
+
+/**
+ * ASP.NET conventions the extractor normalizes away so an `.endpoint.ts` path
+ * matches the spec whichever way the API was mounted: routes are keyed without
+ * the `/api` prefix (either side may carry it), and `JsonNode`-typed query
+ * parameters, which Swagger expands into `Root.Options`, `Root.Parent` and
+ * `Root.Root` dot-paths, collapse back to one object parameter.
+ */
+const API_PREFIX = /^\/api(?=\/|$)/i;
+const JSON_NODE_MEMBER = /^(Options|Parent|Root)\b/;
+
+function toCamelCase(s: string) {
+    return s
+        .split(".")
+        .map((seg) => seg.replace(/^[A-Z]/, (c) => c.toLowerCase()))
+        .join(".");
+}
+
+function normalizePath(raw: string) {
+    let p = raw.startsWith("/") ? raw : `/${raw}`;
+    p = p.replace(/\{([^}:?]+)(?::[^}]+)?\??\}/g, "{$1}").replace(API_PREFIX, "") || "/";
+    return p.length > 1 ? p.replace(/\/+$/, "") : p;
+}
+
+function walkFiles(dir: string, accept: (filePath: string) => boolean) {
+    if (!fs.existsSync(dir)) return [];
+    const out: string[] = [];
+    function walk(d: string) {
+        for (const e of fs.readdirSync(d, { withFileTypes: true })) {
+            const p = path.join(d, e.name);
+            if (e.isDirectory()) walk(p);
+            else if (accept(p)) out.push(p);
+        }
+    }
+    walk(dir);
+    return out;
+}
+
+function endpointFiles(root: string) {
+    const out = new Map<string, string>();
+    for (const filePath of walkFiles(root, (p) => p.endsWith(".endpoint.ts"))) {
+        const c = fs.readFileSync(filePath, "utf8");
+        const method = c.match(/^\s*method:\s*(['"])([^'"]+)\1/m)?.[2];
+        const route = c.match(/^\s*path:\s*(['"])([^'"]+)\1/m)?.[2];
+        if (method && route) out.set(`${method}:${normalizePath(route)}`, filePath);
+    }
+    return out;
+}
+
+function extractEndpoint(
+    doc: unknown,
+    route: string,
+    method: HttpMethod,
+    pathItemIn: unknown,
+    operationIn: unknown,
+) {
+    const pathItem = obj(pathItemIn);
+    const operation = obj(operationIn);
+
+    const rawParams = [
+        ...(Array.isArray(pathItem.parameters) ? (pathItem.parameters as unknown[]) : []),
+        ...(Array.isArray(operation.parameters) ? (operation.parameters as unknown[]) : []),
+    ]
+        .map((x) => deref(doc, x))
+        .filter((x) => typeof x.in === "string" && ["path", "query"].includes(x.in))
+        .filter((x) => typeof x.name === "string");
+
+    const jsonNodeRoots = new Set<string>();
+    for (const x of rawParams) {
+        const name = String(x.name);
+        if (!name.includes(".")) continue;
+        const root = name.split(".")[0]!;
+        const rest = name.slice(root.length + 1);
+        if (JSON_NODE_MEMBER.test(rest)) jsonNodeRoots.add(root);
+    }
+
+    const params = dedupe(
+        rawParams
+            .filter((x) => {
+                const name = String(x.name);
+                if (!name.includes(".")) return true;
+                const root = name.split(".")[0]!;
+                return !jsonNodeRoots.has(root);
+            })
+            .map((x) =>
+                toProp(
+                    doc,
+                    toCamelCase(String(x.name)),
+                    x.schema,
+                    String(x.in) === "path" || x.required === true,
+                ),
+            )
+            .concat(
+                [...jsonNodeRoots].map((root) => ({
+                    name: toCamelCase(root),
+                    required: false,
+                    type: "object",
+                })),
+            ),
+    );
+
+    const body: Prop[] = [];
+    const requestBody = deref(doc, operation.requestBody);
+    const requestContent = pickContent(requestBody.content);
+    if (requestContent) {
+        const s = deref(doc, requestContent.schema);
+        const t = schemaType(s);
+        if (t === "object") body.push(...toProps(doc, s));
+        else if (t === "array") body.push(toProp(doc, "items", s, requestBody.required === true));
+        else body.push(toProp(doc, "body", s, requestBody.required === true));
+    }
+
+    const parsed = parseResponse(doc, operation.responses);
+    const normalizedPath = normalizePath(route);
+
+    return {
+        key: `${method}:${normalizedPath}`,
+        method,
+        path: normalizedPath,
+        params,
+        body: dedupe(body),
+        response: dedupe(parsed.response),
+        responseKind: parsed.responseKind,
+        successStatus: parsed.successStatus,
+        errorStatuses: parsed.errorStatuses,
+    } satisfies Endpoint;
+}
+
+function parseSwaggerEndpoints(swagger: unknown) {
+    const out = new Map<string, Endpoint>();
+    const doc = obj(swagger);
+    for (const [route, pathItem] of Object.entries(obj(doc.paths))) {
+        for (const [openApiMethod, method] of METHODS) {
+            const operation = obj(pathItem)[openApiMethod];
+            if (!isObj(operation)) continue;
+            const endpoint = extractEndpoint(doc, route, method, pathItem, operation);
+            out.set(endpoint.key, endpoint);
+        }
+    }
+    return out;
+}
+
+function formatGeneratedFiles(filePaths: string[]) {
+    if (!filePaths.length) return;
+    try {
+        // Absolute paths: a relative domainsDir yields paths relative to the
+        // process cwd, which a prettier run elsewhere would resolve wrongly.
+        Bun.spawnSync(["bunx", "prettier", "--write", ...filePaths.map((p) => path.resolve(p))], {
+            stdio: ["ignore", "ignore", "ignore"],
+        });
+    } catch {
+        // Formatting is cosmetic; a missing prettier must not fail the run.
+    }
+}
+
+async function fetchJson(url: string) {
+    const response = await fetch(url, {
+        headers: { Accept: "application/json" },
+    });
+    if (!response.ok) {
+        throw new Error(`Swagger request failed (${response.status})`);
+    }
+    return response.json();
+}
+
+function resolveEndpoint(key: string, extracted: Map<string, Endpoint>) {
+    const [method, route] = key.split(":");
+    if (!method || !route) return undefined;
+    return (
+        extracted.get(key) ??
+        extracted.get(`${method}:${normalizePath(`/api${route}`)}`) ??
+        (route.startsWith("/api/")
+            ? extracted.get(`${method}:${normalizePath(route.slice(4))}`)
+            : undefined)
+    );
+}
+
+// The post-write prettier pass reformats generated blocks, so an exact string
+// compare would report freshly synced files as drift forever. Compare modulo
+// the axes prettier varies: quote style, whitespace, and trailing commas.
+function sameModuloFormatting(a: string, b: string) {
+    function norm(s: string) {
+        return s
+            .replace(/['"]/g, '"')
+            .replace(/\s+/g, "")
+            .replace(/,(?=[}\])])/g, "");
+    }
+    return norm(a) === norm(b);
+}
+
+export async function extractEndpoints(options: ExtractEndpointsOptions) {
+    const { swaggerUrls, domainsDir, write = false } = options;
+
+    // Merge every document first: a file missing from one swagger doc may be
+    // matched by another. Last write wins on duplicate keys, so per-agent docs
+    // deliberately override the server-level one (collectSwaggerUrls order).
+    const extracted = new Map<string, Endpoint>();
+    for (const swaggerUrl of swaggerUrls) {
+        for (const [key, endpoint] of parseSwaggerEndpoints(await fetchJson(swaggerUrl))) {
+            extracted.set(key, endpoint);
+        }
+    }
+
+    let matched = 0;
+    const missing: string[] = [];
+    const drift: string[] = [];
+    const updated: string[] = [];
+    const updatedFiles: string[] = [];
+
+    for (const [key, filePath] of endpointFiles(domainsDir).entries()) {
+        const relativePath = path.relative(domainsDir, filePath);
+        const endpoint = resolveEndpoint(key, extracted);
+        if (!endpoint) {
+            missing.push(relativePath);
+            continue;
+        }
+
+        const current = fs.readFileSync(filePath, "utf8");
+        const next = withGeneratedBlock(current, endpoint);
+        if (next === null || next === current || sameModuloFormatting(next, current)) {
+            matched++;
+            continue;
+        }
+
+        if (!write) {
+            drift.push(relativePath);
+            continue;
+        }
+
+        fs.writeFileSync(filePath, next);
+        updatedFiles.push(filePath);
+        updated.push(relativePath);
+    }
+
+    if (write) formatGeneratedFiles(updatedFiles);
+
+    return { matched, missing, drift, updated };
+}

package/src/swagger/generated-block.ts

@@ -0,0 +1,74 @@
+/**
+ * Splicing the generated block into an endpoint definition the developer also edits
+ * by hand. The markers are the contract: everything between them belongs to the
+ * generator, everything outside is the developer's.
+ */
+import type { Endpoint, Prop } from "./types";
+
+const AUTO_START = "// @auto-generated-start";
+const AUTO_END = "// @auto-generated-end";
+
+function serializeProps(props: Prop[], depth: number) {
+    return props
+        .map((p) => {
+            const indent = "    ".repeat(depth);
+            const childIndent = "    ".repeat(depth + 1);
+            const typeLiteral = p.type.includes("'")
+                ? `"${p.type.replace(/"/g, '\\"')}"`
+                : `'${p.type}'`;
+
+            const parts = [`name: '${p.name}'`, `required: ${p.required}`, `type: ${typeLiteral}`];
+            if (p.isArray) parts.push("isArray: true");
+            if (p.properties?.length)
+                parts.push(
+                    `properties: [\n${serializeProps(p.properties, depth + 1)}\n${childIndent}]`,
+                );
+
+            return `${indent}    { ${parts.join(", ")} },`;
+        })
+        .join("\n");
+}
+
+function blockFor(endpoint: Endpoint) {
+    return `    autoGenerated: {
+        params: [
+${serializeProps(endpoint.params, 2)}
+        ] as const,
+        body: [
+${serializeProps(endpoint.body, 2)}
+        ] as const,
+        response: [
+${serializeProps(endpoint.response, 2)}
+        ] as const,
+        successStatus: ${endpoint.successStatus},
+        errorStatuses: [${endpoint.errorStatuses.join(", ")}],
+        responseKind: '${endpoint.responseKind}',
+    } as const,`;
+}
+
+/**
+ * Replaces the marked region when it exists, otherwise inserts one just inside the
+ * closing `});`. Returns null when there is nowhere to put it, which means the file
+ * is not shaped like an endpoint definition.
+ */
+export function withGeneratedBlock(current: string, endpoint: Endpoint) {
+    const start = current.indexOf(AUTO_START);
+    const end = current.indexOf(AUTO_END);
+
+    if (start >= 0 && end > start) {
+        return (
+            current.slice(0, start + AUTO_START.length) +
+            `\n${blockFor(endpoint)}\n    ` +
+            current.slice(end)
+        );
+    }
+
+    const closingIndex = current.lastIndexOf("});");
+    if (closingIndex < 0) return null;
+
+    return (
+        current.slice(0, closingIndex) +
+        `\n  ${AUTO_START}\n${blockFor(endpoint)}\n    ${AUTO_END}\n});` +
+        current.slice(closingIndex + 3)
+    );
+}