@m6d/cortex-cli 0.15.0 → 0.16.0

package/src/management/client.ts

@@ -3,47 +3,76 @@ import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 
 import { isRecord } from "@cortex/contracts/json";
+import { z } from "zod";
 
 import { profilesPath } from "./profiles";
 
-export type OpenApiOperation = {
-    operationId: string;
-    summary?: string;
-    tags?: string[];
+/**
+ * The schema subset the flag builder reads: `type`, `properties`, `required`,
+ * `enum`, `items`, `anyOf`, `description`, `format`, `$ref`, each of its
+ * declared shape when present. Parsed recursively so a nested `null` never
+ * reaches it.
+ */
+const jsonSchemaSchema = z.object({
+    type: z.union([z.string(), z.array(z.string())]).optional(),
+    get properties() {
+        return z.record(z.string(), jsonSchemaSchema).optional();
+    },
+    required: z.array(z.string()).optional(),
+    enum: z.array(z.unknown()).optional(),
+    /** `false` on a tuple, whose positions `prefixItems` lists instead. */
+    get items() {
+        return z.union([z.boolean(), jsonSchemaSchema]).optional();
+    },
+    get anyOf() {
+        return z.array(jsonSchemaSchema).optional();
+    },
+    description: z.string().optional(),
+    format: z.string().optional(),
+    $ref: z.string().optional(),
+});
+export type JsonSchema = z.infer<typeof jsonSchemaSchema>;
+
+const contentSchema = z.record(z.string(), z.object({ schema: jsonSchemaSchema }));
+
+const operationSchema = z.object({
+    operationId: z.string(),
+    summary: z.string().optional(),
+    tags: z.array(z.string()).optional(),
     /** Cortex's own semantics, so nothing here is inferred from names or prose. */
-    "x-destructive"?: true;
-    "x-publish-procedure"?: string;
-    "x-live-fields"?: string[];
+    "x-destructive": z.literal(true).optional(),
+    "x-publish-procedure": z.string().optional(),
+    "x-live-fields": z.array(z.string()).optional(),
     /** A query's input, one parameter per field; a field the URL cannot carry as a scalar has JSON `content` instead of a `schema`. */
-    parameters?: Array<{
-        name: string;
-        in: string;
-        required?: boolean;
-        schema?: JsonSchema;
-        content?: Record<string, { schema: JsonSchema }>;
-    }>;
-    requestBody?: { content: Record<string, { schema: JsonSchema }> };
-};
-export type JsonSchema = {
-    type?: string | string[];
-    properties?: Record<string, JsonSchema>;
-    required?: string[];
-    enum?: unknown[];
-    /** `false` on a tuple, whose positions `prefixItems` lists instead. */
-    items?: JsonSchema | boolean;
-    anyOf?: JsonSchema[];
-    default?: unknown;
-    description?: string;
-    format?: string;
-    $ref?: string;
-};
-export type OpenApiDocument = {
-    info: { version: string };
-    paths: Record<string, Record<string, OpenApiOperation>>;
-    components?: { schemas?: Record<string, JsonSchema> };
-};
+    parameters: z
+        .array(
+            z.object({
+                name: z.string(),
+                in: z.string(),
+                required: z.boolean().optional(),
+                schema: jsonSchemaSchema.optional(),
+                content: contentSchema.optional(),
+            }),
+        )
+        .optional(),
+    requestBody: z.object({ content: contentSchema }).optional(),
+});
+export type OpenApiOperation = z.infer<typeof operationSchema>;
+
+/**
+ * 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
+ * parsed into the shape they expect.
+ */
+const openApiDocumentSchema = z.object({
+    info: z.object({ version: z.string() }),
+    paths: z.record(z.string(), z.record(z.string(), operationSchema)),
+    components: z.object({ schemas: z.record(z.string(), jsonSchemaSchema).optional() }).optional(),
+});
+export type OpenApiDocument = z.infer<typeof openApiDocumentSchema>;
 
-type Cached = { etag: string; document: OpenApiDocument };
+const cachedSchema = z.object({ etag: z.string(), document: openApiDocumentSchema });
 
 /**
  * One cache entry per Cortex base URL (scheme, host, port, path),
@@ -61,85 +90,10 @@ function cachePath(url: string) {
     );
 }
 
-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]));
-}
-
-/**
- * The schema subset the flag builder reads: `type`, `properties`, `required`,
- * `enum`, `items`, `anyOf`, `description`, `format`, `$ref`, each of its
- * declared shape when present. Checked recursively so a nested `null` never
- * reaches it.
- */
-const SCHEMA_FIELDS = {
-    type: optional((v) => isString(v) || isStrings(v)),
-    properties: optional(recordOf(isJsonSchema)),
-    required: optional(isStrings),
-    enum: optional(Array.isArray),
-    items: optional((v) => typeof v === "boolean" || isJsonSchema(v)),
-    anyOf: optional(arrayOf(isJsonSchema)),
-    description: optional(isString),
-    format: optional(isString),
-    $ref: optional(isString),
-} satisfies Record<string, Check>;
-
-function isJsonSchema(value: unknown): value is JsonSchema {
-    return hasFields(value, SCHEMA_FIELDS);
-}
-
-const isContent = recordOf((media) => hasFields(media, { schema: isJsonSchema }));
-
-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)) })),
-    });
-}
-
-function isCached(value: unknown): value is Cached {
-    return hasFields(value, { etag: isString, document: isOpenApiDocument });
-}
-
 /** A cache entry that is missing, fails to parse, or has the wrong shape is treated as absent. */
 function readCache(path: string) {
     try {
-        const parsed: unknown = JSON.parse(readFileSync(path, "utf8"));
-        return isCached(parsed) ? parsed : undefined;
+        return cachedSchema.parse(JSON.parse(readFileSync(path, "utf8")));
     } catch {
         return undefined;
     }
@@ -161,8 +115,9 @@ export async function loadOpenApi(url: string) {
         if (response.status === 304 && cached)
             return { document: cached.document, from: "cache" as const };
         if (!response.ok) throw new Error(`HTTP ${response.status}`);
-        const document: unknown = await response.json();
-        if (!isOpenApiDocument(document)) throw new Error("not an OpenAPI document");
+        const parsed = openApiDocumentSchema.safeParse(await response.json());
+        if (!parsed.success) throw new Error("not an OpenAPI document");
+        const document = parsed.data;
         writeCache(path, { etag: response.headers.get("etag") ?? "", document });
         return { document, from: "network" as const };
     } catch (error) {
@@ -172,7 +127,7 @@ export async function loadOpenApi(url: string) {
 }
 
 /** Best-effort: a cache that cannot be written costs the next run a fetch, nothing more. */
-function writeCache(path: string, entry: Cached) {
+function writeCache(path: string, entry: z.infer<typeof cachedSchema>) {
     try {
         mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
         writeFileSync(path, JSON.stringify(entry));
@@ -208,7 +163,7 @@ export function inputSchemaOf(operation: OpenApiOperation) {
  * 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. A refusal throws
- * `ManagementError` with the error body's code, message and detail.
+ * `ManagementError` with the error body's code, message, detail and sentence.
  */
 export async function callManagement(
     profile: { url: string; key: string },
@@ -230,9 +185,10 @@ export async function callManagement(
     });
     const body: unknown = await response.json().catch(() => null);
     if (!response.ok) {
-        const { code, message, cause } = (body ?? {}) as {
+        const { code, message, refusal, cause } = (body ?? {}) as {
             code?: string;
             message?: string;
+            refusal?: string;
             cause?: unknown;
         };
         throw new ManagementError(
@@ -240,6 +196,7 @@ export async function callManagement(
             code ?? "error",
             message ?? response.statusText,
             isRecord(cause) ? cause : undefined,
+            refusal,
         );
     }
     return body;
@@ -275,13 +232,18 @@ export class UnreachableError extends Error {
     }
 }
 
-/** A refusal; `detail` is what the refusal names, when it names something (an entry, the row holding a name). */
+/**
+ * A refusal; `detail` is what the refusal names, when it names something (an
+ * entry, the row holding a name), and `refusal` the sentence Cortex words it
+ * in, when it has one.
+ */
 export class ManagementError extends Error {
     public constructor(
         public readonly status: number,
         public readonly code: string,
         message: string,
         public readonly detail?: Record<string, unknown>,
+        public readonly refusal?: string,
     ) {
         super(message);
         this.name = "ManagementError";

package/src/management/profiles.ts

@@ -2,10 +2,14 @@ import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "n
 import { homedir } from "node:os";
 import { join } from "node:path";
 
-import { isRecord } from "@cortex/contracts/json";
+import { z } from "zod";
 
-type Profile = { url: string; key: string };
-type Store = { current: string; profiles: Record<string, Profile> };
+const profileSchema = z.object({ url: z.string(), key: z.string() });
+const storeSchema = z.object({
+    current: z.string(),
+    profiles: z.record(z.string(), profileSchema),
+});
+type Store = z.infer<typeof storeSchema>;
 
 /** `~/.cortex/profiles.json`; `CORTEX_HOME` relocates it (tests, CI). */
 export function profilesPath() {
@@ -20,22 +24,6 @@ export class ProfileFileError extends Error {
     }
 }
 
-function isProfile(value: unknown): value is Profile {
-    if (!isRecord(value)) return false;
-    const { url, key } = value;
-    return typeof url === "string" && typeof key === "string";
-}
-
-function isStore(value: unknown): value is Store {
-    if (!isRecord(value)) return false;
-    const { current, profiles } = value;
-    return (
-        typeof current === "string" &&
-        isRecord(profiles) &&
-        Object.values(profiles).every(isProfile)
-    );
-}
-
 /** A profile by name, own properties only: a name like `constructor` is not a profile. */
 function lookup(store: Store, name: string) {
     return Object.hasOwn(store.profiles, name) ? store.profiles[name] : undefined;
@@ -50,8 +38,9 @@ function readStore() {
     } catch (error) {
         throw new ProfileFileError(path, error instanceof Error ? error.message : String(error));
     }
-    if (!isStore(parsed)) throw new ProfileFileError(path, "unexpected shape");
-    return parsed;
+    const store = storeSchema.safeParse(parsed);
+    if (!store.success) throw new ProfileFileError(path, z.prettifyError(store.error));
+    return store.data;
 }
 
 /** The key is a credential, so the file and its directory are owner-only. */
@@ -64,7 +53,7 @@ function writeStore(store: Store) {
 
 // Names are user input, so the store is rebuilt from entries rather than
 // assigned into: `__proto__` and friends stay ordinary keys.
-export function saveProfile(name: string, profile: Profile) {
+export function saveProfile(name: string, profile: z.infer<typeof profileSchema>) {
     const store = readStore();
     writeStore({
         current: name,

package/src/scaffold/files.ts

@@ -7,6 +7,8 @@
  * workspace, and a standalone scaffold has no workspace.
  */
 
+import { NAME_MAX_LENGTH } from "@cortex/contracts/manifest";
+
 import pkg from "../../package.json";
 import serverTs from "@/scaffold/templates/server.ts.txt";
 import setupTs from "@/scaffold/templates/setup.ts.txt";
@@ -27,7 +29,7 @@ import { applyPorts, type Ports } from "@/scaffold/ports";
  * `@m6d/cortex` range below are stamped by scripts/sync-package-versions.ts
  * before the CLI publishes, so a scaffold pins what was current then.
  */
-const CORTEX_VERSION = "0.15.0";
+const CORTEX_VERSION = "0.16.0";
 
 /** This machine as Cortex's containers name it: the one private host the stack's egress policy admits. */
 export const DOCKER_HOST = "host.docker.internal";
@@ -35,9 +37,6 @@ export const DOCKER_HOST = "host.docker.internal";
 /** How Cortex's containers reach the backend on this machine, at the port drawn for it. */
 const SERVER_URL = `http://${DOCKER_HOST}:{{port.server}}`;
 
-/** The longest server name Cortex accepts. */
-const SERVER_NAME_MAX = 100;
-
 /**
  * The agent the manifest declares and the README sends you to chat with.
  * Not `assistant`: Cortex holds that slug for its console's own assistant.
@@ -51,10 +50,11 @@ export const AGENT_SLUG = "helper";
  */
 export const EMBEDDING = { model: "text-embedding-3-small", dimension: 768 } as const;
 
+/** The ranges this repository builds with; files.test.ts holds them to its catalog. */
 const DEV_DEPENDENCIES = {
     // `cortex apply`, `cortex setup` and the management commands, at the release that wrote the project.
     "@m6d/cortex-cli": `~${pkg.version}`,
-    "@types/bun": "latest",
+    "@types/bun": "1.3.14",
     // The two runners of `bun run dev` and `bun run dev:agent`.
     concurrently: "^10.0.6",
     cspell: "^9.6.4",
@@ -63,8 +63,8 @@ const DEV_DEPENDENCIES = {
     "eslint-plugin-prettier": "^5.5.5",
     fallow: "^3.9.1",
     mprocs: "^0.9.6",
-    prettier: "^3.6.2",
-    typescript: "^5",
+    prettier: "^3.8.1",
+    typescript: "~6.0.3",
     "typescript-eslint": "^8.65.0",
 };
 
@@ -150,7 +150,7 @@ function packageJson({ name, datasets, setup }: Project) {
                 verify: "bun run format:check && bun run lint && bun run spellcheck && bun run check && bun run audit",
             },
             dependencies: {
-                "@m6d/cortex": "~0.3.0",
+                "@m6d/cortex": "~0.4.0",
                 // drizzle 1.0 is in beta; this is the build `@m6d/cortex/drizzle` is tested against.
                 ...(datasets ? { "drizzle-orm": "1.0.0-beta.15-859cf75" } : {}),
                 hono: "^4.12.3",
@@ -422,6 +422,7 @@ services:
                 condition: service_completed_successfully
             redis:
                 condition: service_healthy
+        stop_grace_period: 35s
 
     # Runs the agents: widgets, trigger callers and the console's playground
     # and assistant talk to it.
@@ -441,6 +442,7 @@ services:
                 condition: service_completed_successfully
             redis:
                 condition: service_healthy
+        stop_grace_period: 35s
 
 volumes:
     postgres-data:
@@ -530,7 +532,7 @@ pre-commit hook or CI job should run. Each is also available on its own: \`forma
  * are drawn by the caller.
  */
 export function scaffoldFiles(input: Input) {
-    const project = { ...input, server: input.name.slice(0, SERVER_NAME_MAX) };
+    const project = { ...input, server: input.name.slice(0, NAME_MAX_LENGTH) };
     const files = {
         "server.ts": serverTs,
         "setup.ts": setupTs,

package/src/ui/prompts.ts

@@ -4,6 +4,9 @@
  * 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.
+ *
+ * Questions and the cancel line render on stderr: they are the conversation,
+ * not the result, so `-o json | jq` and `> file` get only what a command prints.
  */
 
 import {
@@ -21,15 +24,25 @@ import {
 
 export { intro, log, outro };
 
-async function orExit<T>(answer: Promise<T | symbol>) {
-    const value = await answer;
+const output = process.stderr;
 
-    if (isCancel(value)) {
-        cancel("Cancelled — nothing was written.");
-        process.exit(1);
-    }
+/**
+ * Whether there is a terminal to ask on: stdin to answer from and stderr to
+ * show the question. Without one, a command never asks. On Bun a piped stream
+ * reports `isTTY` as `undefined` rather than `false`, hence `=== true`.
+ */
+export function canAsk() {
+    return process.stdin.isTTY === true && process.stderr.isTTY === true;
+}
 
-    return value;
+function exitCancelled() {
+    cancel("Cancelled — nothing was written.", { output });
+    return process.exit(1);
+}
+
+async function orExit<T>(answer: Promise<T | symbol>) {
+    const value = await answer;
+    return isCancel(value) ? exitCancelled() : value;
 }
 
 /**
@@ -42,6 +55,7 @@ export function askName(check: (name: string) => string | undefined) {
         text({
             message: "Project name",
             placeholder: "my-app",
+            output,
             validate: function (value) {
                 const candidate = (value ?? "").trim();
                 if (candidate.length === 0) return "A project name is required.";
@@ -56,12 +70,17 @@ export function askChoice<const TValue extends string>(
     message: string,
     options: Parameters<typeof select<TValue>>[0]["options"],
 ) {
-    return orExit(select({ message, options }));
+    return orExit(select({ message, options, output }));
 }
 
 /** A yes-or-no question a flag left open, answered no unless the caller says otherwise. */
 export function askConfirm(message: string, initialValue = false) {
-    return orExit(confirm({ message, initialValue }));
+    return orExit(confirm({ message, initialValue, output }));
+}
+
+/** A go-ahead `--yes` left open: answering no stops the run as Ctrl-C does. */
+export async function askToProceed(message: string) {
+    if (!(await askConfirm(message))) exitCancelled();
 }
 
 /**
@@ -77,6 +96,7 @@ export function askValue(
         text({
             message: name,
             placeholder: hint,
+            output,
             validate: function (value) {
                 const candidate = (value ?? "").trim();
                 return candidate.length === 0 ? `${name} is required.` : check(candidate);
@@ -93,6 +113,7 @@ export function askSecret(
     return orExit(
         password({
             message: name,
+            output,
             validate: (value) =>
                 (value ?? "").length === 0 ? `${name} is required.` : check(value ?? ""),
         }),