@m6d/cortex-cli 1.0.0

package/src/swagger/extract-endpoints.ts

@@ -0,0 +1,258 @@
+import * as fs from "fs";
+import * as path from "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";
+
+export type ExtractEndpointsOptions = {
+    swaggerUrls: string[];
+    domainsDir: string;
+    write?: boolean;
+};
+
+const METHODS: Array<[string, HttpMethod]> = [
+    ["get", "GET"],
+    ["post", "POST"],
+    ["put", "PUT"],
+    ["delete", "DELETE"],
+];
+
+const toCamelCase = (s: string) =>
+    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(?=\/|$)/i, "") || "/";
+    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");
+
+    // Collapse JsonNode-expanded dot-notation query params into a single
+    // object param.  Swagger expands JsonNode properties (Options, Parent,
+    // Root, …) into many individual params like "CustomFilter.Parent.Root".
+    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 (/^(Options|Parent|Root)\b/.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)
+    );
+}

package/src/swagger/openapi-schema.ts

@@ -0,0 +1,149 @@
+/**
+ * Reading an OpenAPI document: following $ref, deciding a schema's type, and turning
+ * a schema into the flat property list the generator emits. Nothing here knows what
+ * the properties are for.
+ */
+import type { Obj, Prop } from "./types";
+
+const MAX_DEPTH = 8;
+
+export const isObj = (v: unknown): v is Obj =>
+    typeof v === "object" && v !== null && !Array.isArray(v);
+export const obj = (v: unknown) => (isObj(v) ? v : {});
+const strings = (v: unknown) =>
+    Array.isArray(v) ? v.filter((x): x is string => typeof x === "string") : [];
+export const dedupe = (items: Prop[]) => {
+    const seen = new Set<string>();
+    return items.filter((x) => (seen.has(x.name) ? false : (seen.add(x.name), true)));
+};
+
+function resolvePointer(doc: unknown, ref: string) {
+    if (!ref.startsWith("#/")) return null;
+    let cur: unknown = doc;
+    for (const part of ref.slice(2).split("/")) {
+        const key = part.replace(/~1/g, "/").replace(/~0/g, "~");
+        if (!isObj(cur) || !(key in cur)) return null;
+        cur = cur[key];
+    }
+    return cur;
+}
+
+export function deref(doc: unknown, v: unknown) {
+    if (!isObj(v)) return {};
+    let x = v;
+    const seen = new Set<string>();
+    while (typeof x.$ref === "string") {
+        if (seen.has(x.$ref)) return {};
+        seen.add(x.$ref);
+        x = obj(resolvePointer(doc, x.$ref));
+    }
+    return x;
+}
+
+export function schemaType(s: Obj) {
+    const t = Array.isArray(s.type)
+        ? (s.type as unknown[]).find((x) => typeof x === "string" && x !== "null")
+        : s.type;
+    if (typeof t === "string") return t;
+    if (isObj(s.properties)) return "object";
+    if (isObj(s.items)) return "array";
+    return "";
+}
+
+const isJsonNodeRef = (v: unknown) =>
+    isObj(v) && typeof v.$ref === "string" && /\/System\.Text\.Json\.Nodes\.JsonNode$/.test(v.$ref);
+
+function isJsonNodeSchema(s: Obj) {
+    const p = obj(s.properties);
+    return (
+        schemaType(s) === "object" &&
+        "options" in p &&
+        "parent" in p &&
+        "root" in p &&
+        isJsonNodeRef(p.parent) &&
+        isJsonNodeRef(p.root)
+    );
+}
+
+function scalarType(s: Obj) {
+    if (Array.isArray(s.enum) && s.enum.every((v) => typeof v === "string")) {
+        return s.enum.map((v) => `'${String(v).replace(/'/g, "\\'")}'`).join(" | ");
+    }
+    const t = schemaType(s);
+    const f = typeof s.format === "string" ? s.format : "";
+    if (f === "uuid") return "uuid";
+    if (f === "date") return "date";
+    if (f === "date-time") return "datetime";
+    if (t === "integer" || t === "number") return "number";
+    if (t === "boolean") return "boolean";
+    if (t === "string") return "string";
+    if (t === "object") return "object";
+    return "unknown";
+}
+
+export function toProps(doc: unknown, schemaIn: unknown, depth = 0) {
+    if (depth > MAX_DEPTH) return [];
+    const s = deref(doc, schemaIn);
+    if (isJsonNodeRef(schemaIn) || isJsonNodeSchema(s)) return [];
+    const req = new Set(strings(s.required));
+    return dedupe(
+        Object.entries(obj(s.properties)).map(([name, child]) =>
+            toProp(doc, name, child, req.has(name), depth + 1),
+        ),
+    );
+}
+
+export function toProp(
+    doc: unknown,
+    name: string,
+    schemaIn: unknown,
+    required: boolean,
+    depth = 0,
+    // eslint-disable-next-line m6d/no-explicit-return-type -- mutually recursive with toProps, so the return type cannot be inferred
+): Prop {
+    if (isJsonNodeRef(schemaIn)) return { name, required, type: "object" };
+
+    const s = deref(doc, schemaIn);
+    const req = required && s.nullable !== true;
+
+    if (isJsonNodeSchema(s)) return { name, required: req, type: "object" };
+
+    const t = schemaType(s);
+    if (t === "array") {
+        const item = deref(doc, s.items);
+        if (schemaType(item) === "object") {
+            const properties = toProps(doc, item, depth + 1);
+            return {
+                name,
+                required: req,
+                type: "object",
+                isArray: true,
+                ...(properties.length ? { properties } : {}),
+            };
+        }
+        return { name, required: req, type: scalarType(item), isArray: true };
+    }
+
+    if (t === "object") {
+        const properties = toProps(doc, s, depth + 1);
+        return {
+            name,
+            required: req,
+            type: "object",
+            ...(properties.length ? { properties } : {}),
+        };
+    }
+
+    return { name, required: req, type: scalarType(s) };
+}
+
+export function pickContent(contentIn: unknown) {
+    const content = obj(contentIn);
+    const mimes = Object.keys(content);
+    if (!mimes.length) return null;
+    const mime =
+        mimes.find((x) => x.toLowerCase() === "application/json") ??
+        mimes.find((x) => x.toLowerCase().includes("json")) ??
+        mimes[0];
+    return { schema: obj(content[mime!]).schema, mimes };
+}

package/src/swagger/parse-response.ts

@@ -0,0 +1,88 @@
+/**
+ * Deciding what an endpoint answers with: which statuses it uses, and what shape the
+ * success body takes. The shape is what drives code generation, so a paged envelope
+ * is reported as the rows it wraps rather than as its own page fields.
+ */
+import type { Obj, Prop, ResponseKind } from "./types";
+import { deref, obj, pickContent, schemaType, toProp, toProps } from "./openapi-schema";
+
+type ResponseBody = { responseKind: ResponseKind; response: Prop[] };
+
+const NO_BODY: ResponseBody = { responseKind: "none", response: [] };
+
+const FILE_MIME = /(application\/octet-stream|application\/pdf|application\/vnd\.|text\/csv)/i;
+
+/** An object contributes its own fields; anything else stands as a single `item`. */
+function itemProps(doc: unknown, item: Obj) {
+    return schemaType(item) === "object" ? toProps(doc, item) : [toProp(doc, "item", item, true)];
+}
+
+function isFileResponse(mimes: string[], schema: Obj) {
+    if (mimes.some((mime) => FILE_MIME.test(mime))) return true;
+
+    return (
+        schemaType(schema) === "string" &&
+        typeof schema.format === "string" &&
+        ["binary", "base64"].includes(schema.format)
+    );
+}
+
+/** A paged envelope is described by the items it wraps, not by its own page fields. */
+function parseObjectBody(doc: unknown, schema: Obj) {
+    const props = obj(schema.properties);
+    const hasPaging = ["totalCount", "pageNumber", "pageSize", "totalPages"].some(
+        (k) => k in props,
+    );
+    const list = deref(doc, props.items ?? props.data ?? props.results);
+
+    if (hasPaging && schemaType(list) === "array") {
+        return {
+            responseKind: "paginated",
+            response: itemProps(doc, deref(doc, list.items)),
+        } satisfies ResponseBody;
+    }
+
+    return { responseKind: "object", response: toProps(doc, schema) } satisfies ResponseBody;
+}
+
+function parseResponseBody(doc: unknown, schema: Obj, mimes: string[]) {
+    if (isFileResponse(mimes, schema))
+        return { responseKind: "file", response: [] } satisfies ResponseBody;
+
+    const type = schemaType(schema);
+    if (type === "array") {
+        return {
+            responseKind: "array",
+            response: itemProps(doc, deref(doc, schema.items)),
+        } satisfies ResponseBody;
+    }
+    if (type === "object") return parseObjectBody(doc, schema);
+    if (Object.keys(schema).length) {
+        return {
+            responseKind: "object",
+            response: [toProp(doc, "value", schema, true)],
+        } satisfies ResponseBody;
+    }
+
+    return NO_BODY;
+}
+
+export function parseResponse(doc: unknown, responsesIn: unknown) {
+    const responses = obj(responsesIn);
+    const statuses = Object.keys(responses)
+        .map(Number)
+        .filter(Number.isInteger)
+        .sort((a, b) => a - b);
+    const successStatus = statuses.find((s) => s >= 200 && s < 300) ?? 200;
+    const errorStatuses = [...new Set(statuses.filter((s) => s >= 400))];
+
+    // 204 says there is no body at all, so there is nothing further to read.
+    if (successStatus === 204) return { successStatus, errorStatuses, ...NO_BODY };
+
+    const success = deref(doc, responses[String(successStatus)]);
+    const content = pickContent(success.content);
+    if (!content) return { successStatus, errorStatuses, ...NO_BODY };
+
+    const body = parseResponseBody(doc, deref(doc, content.schema), content.mimes);
+    return { successStatus, errorStatuses, ...body };
+}

package/src/swagger/types.ts

@@ -0,0 +1,25 @@
+/**
+ * The shapes shared across endpoint extraction: what an OpenAPI document looks like
+ * on the way in, and what one generated endpoint looks like on the way out.
+ */
+export type HttpMethod = "GET" | "POST" | "PUT" | "DELETE";
+export type ResponseKind = "object" | "array" | "paginated" | "file" | "none";
+export type Obj = Record<string, unknown>;
+export type Prop = {
+    name: string;
+    required: boolean;
+    type: string;
+    isArray?: boolean;
+    properties?: Prop[];
+};
+export type Endpoint = {
+    key: string;
+    method: HttpMethod;
+    path: string;
+    params: Prop[];
+    body: Prop[];
+    response: Prop[];
+    responseKind: ResponseKind;
+    successStatus: number;
+    errorStatuses: number[];
+};

package/src/ui/prompts.ts

@@ -0,0 +1,102 @@
+/**
+ * The only file that imports `@clack/prompts`. Clack signals Ctrl-C by
+ * *returning* a cancel symbol rather than throwing, so an unwrapped call reads
+ * an abandoned prompt as an answer and scaffolds the project the user just
+ * tried to escape. Every prompt goes through `orExit`, and the rest of the CLI
+ * reaches the library through this module or not at all.
+ */
+
+import {
+    cancel,
+    intro,
+    isCancel,
+    log,
+    multiselect,
+    outro,
+    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>) {
+    const value = await answer;
+
+    if (isCancel(value)) {
+        cancel("Cancelled — nothing was written.");
+        process.exit(1);
+    }
+
+    return value;
+}
+
+/**
+ * Prompted only when the positional is omitted; it is the directory name too.
+ * What makes a name usable is the `new` command's to say — this asks, re-asks
+ * while `check` returns a complaint, and knows nothing else about names.
+ */
+export function askName(check: (name: string) => string | undefined) {
+    return orExit(
+        text({
+            message: "Project name",
+            placeholder: "my-app",
+            validate: function (value) {
+                const candidate = (value ?? "").trim();
+                if (candidate.length === 0) return "A project name is required.";
+                return check(candidate);
+            },
+        }),
+    );
+}
+
+/**
+ * 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 })),
+        }),
+    );
+}
+
+type Step = { title: string; run: () => string | undefined | Promise<string | undefined> };
+
+/**
+ * Write, install, git init. The spinner only runs on a TTY: it redraws in place
+ * with cursor escapes, which is noise in a piped log, and the non-interactive
+ * transcript is plain `◇` lines. A step that returns nothing — `git init` is
+ * silent by design — leaves none.
+ */
+export async function runSteps(steps: Step[]) {
+    for (const step of steps) {
+        // `withGuide: false` because `log.step` writes the `│` between steps; the
+        // spinner adding its own leaves a doubled bar behind every silent step.
+        const spin = process.stdout.isTTY === true ? spinner({ withGuide: false }) : undefined;
+        spin?.start(step.title);
+        const done = await step.run();
+        spin?.clear();
+        if (done !== undefined) log.step(done);
+    }
+}