@m6d/cortex-cli 0.3.0 → 0.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@m6d/cortex-cli",
-    "version": "0.3.0",
+    "version": "0.5.0",
     "description": "Scaffold and operate Cortex servers",
     "license": "MIT",
     "type": "module",

package/src/cc/client.ts

@@ -1,7 +1,9 @@
 import { createHash } from "node:crypto";
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 
+import { isRecord } from "@cortex/contracts/json";
+
 import { profilesPath } from "./profiles";
 
 export type OpenApiOperation = {
@@ -58,31 +60,18 @@ function cachePath(url: string) {
     );
 }
 
-/**
- * Enough of an OpenAPI document to build commands from: `info.version`, a
- * `paths` object whose every operation has an `operationId` and, where
- * present, object-shaped `parameters`, `requestBody`, and `components`.
- * Deeper schema shapes are read defensively by the flag builder.
- */
-function isOpenApiDocument(value: unknown): value is OpenApiDocument {
-    if (!isRecord(value)) return false;
-    const { info, paths, components } = value;
-    if (!isRecord(info) || typeof info["version"] !== "string") return false;
-    if (components !== undefined) {
-        if (!isRecord(components)) return false;
-        const { schemas } = components;
-        if (
-            schemas !== undefined &&
-            !(isRecord(schemas) && Object.values(schemas).every(isJsonSchema))
-        )
-            return false;
-    }
-    return (
-        isRecord(paths) &&
-        Object.values(paths).every(
-            (methods) => isRecord(methods) && Object.values(methods).every(isOperation),
-        )
-    );
+type Check = (value: unknown) => boolean;
+
+const isString = (value: unknown) => typeof value === "string";
+const optional = (check: Check) => (value: unknown) => value === undefined || check(value);
+const arrayOf = (check: Check) => (value: unknown) => Array.isArray(value) && value.every(check);
+const recordOf = (check: Check) => (value: unknown) =>
+    isRecord(value) && Object.values(value).every(check);
+const isStrings = arrayOf(isString);
+
+/** A record whose every listed field passes its check; fields not listed are ignored. */
+function hasFields(value: unknown, fields: Record<string, Check>) {
+    return isRecord(value) && Object.entries(fields).every(([key, check]) => check(value[key]));
 }
 
 /**
@@ -91,83 +80,62 @@ function isOpenApiDocument(value: unknown): value is OpenApiDocument {
  * declared shape when present. Checked recursively so a nested `null` never
  * reaches it.
  */
-function isJsonSchema(value: unknown): value is JsonSchema {
-    return isRecord(value) && Object.entries(SCHEMA_FIELDS).every(([key, ok]) => ok(value[key]));
-}
-
-const isString = (value: unknown) => typeof value === "string";
-const isStrings = (value: unknown) => Array.isArray(value) && value.every(isString);
-const optional = (check: (value: unknown) => boolean) => (value: unknown) =>
-    value === undefined || check(value);
-
-/** One check per field the flag builder reads; anything else in the schema is ignored. */
 const SCHEMA_FIELDS = {
     type: optional((v) => isString(v) || isStrings(v)),
-    properties: optional((v) => isRecord(v) && Object.values(v).every(isJsonSchema)),
+    properties: optional(recordOf(isJsonSchema)),
     required: optional(isStrings),
     enum: optional(Array.isArray),
     items: optional(isJsonSchema),
-    anyOf: optional((v) => Array.isArray(v) && v.every(isJsonSchema)),
+    anyOf: optional(arrayOf(isJsonSchema)),
     description: optional(isString),
     format: optional(isString),
     $ref: optional(isString),
-} satisfies Record<string, (value: unknown) => boolean>;
+} satisfies Record<string, Check>;
 
-function isContent(value: unknown): value is Record<string, { schema: JsonSchema }> {
-    return (
-        isRecord(value) &&
-        Object.values(value).every((media) => isRecord(media) && isJsonSchema(media["schema"]))
-    );
+function isJsonSchema(value: unknown): value is JsonSchema {
+    return hasFields(value, SCHEMA_FIELDS);
 }
 
-function isOperation(value: unknown): value is OpenApiOperation {
-    if (!isRecord(value) || typeof value["operationId"] !== "string") return false;
-    const { summary, tags, parameters, requestBody } = value;
-    const publishProcedure = value["x-publish-procedure"];
-    const liveFields = value["x-live-fields"];
-    if (summary !== undefined && typeof summary !== "string") return false;
-    if (publishProcedure !== undefined && typeof publishProcedure !== "string") return false;
-    if (
-        liveFields !== undefined &&
-        !(Array.isArray(liveFields) && liveFields.every((f) => typeof f === "string"))
-    )
-        return false;
-    if (tags !== undefined && !(Array.isArray(tags) && tags.every((t) => typeof t === "string")))
-        return false;
-    if (
-        parameters !== undefined &&
-        !(
-            Array.isArray(parameters) &&
-            parameters.every(
-                (p) =>
-                    isRecord(p) &&
-                    typeof p["name"] === "string" &&
-                    typeof p["in"] === "string" &&
-                    (p["required"] === undefined || typeof p["required"] === "boolean") &&
-                    (p["schema"] === undefined || isJsonSchema(p["schema"])) &&
-                    (p["content"] === undefined || isContent(p["content"])),
-            )
-        )
-    )
-        return false;
-    return (
-        requestBody === undefined || (isRecord(requestBody) && isContent(requestBody["content"]))
-    );
-}
+const isContent = recordOf((media) => hasFields(media, { schema: isJsonSchema }));
 
-function isCached(value: unknown): value is Cached {
-    return (
-        isRecord(value) && typeof value["etag"] === "string" && isOpenApiDocument(value["document"])
-    );
+const PARAMETER_FIELDS = {
+    name: isString,
+    in: isString,
+    required: optional((v) => typeof v === "boolean"),
+    schema: optional(isJsonSchema),
+    content: optional(isContent),
+} satisfies Record<string, Check>;
+
+const OPERATION_FIELDS = {
+    operationId: isString,
+    summary: optional(isString),
+    tags: optional(isStrings),
+    "x-publish-procedure": optional(isString),
+    "x-live-fields": optional(isStrings),
+    parameters: optional(arrayOf((parameter) => hasFields(parameter, PARAMETER_FIELDS))),
+    requestBody: optional((v) => hasFields(v, { content: isContent })),
+} satisfies Record<string, Check>;
+
+/**
+ * Enough of an OpenAPI document to build commands from: `info.version`, and a
+ * `paths` object whose every operation has an `operationId`. Every field the
+ * command and flag builders read, down through `components` schemas, is
+ * checked for the shape they expect.
+ */
+function isOpenApiDocument(value: unknown): value is OpenApiDocument {
+    return hasFields(value, {
+        info: (v) => hasFields(v, { version: isString }),
+        paths: recordOf(recordOf((operation) => hasFields(operation, OPERATION_FIELDS))),
+        components: optional((v) => hasFields(v, { schemas: optional(recordOf(isJsonSchema)) })),
+    });
 }
 
-export function isRecord(value: unknown): value is Record<string, unknown> {
-    return typeof value === "object" && value !== null && !Array.isArray(value);
+function isCached(value: unknown): value is Cached {
+    return hasFields(value, { etag: isString, document: isOpenApiDocument });
 }
 
-/** A cache entry that fails to parse or has the wrong shape is treated as absent. */
+/** A cache entry that is missing, fails to parse, or has the wrong shape is treated as absent. */
 function readCache(path: string) {
-    if (!existsSync(path)) return undefined;
     try {
         const parsed: unknown = JSON.parse(readFileSync(path, "utf8"));
         return isCached(parsed) ? parsed : undefined;
@@ -180,7 +148,7 @@ function readCache(path: string) {
  * The management API's OpenAPI document, which is what the command tree is
  * built from. Revalidated with `If-None-Match` on every run and cached beside
  * the profiles, so a second run costs one 304 and an offline run still has
- * commands. `null` when neither the network nor the cache can supply it.
+ * commands. Throws when neither the network nor the cache can supply it.
  */
 export async function loadOpenApi(url: string) {
     const path = cachePath(url);
@@ -197,7 +165,7 @@ export async function loadOpenApi(url: string) {
         writeCache(path, { etag: response.headers.get("etag") ?? "", document });
         return { document, from: "network" as const };
     } catch (error) {
-        if (cached) return { document: cached.document, from: "stale" as const, error };
+        if (cached) return { document: cached.document, from: "stale" as const };
         throw error;
     }
 }
@@ -238,8 +206,8 @@ export function inputSchemaOf(operation: OpenApiOperation) {
  * One management call. A query's input object is spread over the query
  * string, one parameter per field, with a scalar written plainly and
  * anything else JSON-encoded, which is how the document declares it. A
- * mutation posts its input as the JSON body. The error body's message on
- * failure.
+ * mutation posts its input as the JSON body. A refusal throws
+ * `ManagementError` with the error body's code and message.
  */
 export async function callManagement(
     profile: { url: string; key: string },

package/src/cc/flags.ts

@@ -86,22 +86,19 @@ export function parseAnswer(flag: Flag, answer: string) {
     return ANSWER_PARSERS[flag.kind](text, flag);
 }
 
-const finite = (text: string) => (Number.isFinite(Number(text)) ? Number(text) : undefined);
-const json = (text: string) => {
-    try {
-        return JSON.parse(text) as unknown;
-    } catch {
-        return undefined;
-    }
-};
-
 /** One parser per flag kind; booleans and enums must match a choice, arrays split on commas. */
 const ANSWER_PARSERS = {
     boolean: (text) => ({ true: true, false: false })[text],
     enum: (text, flag) => (flag.choices?.includes(text) ? text : undefined),
-    number: finite,
+    number: (text) => (Number.isFinite(Number(text)) ? Number(text) : undefined),
     array: (text) => text.split(",").map((item) => item.trim()),
-    json,
+    json: (text) => {
+        try {
+            return JSON.parse(text) as unknown;
+        } catch {
+            return undefined;
+        }
+    },
     string: (text) => text,
 } satisfies Record<Flag["kind"], (text: string, flag: Flag) => unknown>;
 

package/src/cc/output.ts

@@ -1,14 +1,11 @@
+import { isRecord } from "@cortex/contracts/json";
+
 import * as report from "@/ui/report";
 
 type Listing = { items: Array<Record<string, unknown>>; count: number; filteredCount: number };
 
 function isListing(value: unknown): value is Listing {
-    return (
-        typeof value === "object" &&
-        value !== null &&
-        "items" in value &&
-        Array.isArray(value.items)
-    );
+    return isRecord(value) && Array.isArray(value["items"]);
 }
 
 /**

package/src/cc/profiles.ts

@@ -2,6 +2,8 @@ import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "n
 import { homedir } from "node:os";
 import { join } from "node:path";
 
+import { isRecord } from "@cortex/contracts/json";
+
 type Profile = { url: string; key: string };
 type Store = { current: string; profiles: Record<string, Profile> };
 
@@ -19,22 +21,17 @@ export class ProfileFileError extends Error {
 }
 
 function isProfile(value: unknown): value is Profile {
-    return (
-        typeof value === "object" &&
-        value !== null &&
-        typeof (value as Record<string, unknown>)["url"] === "string" &&
-        typeof (value as Record<string, unknown>)["key"] === "string"
-    );
+    if (!isRecord(value)) return false;
+    const { url, key } = value;
+    return typeof url === "string" && typeof key === "string";
 }
 
 function isStore(value: unknown): value is Store {
-    if (typeof value !== "object" || value === null) return false;
-    const { current, profiles } = value as Record<string, unknown>;
+    if (!isRecord(value)) return false;
+    const { current, profiles } = value;
     return (
         typeof current === "string" &&
-        typeof profiles === "object" &&
-        profiles !== null &&
-        !Array.isArray(profiles) &&
+        isRecord(profiles) &&
         Object.values(profiles).every(isProfile)
     );
 }

package/src/commands/cc.ts

@@ -1,9 +1,10 @@
 import { readFileSync } from "node:fs";
 
 import { type Command, Option } from "@commander-js/extra-typings";
-import { isTlsOrLoopback } from "@cortex/contracts/egress";
+import { canCarrySecret } from "@cortex/contracts/egress";
+import { isRecord } from "@cortex/contracts/json";
 
-import { callManagement, inputSchemaOf, isRecord, loadOpenApi, ManagementError } from "@/cc/client";
+import { callManagement, inputSchemaOf, loadOpenApi, ManagementError } from "@/cc/client";
 import type { OpenApiDocument, OpenApiOperation } from "@/cc/client";
 import { flagsFor, parseAnswer, toOption } from "@/cc/flags";
 import type { Flag } from "@/cc/flags";
@@ -166,7 +167,7 @@ function withProfileFile<T>(operation: () => T) {
 
 /** The key rides on every call, so the URL it goes to must be https (or loopback). */
 function requireTls(url: string) {
-    if (isTlsOrLoopback(url)) return url;
+    if (canCarrySecret(url, false)) return url;
     return report.fail({
         what: `${url} is not https`,
         blocks: [
@@ -191,13 +192,13 @@ function requireProfile(name: string | undefined) {
     return profile;
 }
 
-type Resolved = NonNullable<ReturnType<typeof resolveProfile>>;
+type ResolvedProfile = NonNullable<ReturnType<typeof resolveProfile>>;
 
 type CcGroup = Command<[], { profile?: string; output: "table" | "json" }>;
 
 type Operation = { path: string; method: "get" | "post"; operation: OpenApiOperation };
 
-async function buildResourceCommands(cc: CcGroup, profile: Resolved) {
+async function buildResourceCommands(cc: CcGroup, profile: ResolvedProfile) {
     const loaded = await loadOpenApi(profile.url).catch((error: unknown) =>
         report.fail({
             what: `Could not read the management API at ${profile.url}`,
@@ -210,14 +211,15 @@ async function buildResourceCommands(cc: CcGroup, profile: Resolved) {
     if (loaded.from === "stale")
         report.aside(`Using cached commands; ${profile.url} is unreachable.`);
     const { document } = loaded;
+    const byRouter = groupByRouter(document);
 
     // Every operation by procedure path, so a write can find the operation
     // its `x-publish-procedure` names and invoke it by that operation's own
     // method and path.
     const byProcedure = new Map(
-        [...groupByRouter(document).values()].flat().map((o) => [o.operation.operationId, o]),
+        [...byRouter.values()].flat().map((o) => [o.operation.operationId, o]),
     );
-    for (const [router, operations] of groupByRouter(document)) {
+    for (const [router, operations] of byRouter) {
         const group = cc.command(router).description(`${router} procedures`).helpCommand(false);
         for (const operation of operations) {
             registerOperation({ cc, group, router, operation, byProcedure, document, profile });
@@ -252,7 +254,7 @@ function registerOperation(scope: {
     operation: Operation;
     byProcedure: Map<string, Operation>;
     document: OpenApiDocument;
-    profile: Resolved;
+    profile: ResolvedProfile;
 }) {
     const { cc, group, router, byProcedure, document, profile } = scope;
     const { path, method, operation } = scope.operation;
@@ -341,7 +343,7 @@ function declareCommand(
  * since "draft" would understate what just happened.
  */
 async function publishAfterWrite(
-    profile: Resolved,
+    profile: ResolvedProfile,
     publisher: Operation,
     result: unknown,
     publish: boolean,
@@ -372,7 +374,7 @@ async function publishAfterWrite(
  * A management refusal, or a Control Center that cannot be reached, is the
  * run's outcome, in the error grammar; anything else is a bug.
  */
-async function callOrFail<T>(profile: Resolved, call: () => Promise<T>) {
+async function callOrFail<T>(profile: ResolvedProfile, call: () => Promise<T>) {
     try {
         return await call();
     } catch (error) {
@@ -475,7 +477,12 @@ function readJsonBody(source: string) {
     return parsed;
 }
 
-async function walkPages(profile: Resolved, method: "get" | "post", path: string, body: unknown) {
+async function walkPages(
+    profile: ResolvedProfile,
+    method: "get" | "post",
+    path: string,
+    body: unknown,
+) {
     const given = isRecord(body) ? body : {};
     const pageSize = typeof given["pageSize"] === "number" ? given["pageSize"] : 100;
     const items = new Array<unknown>();

package/src/commands/graph.ts

@@ -62,12 +62,13 @@ 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, and only when the config has them:
-    // an absent section is `runSeed`'s error to throw, not ours to predict.
+    // 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) report.input("Domains", `${names.length} — ${names.join(", ")}`);
+    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 {
@@ -121,7 +122,7 @@ function truncate(text: string) {
 
 /** Server level first, then per agent — an agent's domain of the same name wins. */
 function collectDomains(config: ProjectConfig) {
-    const all: Record<string, DomainDef> = { ...config.knowledge?.domains };
+    const all = { ...config.knowledge?.domains };
 
     for (const agent of Object.values(config.agents ?? {})) {
         Object.assign(all, agent.knowledge?.domains);
@@ -136,7 +137,6 @@ function collectDomains(config: ProjectConfig) {
  * come from, and the version it seeds at is the version of that dependency.
  */
 async function runSeed(config: ProjectConfig, domains: Record<string, DomainDef>) {
-    if (!Object.keys(domains).length) throw new Error("No domains found in knowledge config");
     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");
 
@@ -182,8 +182,19 @@ async function warnOnRestamp(neo4j: Neo4jClient) {
     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",
+        ],
+    });
+}
+
 /**
- * Section requirements are `runSeed`'s to enforce — it already throws
+ * 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: {
@@ -195,18 +206,6 @@ function failSeed(options: {
     const { error, config, configPath, verbose } = options;
     const label = configLabel(configPath);
     const message = error instanceof Error ? error.message : String(error);
-
-    if (message === "No domains found in knowledge config") {
-        report.fail({
-            what: `${label} 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",
-            ],
-        });
-    }
-
     const url = config.neo4j?.url;
     if (url !== undefined && UNREACHABLE.test(message)) {
         report.fail({

package/src/commands/new.ts

@@ -68,9 +68,8 @@ type Options = {
 async function scaffold(name: string | undefined, options: Options) {
     const { verbose, databasePassed } = options;
 
-    // No TTY ⇒ never prompt and behave as `--yes`. On Bun a
-    // piped stdin reports `undefined` rather than `false`, which is why this
-    // compares against `true`.
+    // No TTY ⇒ never prompt and behave as `--yes`. On Bun a piped stdin reports
+    // `undefined` rather than `false`, which is why this compares against `true`.
     const interactive = process.stdin.isTTY === true && options.yes !== true;
 
     if (name === undefined && !interactive) missingName();
@@ -293,9 +292,9 @@ function isInsideWorkTree(target: string) {
 }
 
 function missingName(): never {
-    // No TTY ⇒ never prompt, so a missing required argument is a hard error
-    // With a TTY this branch is only reached under `--yes`,
-    // which answers every question including the one that has no default.
+    // No TTY ⇒ never prompt, so a missing required argument is a hard error.
+    // With a TTY this branch is only reached under `--yes`, which answers every
+    // question including the one that has no default.
     report.fail({
         what:
             process.stdin.isTTY === true

package/src/commands/swagger.ts

@@ -4,7 +4,7 @@ import { dirname, join, resolve } from "node:path";
 import { type Command, Option } from "@commander-js/extra-typings";
 
 import { configLabel, configOption, openProject } from "@/config/load";
-import { extractEndpoints } from "@/swagger/extract-endpoints";
+import { declaredRoute, extractEndpoints } from "@/swagger/extract-endpoints";
 import * as report from "@/ui/report";
 
 /** A convention, not config: `KnowledgeConfig` has no `domainsDir`. */
@@ -60,11 +60,21 @@ async function run(group: Command, verb: "sync" | "check", domainsDirOption: str
     if (!existsSync(domainsDir)) failMissingDomainsDir(domainsDir, verb);
 
     const urls = swaggerUrls(loaded);
+    if (!urls.length) failMissingSwaggerUrl(configPath, verb);
     for (const url of urls) report.input("Swagger", url);
 
+    // Unlike `graph seed`, this needs nothing from the project's server — not
+    // even a version handshake. What it writes is `.endpoint.ts` source whose
+    // generated block has to satisfy that server's own `EndpointDef`, so a
+    // codegen that outran the installed server is a type error in the project's
+    // `bun run check`, loudly, rather than something to detect here.
     const startedAt = Date.now();
-    const result = await runExtract(urls, domainsDir, verb).catch(function (error: unknown): never {
-        return failExtract({ error, configPath, verbose, verb });
+    const result = await extractEndpoints({
+        swaggerUrls: urls,
+        domainsDir,
+        write: verb === "sync",
+    }).catch(function (error: unknown): never {
+        return failExtract({ error, configPath, verbose });
     });
 
     // Reported once the run is over because that is when the count is known —
@@ -170,28 +180,12 @@ function renderCheck(result: Report, domainsDir: string, elapsed: string, sync:
 }
 
 /**
- * The route a finding is about, read back the way the server's own file walk
- * reads it. The report is a list of paths; the route is what the reader has to
- * act on, and it lives in the file.
+ * The route a finding is about. The report is a list of paths; the route is
+ * what the reader has to act on, and it lives in the file.
  */
 function routeOf(filePath: string) {
-    const source = readFileSync(filePath, "utf8");
-    const method = source.match(/^\s*method:\s*(['"])([^'"]+)\1/m)?.[2] ?? "?";
-    const route = source.match(/^\s*path:\s*(['"])([^'"]+)\1/m)?.[2] ?? "?";
-    return `${method} ${route}`;
-}
-
-/**
- * Unlike `graph seed`, this needs nothing from the project's server — not even a
- * version handshake. What it writes is `.endpoint.ts` source whose generated block
- * has to satisfy that server's own `EndpointDef`, so a codegen that outran the
- * installed server is a type error in the project's `bun run check`, loudly, rather
- * than something to detect here.
- */
-async function runExtract(swaggerUrls: string[], domainsDir: string, verb: "sync" | "check") {
-    if (!swaggerUrls.length) throw new Error("No swagger URLs found in knowledge config");
-
-    return await extractEndpoints({ swaggerUrls, domainsDir, write: verb === "sync" });
+    const { method = "?", path = "?" } = declaredRoute(readFileSync(filePath, "utf8"));
+    return `${method} ${path}`;
 }
 
 /** Server level, then per agent, deduped — per-agent docs override on a key clash. */
@@ -225,37 +219,29 @@ function failMissingDomainsDir(domainsDir: string, verb: string): never {
     });
 }
 
+function failMissingSwaggerUrl(configPath: string, verb: string): never {
+    report.fail({
+        what: `${configLabel(configPath)} has no knowledge.swagger.url`,
+        blocks: [
+            `\`swagger ${verb}\` generates endpoint schemas from a Swagger spec. Add one:`,
+            '  knowledge: { swagger: { url: "https://api.example.com/swagger/v1/swagger.json" } }',
+            "See https://github.com/boring91/cortex/blob/main/packages/cortex-server/README.md#file-structure-convention",
+        ],
+    });
+}
+
 /**
- * Section requirements are `runExtract`'s to enforce — it already throws
- * `"No swagger URLs found in knowledge config"`. This renders what it threw.
+ * The `◇ Swagger` lines above name every URL that was tried, so the error
+ * states the failure and points at the key behind it.
  */
-function failExtract(options: {
-    error: unknown;
-    configPath: string;
-    verbose: boolean;
-    verb: string;
-}): never {
-    const { error, configPath, verbose, verb } = options;
-    const label = configLabel(configPath);
-    const message = error instanceof Error ? error.message : String(error);
-
-    if (message === "No swagger URLs found in knowledge config") {
-        report.fail({
-            what: `${label} has no knowledge.swagger.url`,
-            blocks: [
-                `\`swagger ${verb}\` generates endpoint schemas from a Swagger spec. Add one:`,
-                '  knowledge: { swagger: { url: "https://api.example.com/swagger/v1/swagger.json" } }',
-                "See https://github.com/boring91/cortex/blob/main/packages/cortex-server/README.md#file-structure-convention",
-            ],
-        });
-    }
-
-    // The `◇ Swagger` lines above name every URL that was tried, so the error
-    // states the failure and points at the key behind it.
+function failExtract(options: { error: unknown; configPath: string; verbose: boolean }): never {
+    const { error, configPath, verbose } = options;
     report.fail({
         what: "Could not read the Swagger spec",
         error,
-        blocks: [`Is the API running? Otherwise check knowledge.swagger.url in\n${label}.`],
+        blocks: [
+            `Is the API running? Otherwise check knowledge.swagger.url in\n${configLabel(configPath)}.`,
+        ],
         verbose,
     });
 }

package/src/config/load.ts

@@ -11,13 +11,13 @@ import { pathToFileURL } from "node:url";
 
 import { Option } from "@commander-js/extra-typings";
 import type { Command } from "@commander-js/extra-typings";
+import { isRecord } from "@cortex/contracts/json";
 
 import { validateConfig } from "@/config/validate";
 import * as report from "@/ui/report";
 
 // Discovery is this exact name in the cwd, with no upward walk, so the flag's
-// default *is* the discovery rule. The second argument is what help prints;
-// without it commander would JSON.stringify the path and show quotes.
+// default *is* the discovery rule.
 const DEFAULT_CONFIG = "./cortex.config.ts";
 
 /**
@@ -27,6 +27,8 @@ const DEFAULT_CONFIG = "./cortex.config.ts";
  * `swagger sync -c x` both land on the group.
  */
 export function configOption() {
+    // The second argument is what help prints; without it commander would
+    // JSON.stringify the path and show quotes.
     return new Option("-c, --config <path>", "Path to cortex.config.ts").default(
         DEFAULT_CONFIG,
         DEFAULT_CONFIG,
@@ -100,11 +102,9 @@ async function loadConfig(path: string, verbose: boolean) {
         const config = module.default;
 
         if (config === undefined) throw new Error("The module has no default export.");
-        if (typeof config !== "object" || config === null || Array.isArray(config)) {
-            throw new Error("The default export is not an object.");
-        }
+        if (!isRecord(config)) throw new Error("The default export is not an object.");
 
-        return config as Record<string, unknown>;
+        return config;
     } catch (error) {
         report.fail({
             what: `Could not load ${configLabel(path)}`,