@m6d/cortex-cli 0.15.0 → 0.17.0

package/README.md

@@ -48,11 +48,11 @@ manifest takes its id from the name and Cortex keeps the id `cortex` for its own
 bunx @m6d/cortex-cli new shop --datasets
 ```
 
-On a TTY it asks only what the flags left open: the name, whether to set up the `helper` agent on
-the first `bun run dev`, and if so the model provider (name, base URL, API key, model). It checks
+On a terminal it asks only what the flags left open: the name, whether to set up the `helper` agent
+on the first `bun run dev`, and if so the model provider (name, base URL, API key, model). It checks
 the provider with one chat message to the model, and reuses it for embeddings when it serves the
-stack's embedding model. With no TTY it never prompts and behaves as `--yes`, so a missing name is a
-hard error rather than a hang.
+stack's embedding model. With no terminal (stdin and stderr) to ask on, it never prompts and behaves
+as `--yes`, so a missing name is a hard error rather than a hang.
 
 | Flag                     | Default | Writes                                                                                      |
 | ------------------------ | ------- | ------------------------------------------------------------------------------------------- |
@@ -62,15 +62,15 @@ hard error rather than a hang.
 
 The image runs at the Cortex release that was current when this CLI was published
 (`CORTEX_VERSION` in the shell picks another); the backend depends on the `@m6d/cortex` release of
-that time. A server name stops at Cortex's 100 characters, so a longer project name is
+that time. A server name stops at Cortex's 120 characters, so a longer project name is
 registered cut to that length.
 
 ## `cortex setup`
 
 Registers a `cortex new` project's backend in its Cortex, then applies its manifest. It reads the
 backend's name, URL and key (`CORTEX_SERVER_*`) and the model provider (`MODEL_PROVIDER_*`) from
-`.env`, and goes in the one order Cortex accepts: the server key's secret, the provider's key and
-the provider, the server on the provider's model, a sync of the server, then the apply. Each step
+`.env`, and goes in the one order Cortex accepts: the provider's key and the provider, the server
+key's secret and the server on the provider's model, a sync of the server, then the apply. Each step
 creates what is missing and keeps what exists, so a second run changes nothing. A key's secret is
 named for its value (`openai-api-key-1a2b3c4d`), so a changed key gets a new secret the provider or
 server moves to, and whatever else presents the old one keeps it. A provider or server under
@@ -87,8 +87,14 @@ bun cortex setup --wait --yes # what `bun run dev` runs
 image. Without `-p`, setup sets up the Cortex `.env` names: a different `CORTEX_URL` exported in the
 shell, which Bun lets win over `.env`, ends the run. The retried sync, a minute while Cortex cannot
 reach the backend, gives up at once on any other refusal. With no model provider and `--yes`, it
-registers the server and applies nothing: Cortex publishes no agent without a model. The run that
-first creates something says how to sign in, with the password only on a terminal.
+registers the server without a model and still applies, since an agent may name its own; when
+Cortex refuses an agent for want of one (`chat_model_required`), nothing is applied and setup says
+how to add a provider. The apply
+deletes what the manifest created and no longer lists, so like `cortex apply` it asks on a terminal
+before it writes anything, and needs `--yes` without one. A field the manifest changes that was
+also edited live is asked about on a terminal. Under `--yes`, as `bun run dev` runs it, such a
+conflict stops every run until `bun cortex apply --yes --prefer live` (or `manifest`) settles it.
+The run that first creates something says how to sign in, with the password only on a terminal.
 
 ## Management commands
 
@@ -121,17 +127,22 @@ field left out, `id` included, is asked for on a terminal and named as the
 missing flag or positional otherwise. Listings take `--pageIndex`, `--pageSize`, `--q`, and `--all` to
 walk every page. `-o json` prints the raw result for pipes.
 
-Writes to agents, tools, services, skills, triggers, and dataset hosts save
-drafts.
+Writes to agents, tools, services, skills, triggers, MCP servers, and dataset
+hosts save drafts.
 `--publish` on a write the API marks publishable (`update`, and a `create`
 whose result is complete enough) runs that entity's publish procedure right
 after; without it the command says so and names the command. Fields the API
 marks live (`x-live-fields`) take effect without a publish, from agents'
 next turn, and the command names them: a trigger's
 `credentialName`, `fireCredentialName` and model, say, or a dataset host's
-`url`, `credentials` and `timeoutMs`. `cortex datasetHosts sync <id>` reads a host's manifest, and a
+`url`, `headers` and `timeoutMs`. `cortex datasetHosts sync <id>` reads a host's manifest, and a
 draft host publishes only after `datasetHosts test` reached it once.
 
+A procedure the API marks destructive (`x-destructive`: delete, publish, rotate, toggle and the
+like) asks before anything is sent, and so does a `--publish` that runs one. `--yes` skips the
+question. With no terminal to ask on, the command fails unless `--yes` is given, so scripts and CI
+pass it. Questions render on stderr, so `-o json` output stays parseable.
+
 ## `cortex apply`
 
 Makes Cortex match a manifest, in one transaction: what is new is
@@ -142,16 +153,16 @@ touched, and a name one of them holds fails the apply.
 ```sh
 cortex apply                             # ./cortex.manifest.ts
 cortex apply deploy/manifest.json --dry-run
-cortex apply -p prod
+cortex apply -p prod --yes               # no question, as CI needs
 cortex apply --prefer live               # keep every live edit the manifest also changed
 ```
 
 An entry's `overridable` lists the fields people may change in Cortex, such
 as an agent's `prompt`. An apply keeps those edits. When the manifest changes
 a field that was also edited live, `cortex apply` asks which to keep for
-each one. `--prefer live` or `--prefer manifest` answers them all. Without a
-terminal and without `--prefer`, the apply changes nothing and lists the
-conflicts; `--dry-run` marks each with `!`.
+each one. `--prefer live` or `--prefer manifest` answers them all. `--yes`
+never asks: under it, as without a terminal, an apply with conflicts and no
+`--prefer` changes nothing and lists them. `--dry-run` marks each with `!`.
 
 The path defaults to exactly `./cortex.manifest.ts` in the directory you run
 in. TypeScript and JSON load the same way: the file's default export is the
@@ -189,7 +200,9 @@ openapi: [
     {
         name: "shop",
         url: "https://shop.example.com/openapi.json",
-        credentials: [{ header: "Authorization", prefix: "Bearer ", credential: null }],
+        headers: [{ header: "Authorization", prefix: "Bearer ", from: { kind: "runToken" } }],
+        // For an API that wraps every answer: where each one keeps its result.
+        // resultPath: "/data",
         pinned: ["findOrder"],
         // A GET runs at once; any other method waits for the end user's approval.
         approval: { never: ["addOrderNote"], always: ["exportOrders"] },
@@ -198,10 +211,11 @@ openapi: [
 ],
 ```
 
-Every apply reads the document first, without the source's credentials. An
+Every apply reads the document first, without the source's headers. An
 operation it adds is created, a changed one updated, and a dropped one
-deleted. A source with credentials is read only over https, or from a host
-the deployment allows, since the document says where they go. A source needs the `tools` write permission even when nothing
+deleted. A source whose headers carry a credential or the run token is read
+only over https, or from a host the deployment allows, since the document
+says where they go. A source needs the `tools` write permission even when nothing
 changes. Each tool is named after its `operationId`, made an identifier of at
 most 64 characters; an operation Cortex cannot import is left
 out. Two operations that come out with one name are told apart by a number
@@ -215,16 +229,19 @@ The manifest is checked against the contract before anything is sent, then
 sent as written, so Cortex fills its own defaults. It goes to the
 management API (`manifests/sync`, or `manifests/preview` with `--dry-run`,
 which changes nothing) under the same profile the management commands use, so
-the key needs `publishing:publish` and the write permission of every kind the
+the key needs `manifests:apply` and the write permission of every kind the
 apply changes. The output lists each changed entry under its kind: `+`
 created, `~` updated, `-` deleted. A trigger the apply creates, or whose
 `fireCredential` it drops, gets a fire secret, printed once below the summary
 and never again.
 
+Since a sync deletes, `cortex apply` asks before sending it. `--yes` skips the
+question, and is required with no terminal to ask on. `--dry-run` never asks.
+
 References between entries (mentions, service scopes, which role a
 credential or secret plays) are judged on the state the apply leaves, so
 the order the manifest lists them in does not matter. A dataset host's
-credentials are the exception: its catalog is read with them before the
+headers are the exception: its catalog is read with them before the
 apply, so they are judged on the deployment as it stands. A credential a
 trigger fires with cannot go to a host in the same apply that drops
 it; drop it first, then apply again.
@@ -240,9 +257,9 @@ it; drop it first, then apply again.
 
 ## Exit codes
 
-| Command | 0                                                          | 1                                                   |
-| ------- | ---------------------------------------------------------- | --------------------------------------------------- |
-| `new`   | Files written — even if `bun install` failed               | Bad target, missing name, cancelled                 |
-| `setup` | Set up, or the server registered with no model to apply on | Not a project, or Cortex refused or was unreachable |
-| `apply` | Applied, or previewed with `--dry-run`                     | Invalid manifest, or refused                        |
-| others  | The procedure ran                                          | It failed, or couldn't run                          |
+| Command | 0                                                          | 1                                                         |
+| ------- | ---------------------------------------------------------- | --------------------------------------------------------- |
+| `new`   | Files written — even if `bun install` failed               | Bad target, missing name, cancelled                       |
+| `setup` | Set up, or the server registered with no model to apply on | Not a project, Cortex refused or unreachable, or declined |
+| `apply` | Applied, or previewed with `--dry-run`                     | Invalid manifest, refused, or declined                    |
+| others  | The procedure ran                                          | It failed, or couldn't run                                |

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@m6d/cortex-cli",
-    "version": "0.15.0",
+    "version": "0.17.0",
     "description": "Scaffold Cortex projects and manage a Cortex deployment",
     "license": "MIT",
     "type": "module",
@@ -16,7 +16,7 @@
     ],
     "scripts": {
         "check": "tsc --noEmit",
-        "prepack": "rm -rf src/contracts && cp -R ../../internal/contracts/src src/contracts",
+        "prepack": "rm -rf src/contracts && bun ../../tooling/semantic-release/release-dirs.js src/contracts",
         "postpack": "rm -rf src/contracts",
         "test": "bun test"
     },
@@ -37,16 +37,6 @@
     },
     "releaseWatchPaths": [
         "apps/cortex",
-        "packages/cortex-typescript",
-        "internal/contracts/src/client-tools",
-        "internal/contracts/src/datasets",
-        "internal/contracts/src/egress-policy",
-        "internal/contracts/src/errors",
-        "internal/contracts/src/json",
-        "internal/contracts/src/manifest",
-        "internal/contracts/src/manifest-file",
-        "internal/contracts/src/server",
-        "internal/contracts/src/triggers",
-        "internal/contracts/src/wire"
+        "packages/cortex-typescript"
     ]
 }

package/src/commands/apply.ts

@@ -13,8 +13,8 @@ import { loadManifestFile } from "@cortex/contracts/manifest-file";
 import { z } from "zod";
 
 import { callManagement, ManagementError } from "@/management/client";
-import { failCall, requireProfile } from "@/commands/management";
-import { askChoice } from "@/ui/prompts";
+import { callOrFail, confirmDestructive, requireProfile } from "@/commands/management";
+import { askChoice, canAsk } from "@/ui/prompts";
 import * as report from "@/ui/report";
 
 // Discovery is this exact name in the cwd, with no upward walk, so the
@@ -42,9 +42,11 @@ const MARKS = { create: "+", update: "~", delete: "-" } satisfies Record<
 /**
  * `cortex apply [path]`: makes Cortex match a manifest in one
  * transaction, through the management API with the profile's key.
- * `--dry-run` answers what would change and changes nothing. A field both
- * the manifest and a live edit in Cortex changed is asked about, unless
- * `--prefer` answers every one.
+ * `--dry-run` answers what would change and changes nothing; anything
+ * else asks first, since a sync deletes. A field both the manifest and a
+ * live edit in Cortex changed is asked about too, unless `--prefer` answers
+ * every one. `--yes` never asks: the sync goes ahead, and a conflict
+ * `--prefer` leaves open ends the run.
  */
 export function registerApply(program: Command<[], { verbose?: true; profile?: string }>) {
     const command = program
@@ -53,6 +55,10 @@ export function registerApply(program: Command<[], { verbose?: true; profile?: s
         .description("Make Cortex match a manifest")
         .argument("[path]", "The manifest, TypeScript or JSON", DEFAULT_MANIFEST)
         .option("--dry-run", "Show what would change, and change nothing")
+        .option(
+            "--yes",
+            "Never ask: apply without confirming, and stop on conflicts --prefer leaves open",
+        )
         .addOption(
             new Option(
                 "--prefer <side>",
@@ -63,21 +69,35 @@ export function registerApply(program: Command<[], { verbose?: true; profile?: s
     command.action(async function (path, options) {
         const { verbose = false, profile: profileName } = program.opts();
         const dryRun = options.dryRun === true;
-        const file = findManifest(path);
+        const file = findManifest(path, "cortex apply");
         const profile = requireProfile(profileName);
 
         report.header(dryRun ? "cortex apply --dry-run" : "cortex apply");
+        const manifest = await loadManifest(file, verbose);
         report.input("Manifest", label(file));
         report.input("Cortex", profile.url);
+        if (!dryRun) {
+            await confirmDestructive(
+                `Applying deletes what the manifest created on ${profile.url} and no longer lists.`,
+                options.yes,
+            );
+        }
 
-        const { changes, triggerSecrets, conflicts } = await applyManifest({
-            profile,
-            file,
-            dryRun,
-            verbose,
-            prefer: options.prefer,
-            interactive: process.stdin.isTTY === true,
-        });
+        const { changes, triggerSecrets, conflicts } = await callOrFail(profile, () =>
+            applyManifest({
+                profile,
+                manifest,
+                dryRun,
+                prefer: options.prefer,
+                interactive: canAsk() && options.yes !== true,
+                // A run that does not ask confirmed its sync with --yes.
+                command: [
+                    "cortex apply",
+                    ...(label(file) === DEFAULT_MANIFEST ? [] : [label(file)]),
+                    "--yes",
+                ].join(" "),
+            }),
+        );
         const created = countNames(changes.create);
         const updated = countNames(changes.update);
         const deleted = countNames(changes.delete);
@@ -97,28 +117,26 @@ export function registerApply(program: Command<[], { verbose?: true; profile?: s
 }
 
 /**
- * Loads the manifest at `file` and sends it, a preview under `dryRun`, then
- * prints its changes one row per entry, and a preview's conflicts. Ends the
- * run on an invalid file, a refusal, or a summary this CLI cannot read.
- * `cortex apply` and `cortex setup` both apply through it; each prints the
- * trigger secrets it returns.
+ * Sends a manifest `loadManifest` read, a preview under `dryRun`, then
+ * prints its changes one row per entry, and a preview's conflicts. A sync
+ * deletes what the manifest created and no longer lists, so its caller
+ * confirms first (`confirmDestructive`). Ends the run on a summary this CLI
+ * cannot read; a refusal throws, for the caller to end the run on
+ * (`callOrFail`) or to answer itself. `cortex apply` and `cortex setup` both
+ * apply through it; each prints the trigger secrets it returns.
  */
 export async function applyManifest(options: {
     profile: ReturnType<typeof requireProfile>;
-    file: string;
+    manifest: Record<string, unknown>;
     dryRun: boolean;
-    verbose: boolean;
     prefer?: Side;
     interactive: boolean;
+    /** What to run again to answer the conflicts it could not ask about. */
+    command: string;
 }) {
-    const { profile, file, dryRun, verbose } = options;
+    const { profile, dryRun } = options;
     const answer = await sendManifest({
         ...options,
-        // What to run again: `cortex apply`, with the path unless it is the default.
-        command: ["cortex apply", ...(label(file) === DEFAULT_MANIFEST ? [] : [label(file)])].join(
-            " ",
-        ),
-        manifest: await loadManifest(file, verbose),
         path: dryRun ? "/manifests/preview" : "/manifests/sync",
     });
     // The secrets are read apart from the changes: a sync has committed by
@@ -146,8 +164,8 @@ export async function applyManifest(options: {
 /**
  * Sends the manifest until nothing in it is left unanswered. A sync refused
  * for fields both the manifest and a live edit changed asks about each one
- * when it can, then goes again with the answers; one that cannot ask ends
- * the run naming them. Any other refusal ends the run as well.
+ * when `interactive`, then goes again with the answers; otherwise it ends
+ * the run naming them. Any other refusal throws.
  */
 async function sendManifest(options: {
     profile: ReturnType<typeof requireProfile>;
@@ -171,7 +189,7 @@ async function sendManifest(options: {
                 error instanceof ManagementError
                     ? unresolvedSchema.safeParse(error.detail)
                     : undefined;
-            if (!refused?.success) return failCall(profile, error);
+            if (!refused?.success) throw error;
             if (!interactive) failUnresolved(refused.data.conflicts, command);
             for (const conflict of refused.data.conflicts) {
                 const keep = await askChoice<Side>(`${conflictLabel(conflict)}. Keep which?`, [
@@ -189,14 +207,14 @@ function conflictLabel({ kind, name, field }: Conflict) {
     return `${kind} ${name}: ${field} changed in both places`;
 }
 
-/** Ends a run that cannot ask, naming every conflict and how to run `command` again to answer them. */
+/** Ends a run that does not ask, naming every conflict and how to run `command` again to answer them. */
 function failUnresolved(conflicts: ReadonlyArray<Conflict>, command: string): never {
     const count = conflicts.length;
     return report.fail({
         what: `${count} field${count === 1 ? "" : "s"} changed both in Cortex and in the manifest`,
         blocks: [
             conflicts.map((conflict) => `  ${conflictLabel(conflict)}`).join("\n"),
-            "Keep one side for all of them, or run in a terminal to choose each:",
+            "Keep one side for all of them, or run in a terminal without --yes to choose each:",
             `  ${command} --prefer live\n  ${command} --prefer manifest`,
         ],
     });
@@ -208,8 +226,12 @@ function label(path: string) {
     return relativePath.startsWith(".") ? relativePath : `./${relativePath}`;
 }
 
-/** The manifest's absolute path; a missing file ends the run before anything prints. */
-export function findManifest(path: string) {
+/**
+ * The manifest's absolute path; a missing file ends the run before anything
+ * prints. `command`, when the command also takes a path, is offered as the
+ * way to point at a manifest elsewhere.
+ */
+export function findManifest(path: string, command?: string) {
     const absolute = resolve(process.cwd(), path);
     if (existsSync(absolute)) return absolute;
     return report.fail({
@@ -217,9 +239,10 @@ export function findManifest(path: string) {
         blocks:
             path === DEFAULT_MANIFEST
                 ? [
-                      "cortex apply reads exactly ./cortex.manifest.ts in the directory you run in.\nIt does not search parent directories.",
-                      "Run it from the project root, or point at the file:",
-                      "  cortex apply ./deploy/cortex.manifest.ts",
+                      "The CLI reads exactly ./cortex.manifest.ts in the directory you run in.\nIt does not search parent directories.",
+                      command
+                          ? `Run it from the project root, or point at the file:\n  ${command} ./deploy/cortex.manifest.ts`
+                          : "Run it from the project root.",
                   ]
                 : ["The path is resolved from the directory you run in."],
     });
@@ -230,7 +253,7 @@ export function findManifest(path: string) {
  * a mistake is named before anything is sent, then sent as written: Cortex
  * fills its own defaults, which may be newer than this CLI's.
  */
-async function loadManifest(path: string, verbose: boolean) {
+export async function loadManifest(path: string, verbose: boolean) {
     const { written, parsed } = await loadManifestFile(path).catch((error: unknown) =>
         report.fail({
             what: `Could not load ${label(path)}`,

package/src/commands/management.ts

@@ -88,18 +88,22 @@ export function registerManagement(program: Program, argv: string[]) {
 }
 
 /**
- * The key is never a flag (argv is visible to other processes and lands in
- * shell history): it is prompted for masked, or read from `CORTEX_KEY`
- * when there is no terminal to ask.
+ * The URL is `--url`, or asked for on a terminal. The key is never a flag
+ * (argv is visible to other processes and lands in shell history): it is
+ * prompted for masked, or read from `CORTEX_KEY` when there is no terminal
+ * to ask.
  */
 async function login(given: string | undefined, name: string) {
-    const url = requireTls(
-        (given ?? (await prompts.askValue("Cortex URL", "https://cortex.example.com"))).replace(
-            /\/+$/,
-            "",
-        ),
-    );
-    const key = process.stdin.isTTY
+    const typed =
+        given ??
+        (prompts.canAsk()
+            ? await prompts.askValue("Cortex URL", "https://cortex.example.com")
+            : report.fail({
+                  what: "No terminal to ask for the Cortex URL",
+                  blocks: ["Pass it with --url."],
+              }));
+    const url = requireTls(typed.replace(/\/+$/, ""));
+    const key = prompts.canAsk()
         ? await prompts.askSecret("Management key")
         : (process.env["CORTEX_KEY"] ??
           report.fail({
@@ -248,7 +252,8 @@ function groupByRouter(document: OpenApiDocument) {
 /**
  * One procedure as one command: a positional for `id`, a typed flag per
  * field, `--json` for a whole body, `--all` on paginated reads, `--publish`
- * on writes to a publishable router.
+ * on writes to a publishable router, `--yes` wherever a destructive
+ * procedure (`x-destructive`) would run.
  */
 function registerOperation(scope: {
     group: Command;
@@ -273,10 +278,13 @@ function registerOperation(scope: {
     const publisher = publishWith === undefined ? undefined : byProcedure.get(publishWith);
     const canPublish = publisher !== undefined;
     const liveFields = operation["x-live-fields"] ?? [];
+    const destructive = operation["x-destructive"] === true;
+    const publishDestructive = publisher?.operation["x-destructive"] === true;
 
     const command = declareCommand(group, name, operation.summary ?? "", flags, {
         paginated,
         canPublish,
+        confirms: destructive || publishDestructive,
     });
 
     command.action(async function (...args) {
@@ -285,11 +293,12 @@ function registerOperation(scope: {
             json?: string;
             all?: boolean;
             publish?: boolean;
+            yes?: boolean;
         };
         // Commander passes the options object first when the command declares
         // no argument, so only a string is the `[id]` positional.
         const positional = typeof args[0] === "string" ? args[0] : undefined;
-        const { output: format, json, all, publish, ...given } = options;
+        const { output: format, json, all, publish, yes, ...given } = options;
         const body = await collectInput(flags, given, json, positional, name);
         // `-o json` promises stdout holds only the result; prose moves to stderr.
         const note = format === "json" ? report.aside : report.note;
@@ -297,6 +306,20 @@ function registerOperation(scope: {
             report.header(`cortex ${router} ${name}`);
             report.input("Cortex", profile.url);
         }
+        // One question before anything is sent, covering the publish too, so
+        // a no leaves no draft behind.
+        const confirming = [
+            ...(destructive ? [`${router} ${name}`] : []),
+            ...(publish === true && publishDestructive
+                ? [publisher.operation.operationId.replace(".", " ")]
+                : []),
+        ];
+        if (confirming.length > 0) {
+            await confirmDestructive(
+                `Running ${confirming.join(" and ")} on ${profile.url} replaces or removes state.`,
+                yes,
+            );
+        }
         const result = await callOrFail(profile, () =>
             all
                 ? walkPages(profile, method, path, body)
@@ -320,7 +343,7 @@ function declareCommand(
     name: string,
     summary: string,
     flags: Flag[],
-    shape: { paginated: boolean; canPublish: boolean },
+    shape: { paginated: boolean; canPublish: boolean; confirms: boolean },
 ) {
     const command = group
         .command(name)
@@ -353,6 +376,8 @@ function declareCommand(
     }
     if (shape.paginated) command.option("--all", "Walk every page");
     if (shape.canPublish) command.option("--publish", "Publish the entity right after saving");
+    if (shape.confirms)
+        command.option("--yes", "Skip the confirmation; required without a terminal");
     return command;
 }
 
@@ -363,6 +388,22 @@ function warningsOf(published: unknown) {
         : [];
 }
 
+/**
+ * The go-ahead for a call that replaces or removes state, which `effect`
+ * names: `--yes`, or a yes on a terminal. With no terminal to ask, the run
+ * fails before anything is sent, so a script never hangs on the question.
+ * The hint does not echo argv, which may hold values that must not reach a
+ * CI log.
+ */
+export async function confirmDestructive(effect: string, yes: boolean | undefined) {
+    if (yes === true) return;
+    if (prompts.canAsk()) return prompts.askToProceed(`${effect} Continue?`);
+    report.fail({
+        what: "No terminal to confirm this call",
+        blocks: [effect, "Rerun the command with --yes to run it without asking."],
+    });
+}
+
 /**
  * A write to a publishable router is a draft: publish it now, or say how to.
  * Fields Cortex reads live are already in effect and are named as such,
@@ -408,14 +449,18 @@ export async function callOrFail<T>(profile: ResolvedProfile, call: () => Promis
 
 /**
  * A management refusal, or a Cortex that cannot be reached, is the
- * run's outcome, in the error grammar, with whatever the refusal names;
- * anything else is a bug, and rethrown.
+ * run's outcome, in the error grammar: the refusal's literal, the sentence
+ * Cortex words it in, then whatever it names; anything else is a bug, and
+ * rethrown.
  */
 export function failCall(profile: { url: string }, error: unknown): never {
     if (error instanceof ManagementError) {
         report.fail({
             what: `${error.status} ${error.code}: ${error.message}`,
-            blocks: refusalBlocks(error.detail ?? {}),
+            blocks: [
+                ...(error.refusal === undefined ? [] : [error.refusal]),
+                ...refusalBlocks(error.detail ?? {}),
+            ],
         });
     }
     if (error instanceof UnreachableError) {
@@ -459,8 +504,8 @@ function issueLine(issue: unknown) {
 
 /**
  * The body: `--json` first, flags layered over it, the positional as `id`.
- * A required field left missing is asked for on a TTY and named as the
- * flag, or the positional, to add otherwise.
+ * A required field left missing is asked for on a terminal and named as
+ * the flag, or the positional, to add otherwise.
  */
 async function collectInput(
     flags: Flag[],
@@ -476,7 +521,7 @@ async function collectInput(
     if (positional !== undefined) body.set("id", positional);
 
     const missing = flags.filter((flag) => flag.required && body.get(flag.name) === undefined);
-    if (missing.length > 0 && !process.stdin.isTTY) {
+    if (missing.length > 0 && !prompts.canAsk()) {
         const named = (flag: Flag) =>
             flag.name === "id"
                 ? "<id>"

package/src/commands/new.ts

@@ -9,7 +9,7 @@ import pkg from "../../package.json";
 import { askProvider } from "@/commands/setup";
 import { AGENT_SLUG, manifestIdOf, scaffoldFiles } from "@/scaffold/files";
 import { allocatePorts, type Ports } from "@/scaffold/ports";
-import { askConfirm, askName, intro, log, outro, runSteps } from "@/ui/prompts";
+import { askConfirm, askName, canAsk, intro, log, outro, runSteps } from "@/ui/prompts";
 import * as report from "@/ui/report";
 
 /** npm's rule for an unscoped package name. The name is the directory too. */
@@ -46,9 +46,8 @@ type Options = { datasets?: true; setup?: boolean; yes?: true; verbose: boolean
 async function scaffold(name: string | undefined, options: Options) {
     const { verbose } = 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`.
-    const interactive = process.stdin.isTTY === true && options.yes !== true;
+    // No terminal ⇒ never prompt and behave as `--yes`.
+    const interactive = canAsk() && options.yes !== true;
 
     if (name === undefined && !interactive) missingName();
 
@@ -280,14 +279,13 @@ 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
+    // No terminal ⇒ never prompt, so a missing required argument is a hard error.
+    // With one, 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
-                ? "cortex new needs a project name."
-                : "cortex new needs a project name when stdin is not a TTY.",
+        what: canAsk()
+            ? "cortex new needs a project name."
+            : "cortex new needs a project name when there is no terminal to ask on.",
         blocks: [
             "Pass it as an argument, and --yes to accept defaults for the rest:",
             "  cortex new my-app --yes",