@m6d/cortex-cli 0.14.0 → 0.16.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,8 +127,8 @@ 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
@@ -132,6 +138,11 @@ next turn, and the command names them: a trigger's
 `url`, `credentials` 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,9 +153,17 @@ 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. `--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
 manifest. `defineManifest` from `@m6d/cortex` types one as you write it:
@@ -182,6 +201,8 @@ openapi: [
         name: "shop",
         url: "https://shop.example.com/openapi.json",
         credentials: [{ header: "Authorization", prefix: "Bearer ", credential: null }],
+        // 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"] },
@@ -207,12 +228,15 @@ 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
@@ -232,9 +256,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.14.0",
+    "version": "0.16.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

@@ -1,19 +1,38 @@
 import { existsSync } from "node:fs";
 import { relative, resolve } from "node:path";
 
+import { Option } from "@commander-js/extra-typings";
 import type { Command } from "@commander-js/extra-typings";
-import { appliedManifestSchema, manifestChangesSchema } from "@cortex/contracts/manifest";
+import { isRecord } from "@cortex/contracts/json";
+import {
+    appliedManifestSchema,
+    manifestApplyInputSchema,
+    manifestPreviewSchema,
+} from "@cortex/contracts/manifest";
 import { loadManifestFile } from "@cortex/contracts/manifest-file";
 import { z } from "zod";
 
-import { callManagement } from "@/management/client";
-import { callOrFail, requireProfile } from "@/commands/management";
+import { callManagement, ManagementError } from "@/management/client";
+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
 // argument's default is the discovery rule.
 export const DEFAULT_MANIFEST = "./cortex.manifest.ts";
 
+/** Which value a field both the manifest and a live write changed keeps. */
+const SIDES = manifestApplyInputSchema.shape.prefer.unwrap().options;
+type Side = (typeof SIDES)[number];
+type Resolution = z.input<typeof manifestApplyInputSchema>["resolutions"];
+type Conflict = z.infer<typeof manifestPreviewSchema>["conflicts"][number];
+
+/** A sync refused for fields both sides changed that nothing answered. */
+const unresolvedSchema = z.object({
+    error: z.literal("unresolved_conflicts"),
+    conflicts: manifestPreviewSchema.shape.conflicts,
+});
+
 const CHANGES = ["create", "update", "delete"] as const;
 const MARKS = { create: "+", update: "~", delete: "-" } satisfies Record<
     (typeof CHANGES)[number],
@@ -23,7 +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.
+ * `--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
@@ -31,27 +54,62 @@ export function registerApply(program: Command<[], { verbose?: true; profile?: s
         .helpGroup("Cortex:")
         .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("--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>",
+                "Keep the live or the manifest value of every field both changed, without asking",
+            ).choices(SIDES),
+        );
 
     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 } = await applyManifest({ profile, file, dryRun, verbose });
+        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);
+        const conflicted =
+            conflicts.length > 0
+                ? `, ${conflicts.length} conflict${conflicts.length === 1 ? "" : "s"}`
+                : "";
         report.footer(
-            created + updated + deleted === 0
+            created + updated + deleted + conflicts.length === 0
                 ? "no changes"
                 : dryRun
-                  ? `would create ${created}, update ${updated}, delete ${deleted}`
+                  ? `would create ${created}, update ${updated}, delete ${deleted}${conflicted}`
                   : `created ${created}, updated ${updated}, deleted ${deleted}`,
         );
         printTriggerSecrets(triggerSecrets);
@@ -59,34 +117,35 @@ 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. 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 manifest = await loadManifest(file, verbose);
-    const answer = await callOrFail(profile, () =>
-        callManagement(
-            profile,
-            "post",
-            dryRun ? "/manifests/preview" : "/manifests/sync",
-            manifest,
-        ),
-    );
+    const { profile, dryRun } = options;
+    const answer = await sendManifest({
+        ...options,
+        path: dryRun ? "/manifests/preview" : "/manifests/sync",
+    });
     // The secrets are read apart from the changes: a sync has committed by
     // now, and a summary this CLI is too old to read must not lose them.
     const { triggerSecrets = {} } = appliedManifestSchema
         .pick({ triggerSecrets: true })
         .partial()
         .parse(answer);
-    const applied = manifestChangesSchema.safeParse(answer);
+    const applied = manifestPreviewSchema.partial({ conflicts: true }).safeParse(answer);
     if (!applied.success) {
         printTriggerSecrets(triggerSecrets);
         report.fail({
@@ -97,8 +156,68 @@ export async function applyManifest(options: {
             ],
         });
     }
-    printChanges(applied.data);
-    return { changes: applied.data, triggerSecrets };
+    const { conflicts = [], ...changes } = applied.data;
+    printChanges(changes, conflicts);
+    return { changes, triggerSecrets, conflicts };
+}
+
+/**
+ * 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 `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>;
+    path: string;
+    command: string;
+    manifest: Record<string, unknown>;
+    prefer?: Side;
+    interactive: boolean;
+}) {
+    const { profile, path, command, manifest, prefer, interactive } = options;
+    const resolutions: Resolution = [];
+    for (;;) {
+        try {
+            return await callManagement(profile, "post", path, {
+                ...manifest,
+                prefer,
+                resolutions,
+            });
+        } catch (error) {
+            const refused =
+                error instanceof ManagementError
+                    ? unresolvedSchema.safeParse(error.detail)
+                    : undefined;
+            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?`, [
+                    { value: "live", label: "Keep live" },
+                    { value: "manifest", label: "Use manifest" },
+                ]);
+                resolutions.push({ ...conflict, keep });
+            }
+        }
+    }
+}
+
+/** How a conflict reads: its entry and the field both sides changed. */
+function conflictLabel({ kind, name, field }: Conflict) {
+    return `${kind} ${name}: ${field} changed in both places`;
+}
+
+/** 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 without --yes to choose each:",
+            `  ${command} --prefer live\n  ${command} --prefer manifest`,
+        ],
+    });
 }
 
 /** How a manifest path prints: relative to the cwd, `./`-prefixed. */
@@ -107,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({
@@ -116,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."],
     });
@@ -129,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)}`,
@@ -140,17 +264,23 @@ async function loadManifest(path: string, verbose: boolean) {
             verbose,
         }),
     );
-    if (!parsed.success) {
+    if (!parsed.success || !isRecord(written)) {
         report.fail({
             what: `${label(path)} is not a valid manifest`,
-            blocks: [z.prettifyError(parsed.error)],
+            blocks: parsed.success ? [] : [z.prettifyError(parsed.error)],
         });
     }
     return written;
 }
 
-/** One row per changed entry under its kind: `+` created, `~` updated, `-` deleted. */
-function printChanges(changes: Record<(typeof CHANGES)[number], Record<string, string[]>>) {
+/**
+ * One row per changed entry under its kind: `+` created, `~` updated, `-`
+ * deleted, and `!` a field both the manifest and a live edit changed.
+ */
+function printChanges(
+    changes: Record<(typeof CHANGES)[number], Record<string, string[]>>,
+    conflicts: ReadonlyArray<Conflict>,
+) {
     const rows = new Map<string, string[]>();
     for (const change of CHANGES) {
         for (const [kind, names] of Object.entries(changes[change])) {
@@ -158,6 +288,9 @@ function printChanges(changes: Record<(typeof CHANGES)[number], Record<string, s
             rows.set(kind, [...(rows.get(kind) ?? []), ...marked]);
         }
     }
+    for (const { kind, name, field } of conflicts) {
+        rows.set(kind, [...(rows.get(kind) ?? []), `! ${name}  ${field} changed in both places`]);
+    }
     for (const [kind, lines] of rows) {
         for (const [index, line] of lines.entries()) {
             report.row(index === 0 ? kind : "", line, 14);