@isomorph.ai/cli 0.3.4 → 0.4.0-rc.1

package/dist/packages/harbour-cli/src/cli.js

@@ -1,99 +1,72 @@
 #!/usr/bin/env node
 import { RemoteMcpClient } from "./remote-mcp-client.js";
-import { appCallsAi, productionise, SAVE_APPROVAL } from "./productionise.js";
-import { confirmAudience, confirmProfile, continueCommand, dismissSecret, fetchStatus, follow, getAppSetup, listSecrets, promoteToProduction, PROMOTION_CONFIRMATION, readSecretFromStdin, readSecretFromTerminal, retryDeployment, setSecret, summarize } from "./operations.js";
+import { appCallsAi, deploy } from "./deploy.js";
+import { continueCommand, fetchStatus, follow, promoteToProduction, retryDeployment, summarize } from "./operations.js";
 import { CliError, failureEnvelope, operationEnvelope, renderFailure, renderSummary } from "./output.js";
 import { CLI_VERSION } from "./version.js";
 import { connectedAccount, login, logout, refreshStoredToken } from "./auth.js";
-import { companyLabel, connect, loadConfig, resolveConfig } from "./config.js";
+import { assertCliCurrent, companyLabel, connect, loadConfig, resolveConfig } from "./config.js";
 import { EMBEDDED_KIT_BUNDLE } from "./kit-bundle.js";
-import { appRoot, assertKitCurrent, readKitLock, requestResourceName } from "./kit.js";
+import { appRoot, requestResourceName } from "./kit.js";
 import { initKit } from "./starter.js";
-import { agentPaths, agentSetup, cliVersionLines } from "./agent-setup.js";
-import { startDev } from "./dev.js";
+import { agentPaths, agentSetup } from "./agent-setup.js";
+import { detachDev, startDev } from "./dev.js";
 import { ensureSdk, LocalRuntime, readDevLock, releaseDevLock, runCommand } from "./local-runtime.js";
 import { CHECKS_FAILED_HINT, checksFailedMessage, runChecks } from "./check.js";
-import { assertAiReady, companySystemsLine, GovernanceClient, groupGrants, IDENTITY_WORDS, integrationsCatalog, integrationsStatus, renderGrantGroup, renderIntegrationsCatalog, requestIntegrations } from "./integrations.js";
+import { assertDeployReady, companySystemsLine, GovernanceClient, groupGrants, IDENTITY_WORDS, integrationsCatalog, integrationsStatus, renderGrantGroup, renderIntegrationsCatalog, requestIntegrations } from "./integrations.js";
 import { runJob } from "./jobs.js";
 const args = process.argv.slice(2);
-const command = args[0];
+// `productionise` was the command's name until 0.3.4: it is accepted for one release, unlisted, and behaves exactly as `deploy`.
+const command = args[0] === "productionise" ? "deploy" : args[0];
 const connectUrl = args[1];
 const root = optionValue("--app-root");
 const operationRef = optionValue("--operation");
 const json = args.includes("--json");
 const noWait = args.includes("--no-wait");
-const secretName = optionValue("--name");
-const profileName = optionValue("--name");
-const profileDescription = optionValue("--description");
-const audienceEmails = optionValue("--emails");
 const sessionNotes = optionValue("--session-notes");
-const personal = args.includes("--personal");
-const valueStdin = args.includes("--value-stdin");
-/** The reply the save and promote prompts would otherwise wait to have typed, for a caller with no terminal. */
-const confirmSave = args.includes("--confirm-save");
+/** The one flag that means "the person tried the preview"; `promote` never prompts for it. */
 const confirmTested = args.includes("--confirm-tested");
 const subcommand = args[1] && !args[1].startsWith("--") ? args[1] : undefined;
 const wait = args.includes("--wait");
 const reset = args.includes("--reset");
+/** `dev --detach`: start the services, print the origin, exit while they keep running. */
+const detach = args.includes("--detach");
 const upgrade = args.includes("--upgrade");
 const testIntegrations = args.includes("--integrations");
 const reason = optionValue("--reason");
 const operations = optionValue("--operations");
 const scheduledAt = optionValue("--scheduled-at");
 const realJob = args.includes("--real");
-/** Seconds `productionise`, `status --wait`, `retry` and `promote` follow the operation before reporting it as still running (default: 30 minutes). */
+/** Seconds `deploy`, `status --wait`, `retry` and `promote` follow the operation before reporting it as still running (default: 30 minutes). */
 const maxWaitSeconds = args.includes("--max-wait") ? Number(optionValue("--max-wait")) : undefined;
 const waitOptions = maxWaitSeconds ? { maxWaitMs: maxWaitSeconds * 1000 } : {};
-const includePaths = [];
 let optionError;
 if (maxWaitSeconds !== undefined && !(Number.isInteger(maxWaitSeconds) && maxWaitSeconds > 0))
     optionError = "--max-wait takes a whole number of seconds.";
-if (command === "productionise" && ((profileName && !profileDescription) || (!profileName && profileDescription) || (audienceEmails && (!profileName || !profileDescription))))
-    optionError = "Productionise takes --name and --description together; --emails may be added only with both.";
-for (let index = 0; index < args.length; index += 1) {
-    if (args[index] === "--include") {
-        const value = args[index + 1];
-        if (!value || value.startsWith("--")) {
-            optionError = "--include requires a relative file or directory path.";
-            break;
-        }
-        includePaths.push(value);
-        index += 1;
-    }
-}
 const explicitToken = process.env.ISOMORPH_TOKEN?.trim() ?? "";
 const usage = [
     "Usage:",
     "  isomorph connect <work-email | company-start-url>",
     "  isomorph login | logout",
-    "  isomorph productionise --app-root <path> [--include <relative-path>]... [--name <text> --description <text> [--emails a@co,b@co]] [--session-notes <text>] [--confirm-save] [--no-wait] [--max-wait <seconds>] [--json]",
-    "  isomorph status --operation <reference> [--wait] [--max-wait <seconds>] [--json]",
-    "  isomorph retry --operation <reference> [--no-wait] [--max-wait <seconds>] [--json]",
-    "  isomorph promote --operation <reference> [--app-root <path>] [--confirm-tested] [--no-wait] [--max-wait <seconds>] [--json]   (--app-root: also confirm the company's AI setup for production when the app calls governed AI)",
-    "  isomorph setup --operation <reference> [--json]            what the app still needs (name, audience, secrets)",
-    "  isomorph profile --operation <reference> [--name <text>] [--description <text>] [--json]",
-    "  isomorph audience --operation <reference> [--emails a@co,b@co] [--json]   (no --emails = only you)",
-    "  isomorph secrets list --operation <reference> [--json]",
-    "  isomorph secrets set --operation <reference> --name <NAME> [--personal] [--value-stdin]",
-    "  isomorph secrets dismiss --operation <reference> --name <NAME>",
     "  isomorph agent-setup [--json]                               install the plain-English Isomorph skill for Claude Code (~/.claude/skills/isomorph) and Codex (~/.codex/skills/isomorph)",
-    "  isomorph init --app-root <path> [--upgrade]                 create the starter or add the kit files; --upgrade re-pins the kit bundle and moves an app set up by an older CLI to this kit (also runs agent-setup)",
-    "  isomorph dev --app-root <path> [--reset]                    run the app locally on one loopback origin (--reset deletes this app's local data)",
+    "  isomorph init --app-root <path> [--upgrade]                 create the starter or add the kit files (also runs agent-setup); --upgrade re-pins the kit bundle and runs the checks",
+    "  isomorph dev --app-root <path> [--reset] [--detach] [--json]  run the app locally on one loopback origin (--reset deletes this app's local data; --detach starts it in the background and prints the origin and pid once it answers)",
     "  isomorph stop --app-root <path>                             stop this app's local services, keeping its database and files",
     "  isomorph check --app-root <path> [--integrations] [--json]  types, build, then the pipeline's kit gate in the local session: declaration, migrations + database gate, write probe with cross-user denial, journeys, operation coverage (+ authorised real reads)",
+    "  isomorph deploy --app-root <path> [--session-notes <text>] [--no-wait] [--max-wait <seconds>] [--json]   deploy the private preview: name, description and audience come from .isomorph/app.json",
+    "  isomorph status --operation <reference> [--wait] [--max-wait <seconds>] [--json]",
+    "  isomorph retry --operation <reference> [--no-wait] [--max-wait <seconds>] [--json]",
+    "  isomorph promote --operation <reference> [--app-root <path>] [--confirm-tested] [--no-wait] [--max-wait <seconds>] [--json]   (--confirm-tested: the person has tried the preview; --app-root: also confirm the company's AI setup for production when the app calls governed AI)",
     "  isomorph jobs run <name> --app-root <path> [--scheduled-at <UTC>] [--real] [--json]  run one scheduled job now (local fixtures; --real uses approved company access)",
-    "  isomorph integrations request <connection> --app-root <path> [--reason <text>] [--operations a,b] [--json]   one request per connection, for every environment at once: IT approves it once (isomorph dev and productionise file it for you)",
+    "  isomorph integrations request <connection> --app-root <path> [--reason <text>] [--operations a,b] [--json]   one request per connection, for every environment at once: IT approves it once (isomorph dev and deploy file it for you)",
     "  isomorph integrations status --app-root <path> [--json]",
     "  isomorph integrations catalog --app-root <path> [--json]   the company's connections as .isomorph/integrations.json names them: identifiers, allowed operations, approved channels/tables/views/mailboxes per environment (no app needed)",
     "Run `isomorph connect <work-email>` once; sign in with `isomorph login` when Isomorph asks.",
-    "productionise saves the app, follows its deployment, and prints the protected preview link; promote sends a tested preview to production.",
-    "productionise stops for a typed `Approved.` before it copies the app files to the company code system, and promote for a typed `Tested.` before it releases the preview. --confirm-save and --confirm-tested give that same reply on the command line when nobody can type it; the approval recorded is the one made by whoever ran the command.",
-    `--max-wait bounds how long productionise, status --wait, retry and promote follow the deployment (default 30 minutes). When it passes the command exits 0 with status RUNNING, the last known deployment state, and the \`${continueCommand("<reference>")}\` that continues the same deployment: a bounded wait is not a failure and never means start another one.`,
-    "For kit apps, productionise first files the access request for every connection in .isomorph/integrations.json (one per connection; IT approves it once for every environment) and exits 2 (INTEGRATIONS_NOT_READY) naming what IT still has to approve, asks governance whether the company's AI setup is ready when the app calls governed AI (exit 2, AI_NOT_READY, with the IT step), then runs the pipeline's kit gate in the local session and refuses (KIT_GATE_FAILED) what CodeBuild would refuse. promote asks the same AI question for production when --app-root names the app.",
-    "secrets set reads the value from your terminal with echo off (or from stdin with --value-stdin); it is never printed or passed to any other program.",
+    "deploy runs the checks when they have not passed for this exact code, then asks Isomorph once whether the app can deploy (the access request for every connection in .isomorph/integrations.json, which IT approves once for every environment; the company's AI setup when the app calls governed AI; this CLI's version) and refuses with exit 2 naming every blocker and its fix; then it saves the app, follows its deployment and prints the protected preview link. promote sends a tested preview to production after the same question for production.",
+    `--max-wait bounds how long deploy, status --wait, retry and promote follow the deployment (default 30 minutes). When it passes the command exits 0 with status RUNNING, the last known deployment state, and the \`${continueCommand("<reference>")}\` that continues the same deployment: a bounded wait is not a failure and never means start another one.`,
     ""
 ].join("\n");
-const OPERATION_COMMANDS = ["status", "retry", "promote", "setup", "profile", "audience", "secrets"];
+const OPERATION_COMMANDS = ["status", "retry", "promote"];
 const LOCAL_COMMANDS = ["init", "dev", "stop", "check", "jobs"];
 const progress = (message) => { process.stderr.write(`${message}\n`); };
 /** Envelope for commands that start no Isomorph operation (local kit commands, integrations). */
@@ -109,11 +82,11 @@ const emit = (value, line) => { process.stdout.write(json ? `${JSON.stringify(va
  */
 const exitAfterWriting = (code, out, err = "") => { process.stderr.write(err, () => process.stdout.write(out, () => process.exit(code))); };
 /** Exit 2, like a usage error: nothing started and the fix is a command the maker runs. */
-const USAGE_REFUSALS = ["INTEGRATIONS_NOT_READY", "AI_NOT_READY", "NOT_A_MEMBER", "TENANT_AMBIGUOUS", "NOT_A_START_LINK", "PLATFORM_UNREACHABLE"];
+const USAGE_REFUSALS = ["DEPLOY_BLOCKED", "INTEGRATIONS_NOT_READY", "AI_NOT_READY", "CLI_UPGRADE_REQUIRED", "NOT_A_MEMBER", "TENANT_AMBIGUOUS", "NOT_A_START_LINK", "PLATFORM_UNREACHABLE"];
 if (command === "--version" || command === "version") {
     process.stdout.write(`${CLI_VERSION}\n`);
     // `-h` was matched anywhere in argv while `--help` was only recognised as the
-    // first token, so `isomorph productionise --help` fell through to argument
+    // first token, so `isomorph deploy --help` fell through to argument
     // validation and exited 2 with the usage block as an error. Both spellings now
     // mean the same thing wherever they appear.
 }
@@ -128,22 +101,16 @@ else if (command === "agent-setup") {
     if (result.removed.length)
         progress("The guide is no longer in your global Codex instructions, where every session read it; Codex now has it as a skill, like Claude Code.");
     progress("Claude Code and Codex: the `isomorph` skill is installed. Each agent uses it only for an Isomorph app (a folder with .isomorph/, or an app you ask it to build) and works as usual everywhere else. Say what you want to build; the agent installs and runs the kit itself.");
-    // Which `isomorph` the next command will run. This command is usually reached through
-    // `npx …@stable`, which tells you nothing about the CLI that does the actual work.
-    if (result.cli)
-        for (const line of cliVersionLines(result.cli))
-            progress(line);
     emit(summaryEnvelope({ ...result, paths: agentPaths(process.env) }));
 }
-else if (!["connect", "login", "logout", "productionise", "integrations", ...LOCAL_COMMANDS, ...OPERATION_COMMANDS].includes(command)
+else if (!["connect", "login", "logout", "deploy", "integrations", ...LOCAL_COMMANDS, ...OPERATION_COMMANDS].includes(command)
     || (command === "connect" && (!connectUrl || connectUrl.startsWith("--")))
-    || (["productionise", "status", "retry", "promote"].includes(command) && optionError)
-    || (command === "productionise" && !root)
+    || (["deploy", "status", "retry", "promote"].includes(command) && optionError)
+    || (command === "deploy" && !root)
     || (LOCAL_COMMANDS.includes(command) && !root)
     || (command === "jobs" && (subcommand !== "run" || !args[2] || args[2].startsWith("--")))
     || (command === "integrations" && (!root || !subcommand || !["request", "status", "catalog"].includes(subcommand) || (subcommand === "request" && (!args[2] || args[2].startsWith("--")))))
-    || (OPERATION_COMMANDS.includes(command) && !operationRef)
-    || (command === "secrets" && (!subcommand || !["list", "set", "dismiss"].includes(subcommand) || (subcommand !== "list" && !secretName)))) {
+    || (OPERATION_COMMANDS.includes(command) && !operationRef)) {
     exitAfterWriting(2, "", `${optionError ? `${optionError}\n` : ""}${usage}`);
 }
 else {
@@ -156,20 +123,12 @@ else {
             // Local commands run before the company config/login requirement: the base app needs neither.
             const bundle = EMBEDDED_KIT_BUNDLE;
             const target = appRoot(root);
-            // `init --upgrade` is the one command that moves an app from the old kit layout (initKit decides); every other one refuses it.
-            if (command !== "init")
-                await assertKitCurrent(target);
             const config = resolveConfig(process.env, await loadConfig());
             const companyToken = async () => config ? (explicitToken || await refreshStoredToken(config.mcpUrl, config.tenantId)) : undefined;
             if (command === "init") {
                 const result = await initKit(target, bundle, { upgrade, tenantId: config?.tenantId, env: process.env });
                 for (const line of [...result.created.map(path => `created ${path}`), ...result.updated.map(path => `updated ${path}`), ...result.kept.map(path => `kept    ${path}`), ...result.bundleChanges.map(change => `bundle  ${change}`), ...["created", "updated"].flatMap(state => result.agents[state].map(path => `${state} ${path} (agent guide)`))])
                     progress(line);
-                // Silent while the installed CLI is current; loud when `init` came from a
-                // newer package than the CLI that will run `dev`, `check` and `productionise`.
-                if (result.agents.cli?.upgradeRequired)
-                    for (const line of cliVersionLines(result.agents.cli))
-                        progress(line);
                 // The SDK is not on the public registry: init installs the pinned tarball (and the app's other dependencies) itself.
                 const sdk = await ensureSdk(target, bundle, process.env, runCommand, progress);
                 if (sdk === "missing")
@@ -209,7 +168,7 @@ else {
                 if (!report.passed) {
                     const message = checksFailedMessage(report);
                     exitAfterWriting(1, json
-                        ? `${JSON.stringify({ ...summaryEnvelope(report), status: "FAILED", error: { code: "CHECKS_FAILED", message, remediationHint: CHECKS_FAILED_HINT } })}\n`
+                        ? `${JSON.stringify({ ...summaryEnvelope(report), status: "FAILED", error: { code: "CHECKS_FAILED", layer: "gate", message, remediationHint: CHECKS_FAILED_HINT, paths: report.checks.filter(check => check.status === "fail").map(check => check.name) } })}\n`
                         : `${message}\n${CHECKS_FAILED_HINT}\n`);
                 }
                 else
@@ -220,6 +179,10 @@ else {
                 progress(`Job ${result.name} completed for ${result.scheduledAt}.`);
                 emit(summaryEnvelope(result));
             }
+            else if (detach) {
+                const started = await detachDev(target, { output: progress, reset });
+                emit(summaryEnvelope(started), `Isomorph dev is running: ${started.origin} (pid ${started.pid}). \`isomorph stop --app-root .\` stops it.\n`);
+            }
             else {
                 const started = await startDev(target, { bundle, output: progress, reset, company: config ? { apiUrl: config.apiUrl, tenantId: config.tenantId, accessToken: companyToken, account: token => connectedAccount(config.mcpUrl, config.tenantId, token) } : undefined });
                 let stopping = false;
@@ -234,6 +197,9 @@ else {
             const config = resolveConfig(process.env, await loadConfig());
             if (!config)
                 throw new CliError("CONFIG_REQUIRED", "Connect Isomorph first with `isomorph connect <work-email>`.");
+            // Before any network call: a CLI the company's platform no longer accepts is refused
+            // here, in under a second, with the install command, instead of by the pipeline.
+            assertCliCurrent(config);
             const url = config.mcpUrl;
             const tenant = config.tenantId;
             if (command === "login") {
@@ -256,7 +222,6 @@ else {
                 let envelope;
                 if (command === "integrations") {
                     const target = appRoot(root);
-                    await assertKitCurrent(target);
                     const governance = new GovernanceClient(config.apiUrl, token, tenant);
                     const result = subcommand === "status"
                         ? await integrationsStatus(target, governance)
@@ -267,13 +232,9 @@ else {
                     if (!json)
                         progress(subcommand === "status" ? renderIntegrationsStatus(result) : subcommand === "catalog" ? renderIntegrationsCatalog(result) : renderRequest(result));
                 }
-                else if (command === "productionise") {
-                    // Kit apps: the access requests are filed and the preview lane checked (and the app linked) before any operation starts, so productionise never mints a second app for the same root.
-                    const confirmedAppSetup = profileName && profileDescription
-                        ? { displayName: profileName, description: profileDescription, audienceEmails: audienceEmails ? audienceEmails.split(",").map(value => value.trim()).filter(Boolean) : [] }
-                        : undefined;
-                    await assertKitCurrent(appRoot(root));
-                    const result = await productionise(root, client, progress, tenant, includePaths, { waitForDeployment: !noWait, waitOptions, integrations: { governance: new GovernanceClient(config.apiUrl, token, tenant), bundle: EMBEDDED_KIT_BUNDLE }, ...(confirmSave ? { readApproval: async () => SAVE_APPROVAL } : {}), ...(confirmedAppSetup ? { confirmedAppSetup } : {}), ...(sessionNotes ? { sessionNotes } : {}) });
+                else if (command === "deploy") {
+                    // The access requests are filed and the preview lane checked (and the app linked) before any operation starts, so deploy never mints a second app for the same root.
+                    const result = await deploy(root, client, progress, tenant, { waitForDeployment: !noWait, waitOptions, integrations: { governance: new GovernanceClient(config.apiUrl, token, tenant), bundle: EMBEDDED_KIT_BUNDLE }, ...(sessionNotes ? { sessionNotes } : {}) });
                     envelope = operationEnvelope(result.result, result.operationRef, CLI_VERSION);
                 }
                 else {
@@ -282,27 +243,12 @@ else {
                         summary = wait ? await follow(client, operationRef, progress, waitOptions) : summarize(await fetchStatus(client, operationRef));
                     else if (command === "retry")
                         summary = await retryDeployment(client, operationRef, progress, { wait: !noWait, waitOptions });
-                    else if (command === "promote") {
-                        // The production PLAN blocks on the same AI setup plus enforce mode; with the app root in hand, ask before promoting.
-                        if (root && config.apiUrl && await appCallsAi(appRoot(root))) {
-                            const lock = await readKitLock(appRoot(root));
-                            if (lock?.appId)
-                                await assertAiReady(lock.appId, "production", new GovernanceClient(config.apiUrl, token, tenant), progress);
-                        }
-                        summary = await promoteToProduction(client, operationRef, progress, { wait: !noWait, waitOptions, ...(confirmTested ? { readConfirmation: async () => PROMOTION_CONFIRMATION } : {}) });
+                    else {
+                        // Production has its own lane and its own AI mode: with the app root in hand, the same one-call pre-flight runs for production before promoting.
+                        if (root)
+                            await assertDeployReady(appRoot(root), new GovernanceClient(config.apiUrl, token, tenant), tenant, EMBEDDED_KIT_BUNDLE, "production", progress, await appCallsAi(appRoot(root)));
+                        summary = await promoteToProduction(client, operationRef, progress, { wait: !noWait, waitOptions, confirmedTested: confirmTested });
                     }
-                    else if (command === "setup")
-                        summary = { setup: await getAppSetup(client, operationRef) };
-                    else if (command === "profile")
-                        summary = { setup: await confirmProfile(client, operationRef, { ...(profileName ? { displayName: profileName } : {}), ...(profileDescription ? { description: profileDescription } : {}) }, progress) };
-                    else if (command === "audience")
-                        summary = { setup: await confirmAudience(client, operationRef, audienceEmails ? audienceEmails.split(",").map(value => value.trim()).filter(Boolean) : [], progress) };
-                    else if (subcommand === "list")
-                        summary = { secrets: await listSecrets(client, operationRef) };
-                    else if (subcommand === "set")
-                        summary = await setSecret(client, operationRef, { name: secretName, ...(personal ? { personal: true } : {}), readValue: valueStdin ? readSecretFromStdin : () => readSecretFromTerminal(`Value for ${secretName} (not shown): `) }, progress);
-                    else
-                        summary = await dismissSecret(client, operationRef, secretName, progress);
                     envelope = operationEnvelope(summary, operationRef, CLI_VERSION);
                 }
                 process.stdout.write(json ? `${JSON.stringify(envelope)}\n` : renderSummary(envelope));
@@ -311,7 +257,7 @@ else {
     }
     catch (error) {
         const envelope = failureEnvelope(error, CLI_VERSION);
-        exitAfterWriting(USAGE_REFUSALS.includes(envelope.error?.code ?? "") ? 2 : 1, json || command === "productionise" ? `${JSON.stringify(envelope)}\n` : "", renderFailure(envelope));
+        exitAfterWriting(USAGE_REFUSALS.includes(envelope.error?.code ?? "") ? 2 : 1, json || command === "deploy" ? `${JSON.stringify(envelope)}\n` : "", renderFailure(envelope));
     }
 }
 /** One line per (connection, identity): the three lanes are one approval, so they are read together. */

package/dist/packages/harbour-cli/src/config.js

@@ -3,6 +3,46 @@ import { dirname, join } from "node:path";
 import { homedir } from "node:os";
 import { transportFailure } from "./integrations.js";
 import { CliError } from "./output.js";
+import { CLI_VERSION } from "./version.js";
+/**
+ * The one command that installs or upgrades the CLI. It carries no dist-tag: npm resolves an
+ * untagged name through `latest`, which is what a release publishes, so every instruction in
+ * the kit names the package the same way a person typing it from memory would (LLD §15.5).
+ */
+export const CLI_INSTALL_COMMAND = "npm i -g @isomorph.ai/cli";
+/**
+ * Refuses, in under a second and before any network call, a CLI older than the
+ * minimum the company's platform accepts. The platform knows that number (it is
+ * what `kit_bundle_incompatible` used to discover minutes into a pipeline run);
+ * `connect` stores it and every company command asks here first.
+ */
+export function assertCliCurrent(config, running = CLI_VERSION) {
+    const minimum = config.minimumCliVersion;
+    if (!minimum || compareCliVersions(running, minimum) >= 0)
+        return;
+    throw new CliError("CLI_UPGRADE_REQUIRED", `This CLI is ${running}; the company's Isomorph platform needs ${minimum} or newer.`, undefined, `Run \`${CLI_INSTALL_COMMAND}\`, then run this again.`);
+}
+/** Numeric-core semver order; a prerelease sorts before its release. An unparseable version compares equal, so nothing is called stale on a guess. */
+export function compareCliVersions(left, right) {
+    const parse = (value) => {
+        const match = /^\s*v?(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?/.exec(value);
+        return match ? { core: [Number(match[1]), Number(match[2]), Number(match[3])], pre: match[4] } : undefined;
+    };
+    const a = parse(left);
+    const b = parse(right);
+    if (!a || !b)
+        return 0;
+    for (let index = 0; index < 3; index += 1)
+        if (a.core[index] !== b.core[index])
+            return a.core[index] < b.core[index] ? -1 : 1;
+    if (a.pre === b.pre)
+        return 0;
+    if (a.pre === undefined)
+        return 1;
+    if (b.pre === undefined)
+        return -1;
+    return a.pre < b.pre ? -1 : 1;
+}
 export function configPath(env = process.env) {
     return join(env.XDG_CONFIG_HOME?.trim() || join(homedir(), ".config"), "isomorph", "config.json");
 }
@@ -59,19 +99,26 @@ export async function connect(startUrl, path = configPath(), fetchImpl = fetch)
         throw new CliError("PLATFORM_UNREACHABLE", `Isomorph answered ${response.status} instead of a company connection profile. Try again in a minute; if it keeps failing, Isomorph is down.`);
     if (body.schema !== "harbour.tenant-start/1.0")
         throw new Error("This is not an Isomorph connection profile.");
+    const minimum = minimumCliVersion(body);
     const config = {
         schema: "isomorph.cli-config/1.0",
         tenantId: String(body.tenantId ?? ""),
         ...(typeof body.displayName === "string" ? { displayName: body.displayName } : {}),
         mcpUrl: String(body.mcpUrl ?? ""),
         ...(typeof body.uploadUrl === "string" ? { uploadUrl: body.uploadUrl } : {}),
-        ...(typeof body.apiUrl === "string" ? { apiUrl: body.apiUrl } : {})
+        ...(typeof body.apiUrl === "string" ? { apiUrl: body.apiUrl } : {}),
+        ...(minimum ? { minimumCliVersion: minimum } : {})
     };
     if (!validConfig(config))
         throw new Error("This is not the expected Isomorph connection profile.");
     await saveConfig(config, path);
     return config;
 }
+/** `kit.minimumCliVersion` of a tenant-start profile; undefined on a profile that predates it. */
+function minimumCliVersion(body) {
+    const kit = isRecord(body.kit) ? body.kit : undefined;
+    return typeof kit?.minimumCliVersion === "string" && kit.minimumCliVersion.trim() ? kit.minimumCliVersion.trim() : undefined;
+}
 function platformOrigin() {
     return process.env.ISOMORPH_PLATFORM_URL?.trim() || "https://platform.isomorph.ai";
 }
@@ -105,7 +152,7 @@ export function resolveConfig(env, saved) {
     if (!mcpUrl || !tenantId)
         return undefined;
     // The saved name belongs to the saved tenant; an ISOMORPH_TENANT override names another company.
-    return { schema: "isomorph.cli-config/1.0", tenantId, ...(saved?.displayName && tenantId === saved.tenantId ? { displayName: saved.displayName } : {}), mcpUrl, ...(saved?.uploadUrl ? { uploadUrl: saved.uploadUrl } : {}), apiUrl: env.ISOMORPH_API_URL?.trim() || saved?.apiUrl || apiUrlFromMcpUrl(mcpUrl) };
+    return { schema: "isomorph.cli-config/1.0", tenantId, ...(saved?.displayName && tenantId === saved.tenantId ? { displayName: saved.displayName } : {}), mcpUrl, ...(saved?.uploadUrl ? { uploadUrl: saved.uploadUrl } : {}), apiUrl: env.ISOMORPH_API_URL?.trim() || saved?.apiUrl || apiUrlFromMcpUrl(mcpUrl), ...(saved?.minimumCliVersion && tenantId === saved.tenantId ? { minimumCliVersion: saved.minimumCliVersion } : {}) };
 }
 /** The company as the CLI names it: `Fourier (fourier)`, or the id twice when the profile carried no name. */
 export function companyLabel(config) {
@@ -127,7 +174,8 @@ function validConfig(value) {
         && typeof value.mcpUrl === "string"
         && /^https?:\/\//.test(value.mcpUrl)
         && (value.uploadUrl === undefined || typeof value.uploadUrl === "string")
-        && (value.apiUrl === undefined || (typeof value.apiUrl === "string" && /^https?:\/\//.test(value.apiUrl))));
+        && (value.apiUrl === undefined || (typeof value.apiUrl === "string" && /^https?:\/\//.test(value.apiUrl)))
+        && (value.minimumCliVersion === undefined || typeof value.minimumCliVersion === "string"));
 }
 function isRecord(value) {
     return Boolean(value && typeof value === "object" && !Array.isArray(value));