@isomorph.ai/cli 0.2.0

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

@@ -0,0 +1,508 @@
+import { homedir } from "node:os";
+import { basename, dirname, parse, resolve } from "node:path";
+import { readdir, readFile, mkdir, rename, writeFile } from "node:fs/promises";
+import { scanWorkspace } from "../../../src/analyzer.js";
+import { createSourceManifest } from "../../../src/source-intake.js";
+import { structured } from "./remote-mcp-client.js";
+import { archiveForManifest, putMultipart } from "./upload.js";
+import { CliError } from "./output.js";
+import { confirmAudience, confirmProfile, follow, getAppSetup, pickSourceFailure, readLine, fetchStatus, outcomeFor } from "./operations.js";
+import { CLI_VERSION } from "./version.js";
+import { isProhibitedSecretPath } from "../../../src/secret-paths.js";
+import { assertAiReady, assertPreviewIntegrationsReady } from "./integrations.js";
+import { kitPaths, readKitLock, recordKitAppId, sourceDigest } from "./kit.js";
+import { FLOW_CHECK, preflightKitGate, readReport } from "./check.js";
+export async function productionise(rootArg, client, output, tenantId, includePaths = [], options = {}) {
+    const root = resolve(rootArg);
+    output(`Isomorph is checking ${basename(root)}.`);
+    if (root === parse(root).root || root === resolve(homedir()))
+        throw new CliError("PREFLIGHT_APP_ROOT", "The selected app boundary is unsafe.");
+    let pending = await readPending(root, tenantId, client.endpoint);
+    let prior;
+    if (pending) {
+        try {
+            prior = await fetchStatus(client, pending.operationRef);
+        }
+        catch (error) {
+            if (error instanceof CliError)
+                throw withOperation(error, pending.operationRef);
+            throw new CliError("OPERATION_STATUS_UNAVAILABLE", "Isomorph could not read the existing operation. Continue it when the connection recovers; do not start another deployment.", pending.operationRef);
+        }
+        if (prior.operation?.stage === "failed" && pending.sourceDigest === (await sourceDigest(root)).digest)
+            throw intakeRejection(prior, pending.operationRef);
+        if (operationFinished(prior) && pending.sourceDigest !== (await sourceDigest(root)).digest)
+            pending = undefined;
+    }
+    else {
+        const appId = options.appId ?? (await readKitLock(root))?.appId;
+        if (appId) {
+            await client.initialize();
+            const recovered = structured(await client.call("isomorph_get_operation_status", { appId }));
+            if (!recovered || !Object.hasOwn(recovered, "operation"))
+                throw new CliError("RECOVERY_UNAVAILABLE", "This company needs Isomorph's deployment recovery update before shipping. No new deployment was started.");
+            if (recovered.operation?.operationId && !operationFinished(recovered)) {
+                prior = recovered;
+                pending = { tenantId, endpoint: client.endpoint, operationRef: recovered.operation.operationId, sourceDigest: (await sourceDigest(root)).digest, uploaded: Boolean(recovered.sourceSave || recovered.deployment || recovered.waiting || recovered.operation.stage === "awaiting-approval"), graph: await scanWorkspace(root, { sourceBoundary: "root", ...(includePaths.length ? { includePaths } : {}) }), appId };
+                await writePending(root, pending);
+            }
+        }
+    }
+    if (pending && (prior?.deployment || prior?.production || prior?.waiting || operationFinished(prior))) {
+        output("Isomorph is continuing the existing operation; no new deployment was started.");
+        return finishDeployment(client, pending.operationRef, output, options);
+    }
+    if (pending && prior?.sourceSave)
+        pending.uploaded = true;
+    if (pending && !pending.uploaded && pending.sourceDigest !== (await sourceDigest(root)).digest) {
+        throw new CliError("UPLOAD_SOURCE_CHANGED", "The app changed before its upload finished. Restore the submitted files before continuing this operation.", pending.operationRef);
+    }
+    const graph = pending?.graph ?? await scanWorkspace(root, { sourceBoundary: "root", ...(includePaths.length ? { includePaths } : {}) });
+    if (!graph.deploymentScope.includedFiles.length)
+        throw new CliError("PREFLIGHT_EMPTY", "The selected app boundary contains no eligible files.");
+    if (graph.deploymentScope.includedFiles.some(isProhibitedSecretPath))
+        throw new CliError("PREFLIGHT_SECRET_PATH", "The selected app boundary contains a prohibited secret file.");
+    // The app's own retained checks are the cheapest gate Isomorph has and the
+    // most expensive one to discover in the cloud. Measured: a builder shipped
+    // without running `isomorph check`, the retained checks no longer matched the
+    // code, and the pipeline's `flow` gate refused it twice — 2m23s and 2m12s per
+    // discovery — for a mismatch `isomorph check` names locally in about five
+    // seconds. Refuse here, before the tree is even read into memory, and long
+    // before any grant lookup, database replay, operation or upload.
+    if (!pending?.uploaded)
+        await assertChecksPassedForTree(root, output);
+    const files = pending?.uploaded ? [] : await Promise.all(graph.deploymentScope.includedFiles.map(async (path) => ({ path, content: new Uint8Array(await readFile(resolve(root, path))) })));
+    output(`Isomorph found ${graph.deploymentScope.includedFiles.length} app files.`);
+    // A declared connection IT has not approved yet would only park the
+    // deployment after the save; file the request and refuse here, before any operation exists.
+    const kitAppId = pending?.appId ?? (options.integrations ? await assertPreviewIntegrationsReady(root, options.integrations.governance, tenantId, options.integrations.bundle, output) : options.appId);
+    // An app that calls governed AI needs the company's AI setup to pass the
+    // deployment PLAN; ask governance now rather than discover it on the deployed button.
+    if (!pending?.uploaded && options.integrations && kitAppId && await appCallsAi(root))
+        await assertAiReady(kitAppId, "preview", options.integrations.governance, output);
+    // A kit app the pipeline's gate would refuse (a table without RLS, an
+    // operation no journey exercises, a cross-user leak) is refused here,
+    // before the save, by the same gate with the same wording.
+    const gate = options.kitGate === false ? undefined : options.kitGate ?? (options.integrations ? { bundle: options.integrations.bundle } : undefined);
+    if (gate && !pending?.uploaded)
+        await preflightKitGate(root, gate.bundle, output, gate.run);
+    try {
+        await client.initialize();
+    }
+    catch {
+        throw new CliError("NOT_STARTED", "Isomorph could not be reached before the operation started.");
+    }
+    let start;
+    const linked = kitAppId ? { appId: kitAppId } : {};
+    try {
+        start = pending ? { operation: { operationId: pending.operationRef } } : structured(await client.call("isomorph_start_productionization", { appPath: basename(root), appName: basename(root), surface: "codex", ...linked }));
+    }
+    catch (error) {
+        if (error instanceof CliError)
+            throw error;
+        throw new CliError("START_UNCONFIRMED", "Isomorph did not confirm the start response. Run productionise again to recover the app operation before starting another deployment.");
+    }
+    const operationRef = start.operation?.operationId;
+    if (!operationRef)
+        throw new CliError("START_UNCONFIRMED", "Isomorph did not return the operation reference. Recover the app operation before starting another deployment.");
+    pending ??= { tenantId, endpoint: client.endpoint, operationRef, sourceDigest: (await sourceDigest(root)).digest, uploaded: false, graph, ...(kitAppId ? { appId: kitAppId } : {}) };
+    await writePending(root, pending);
+    output(`Isomorph operation saved. Continue with isomorph status --operation ${operationRef} --wait --json.`);
+    try {
+        let appId = pending.appId;
+        if (!pending.uploaded && !pending.uploadCompletion) {
+            const submitted = structured(await client.call("isomorph_submit_application_graph", { operationId: operationRef, surface: "codex", graph, ...linked }));
+            if (submitted.nextTool && !matchesTool(submitted.nextTool, "isomorph_prepare_source_upload"))
+                throw new CliError("UNSUPPORTED_NEXT_STEP", "Isomorph returned an unsupported next step.", operationRef);
+            appId = typeof submitted.appId === "string" ? submitted.appId.trim() : "";
+            if (!appId)
+                throw new CliError("APP_IDENTITY_MISSING", "Isomorph did not return the app identity for this operation.", operationRef);
+            if (kitAppId && appId !== kitAppId)
+                throw new CliError("APP_IDENTITY_MISMATCH", "Isomorph returned a different app identity than the one linked in .isomorph/kit.lock.json.", operationRef);
+            // The canonical identity lands in kit.lock so a later `integrations request` reuses it instead of linking a second app.
+            await recordKitAppId(root, appId, tenantId);
+            pending = { ...pending, appId, sourceDigest: (await sourceDigest(root)).digest };
+            await writePending(root, pending);
+            if (options.confirmedAppSetup && !pending.appSetupConfirmed) {
+                await confirmProfile(client, operationRef, options.confirmedAppSetup, output);
+                await confirmAudience(client, operationRef, options.confirmedAppSetup.audienceEmails, output);
+                pending = { ...pending, appSetupConfirmed: true };
+                await writePending(root, pending);
+            }
+            const manifest = await createSourceManifest({ tenantId, appId, operationId: operationRef, graphDigest: graph.graphDigest, files });
+            const preliminaryArchive = await archiveForManifest(root, manifest);
+            const prepared = structured(await client.call("isomorph_prepare_source_upload", { operationId: operationRef, appId, surface: "codex", graph, format: "zip", filename: `${appId}.zip`, compressedBytes: preliminaryArchive.body.byteLength, manifest: { schema: "isomorph.source-package-manifest/1.0", files: manifest.files.map(file => ({ path: file.path, size: file.bytes, sha256: file.sha256 })) } }));
+            if (!prepared.acceptedManifest || !prepared.sourceUpload)
+                throw new CliError("UPLOAD_CONTRACT_MISSING", "Isomorph did not return a safe upload contract.", operationRef);
+            if (prepared.nextAction?.tool && !matchesTool(prepared.nextAction.tool, "isomorph_complete_source_upload"))
+                throw new CliError("UNSUPPORTED_NEXT_STEP", "Isomorph returned an unsupported next step.", operationRef);
+            const archive = await archiveForManifest(root, prepared.acceptedManifest);
+            const parts = await putMultipart(prepared.sourceUpload, archive.body, (sent, total) => output(`Isomorph is uploading the app package (${Math.floor(sent * 100 / total)}%).`));
+            pending = { ...pending, uploadCompletion: { intentId: prepared.sourceUpload.intentId, parts, clientSha256: archive.digest } };
+            await writePending(root, pending);
+        }
+        if (!pending.uploaded && pending.uploadCompletion) {
+            await client.call("isomorph_complete_source_upload", { operationId: operationRef, ...pending.uploadCompletion });
+            pending = { ...pending, uploaded: true };
+            await writePending(root, pending);
+            output("Isomorph uploaded the secure app package and is inspecting it.");
+        }
+        if (!appId)
+            throw new CliError("APP_IDENTITY_MISSING", "The saved operation has no app identity.", operationRef);
+        if (!prior?.sourceSave)
+            await waitForIntake(client, operationRef);
+        let execution = prior?.sourceSave?.status && prior.sourceSave.status !== "AWAITING_APPROVAL" ? { status: prior.sourceSave.status } : await execute(client, operationRef, appId, graph);
+        if (execution.status === "APPROVAL_REQUIRED" || execution.approvalRequiredBeforeExternalAction === true) {
+            output(`Approval required: Isomorph can copy ${graph.deploymentScope.includedFiles.length} app files to the approved company code system. Nothing will be deployed or released. Type Approved. then press Enter.`);
+            const approval = await readApproval();
+            if (approval !== "Approved.")
+                throw new CliError("APPROVAL_NOT_GRANTED", "The Isomorph save was not approved.", operationRef);
+            execution = await execute(client, operationRef, appId, graph, { schema: "isomorph.stage-approval/1.0", step: "save_source_baseline", approved: true, approvedByUser: true, userApprovalText: approval, userVisibleProgress: "Approved.", nextStepSummary: "Isomorph can safely save the app.", dataOrActions: ["Save the app in the company code system."] });
+        }
+        if (execution.status === "ADMIN_SETUP_REQUIRED")
+            throw new CliError("ADMIN_SETUP_REQUIRED", "The company code connection needs one-time administrator setup.", operationRef);
+        if (execution.status === "FAILED")
+            throw new CliError("FAILED", "Isomorph could not save the app.", operationRef);
+        if (execution.status === "RETRYABLE_FAILURE")
+            throw new CliError("RETRYABLE_FAILURE", "Isomorph could not complete the save yet. Resume this operation safely.", operationRef);
+        const evidence = await waitForSave(client, operationRef, graph, execution, output);
+        const report = structured(await client.call("isomorph_build_verification_report", { operationId: operationRef, appId, surface: "codex", graph, sourceControlEvidence: evidence.sourceControlEvidence, runnerEvidence: evidence.runnerEvidence }));
+        output("Isomorph verified the saved app.");
+        const verification = safeVerificationResult(report, evidence);
+        if (options.waitForDeployment === false)
+            return { cliVersion: CLI_VERSION, operationRef, result: verification };
+        return finishDeployment(client, operationRef, output, options, verification);
+    }
+    catch (error) {
+        throw await operationFailure(client, operationRef, error);
+    }
+}
+/**
+ * What a builder is told to do when the checks have not passed. `isomorph check`
+ * exercises the retained journeys and the pipeline's operation-coverage gate
+ * against the running app, so both commands are named: the app has to be up
+ * before the checks that matter can run at all.
+ */
+const RUN_THE_CHECKS = "Run `isomorph check --app-root .` (it starts the local Isomorph services itself when `isomorph dev` is not running). Fix whatever it reports, then run this again.";
+const FIX_THE_CHECKS = "Fix what the checks reported (the detail is in .isomorph/local/check-report.json), then run `isomorph check --app-root .` again.";
+/**
+ * The checks the deployment pipeline replays in the cloud: each retained
+ * journey under its own `journey:<file>` name and the operation-coverage gate
+ * under the pipeline's rule for it. The kit gate records them as `not_run` —
+ * not as a pass — when an earlier check stopped the run, which is exactly the
+ * state that used to reach the pipeline and fail there.
+ */
+function isReplayedGate(name) {
+    return name === FLOW_CHECK || name.startsWith("journey:");
+}
+/** The retained checks this app keeps, enumerated exactly as `isomorph check` and the pipeline enumerate them. */
+async function retainedChecks(root) {
+    return (await readdir(kitPaths(root).checks).catch(() => [])).filter(name => /\.(mjs|js|cjs)$/.test(name)).sort();
+}
+/** At most three names, so one long list of journey files cannot push the reason itself past the report cap. */
+function nameList(names) {
+    return names.length > 3 ? `${names.slice(0, 3).join(", ")} and ${names.length - 3} more` : names.join(", ");
+}
+/**
+ * Refuses a tree whose own retained checks have not passed *for that tree*.
+ *
+ * `isomorph check` writes `.isomorph/local/check-report.json` with the digest of
+ * the source it ran against, so three different things have to be true before a
+ * deployment is worth anyone's time: the checks ran, they ran against these
+ * bytes, and the ones that matter actually ran rather than being skipped.
+ *
+ * Scope: an app that keeps no retained checks is not gated. This is not a
+ * loophole — `.isomorph/checks/` is what the pipeline replays, and an app that
+ * keeps none is refused there by the same coverage gate the moment its code
+ * performs any operation. Gating it here would only refuse, with a fix it
+ * cannot carry out, every app that never adopted the kit.
+ *
+ * The digest is recomputed by the same `sourceDigest` `isomorph check` used, so
+ * a match means one function saw the same bytes twice and no parallel
+ * implementation can drift into refusing a checked tree. It spans the whole app
+ * boundary, so a `--include` submission is compared against the tree the checks
+ * actually ran on: conservative where the two differ, never permissive.
+ */
+async function assertChecksPassedForTree(root, output) {
+    const retained = await retainedChecks(root);
+    if (!retained.length)
+        return;
+    const plural = retained.length === 1 ? "" : "s";
+    const report = await readReport(root);
+    if (!report)
+        throw new CliError("CHECKS_NOT_RUN", `This app keeps ${retained.length} check${plural} that say whether it still works, and ${retained.length === 1 ? "it has" : "they have"} never been run against this code. Isomorph does not deploy an app whose own checks have not passed.`, undefined, RUN_THE_CHECKS);
+    const tree = await sourceDigest(root);
+    if (report.sourceDigest !== tree.digest)
+        throw new CliError("CHECKS_STALE", "The app's code has changed since its checks last ran, so that result no longer describes what would be deployed. Isomorph does not deploy an app whose own checks have not passed for this exact code.", undefined, RUN_THE_CHECKS);
+    const checks = Array.isArray(report.checks) ? report.checks : [];
+    const failed = checks.filter(check => check.status === "fail").map(check => check.name);
+    if (failed.length || report.passed !== true)
+        throw new CliError("CHECKS_FAILED", `The app's own checks last ran and did not pass${failed.length ? ` (${nameList(failed)})` : ""}. Isomorph does not deploy an app whose checks are failing; the deployment pipeline would refuse it too.`, undefined, FIX_THE_CHECKS);
+    // "Skipped" is not "passed". A report whose journeys and coverage gate never
+    // ran says nothing about whether the app works, and accepting it would hand
+    // the discovery straight back to the pipeline.
+    const notRun = checks.filter(check => isReplayedGate(check.name) && check.status !== "pass").map(check => check.name);
+    const flowRan = checks.some(check => check.name === FLOW_CHECK && check.status === "pass");
+    if (notRun.length || !flowRan) {
+        const names = notRun.length ? notRun : [FLOW_CHECK];
+        throw new CliError("CHECKS_NOT_RUN", `The last check run skipped ${nameList(names)} instead of passing ${names.length === 1 ? "it" : "them"}. The deployment pipeline runs the same ones in the cloud, so skipping them here only moves the failure.`, undefined, RUN_THE_CHECKS);
+    }
+    output(`The app's own checks passed for this exact code (${retained.length} retained check${plural}, last run ${report.createdAt}).`);
+}
+async function waitForIntake(client, operationRef) {
+    for (let attempt = 0; attempt < 60; attempt += 1) {
+        const status = structured(await client.call("isomorph_get_operation_status", { operationId: operationRef, waitSeconds: 3 }));
+        if (status.operation?.stage === "awaiting-approval" || status.sourceSave?.status === "QUEUED")
+            return;
+        if (status.operation?.stage === "failed")
+            throw intakeRejection(status, operationRef);
+        await new Promise(resolve => setTimeout(resolve, 1_000));
+    }
+    throw new CliError("INSPECTION_TIMEOUT", "Isomorph is still inspecting the app package. Resume this operation safely.", operationRef);
+}
+/**
+ * Intake does not merely refuse a package; it records why — a stable code, one
+ * plain-English sentence, and the commands that fix it — on the operation. The
+ * stage alone was all this used to read, so every refusal reached the maker as
+ * the same sentence and the reason stayed on the server. Say what the server
+ * said, and keep the generic line only for an operation that failed without
+ * any detail at all.
+ */
+function intakeRejection(status, operationRef) {
+    return refusal(pickSourceFailure(status), "PACKAGE_REJECTED", "Isomorph could not safely accept this app package.", operationRef);
+}
+/**
+ * The one way this file turns "the server refused" into a failure the builder
+ * can act on: the server's own code, sentence and fix where it gave them, the
+ * generic pair only where it gave nothing, and the operation reference always.
+ */
+function refusal(failure, fallbackCode, fallbackMessage, operationRef) {
+    return new CliError(failure?.code ?? fallbackCode, failure?.message ?? fallbackMessage, operationRef, failure?.remediationHint);
+}
+/**
+ * Why the whole operation stopped. The outer catch used to answer this with one
+ * fixed sentence for everything that was not already a `CliError`, which is
+ * every plain refusal the server raises — so the reason stayed on the server
+ * and the builder was told only that something failed. Read the reason from
+ * three places, in the order that serves the builder:
+ *
+ *  1. A `CliError` already carries a reason; keep it, and only make sure it
+ *     names the operation, since by here one exists.
+ *  2. The operation is not failed at all but waiting for its profile, audience
+ *     or secrets — say what is pending and which commands supply it.
+ *  3. Otherwise the thrown value's own detail, then the refusal intake recorded
+ *     on the operation, and only then the generic line.
+ */
+async function operationFailure(client, operationRef, error) {
+    if (error instanceof CliError)
+        return error.operationRef ? error : new CliError(error.code, error.message, operationRef, error.remediationHint, error.result);
+    const detail = errorDetail(error);
+    const state = await probeOperation(client, operationRef);
+    // A pending-setup operation is not a failed operation: nothing is wrong with
+    // it and re-running `productionise` after the setup commands carries it on.
+    // It is still a failed *command* — no app was saved, verified or deployed —
+    // so it keeps a non-zero exit rather than reporting a success that did not
+    // happen, and carries the real next step instead of a bare code.
+    if (state.pending.length)
+        return new CliError(detail?.code ?? "SETUP_REQUIRED", state.plainEnglish ?? pendingSentence(state.pending), operationRef, setupRemediation(operationRef));
+    return refusal(detail ?? state.failure, "OPERATION_FAILED", "Isomorph could not complete the started operation.", operationRef);
+}
+/**
+ * What the thrown value itself says. A refusal reaches us as a bare `Error`
+ * carrying the server's sentence, and — once errors carry them — the server's
+ * stable code and remediation too; all of it must survive to the builder. A
+ * runtime fault (`TypeError` and friends) is a defect in this CLI rather than
+ * an answer for the builder, so its message is not borrowed as the reason
+ * unless it also carries a code.
+ */
+function errorDetail(error) {
+    if (!error || typeof error !== "object")
+        return undefined;
+    const raw = error;
+    const code = text(raw.code);
+    const remediationHint = text(raw.remediationHint);
+    const message = code || (error instanceof Error && error.constructor === Error) ? text(raw.message) : undefined;
+    if (!code && !message && !remediationHint)
+        return undefined;
+    return { ...(code ? { code } : {}), ...(message ? { message } : {}), ...(remediationHint ? { remediationHint } : {}) };
+}
+function text(value) {
+    return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+/**
+ * What the server says about the operation once a call has failed. Both reads
+ * are best-effort: the reason the builder gets must never depend on a second
+ * call succeeding, so a probe that fails simply contributes nothing.
+ */
+async function probeOperation(client, operationRef) {
+    let failure;
+    try {
+        failure = pickSourceFailure(structured(await client.call("isomorph_get_operation_status", { operationId: operationRef, waitSeconds: 0 })));
+    }
+    catch { /* no status: fall back to what the error said */ }
+    try {
+        const setup = await getAppSetup(client, operationRef);
+        return { pending: setup.pending ?? [], ...(setup.nextAction?.plainEnglish ? { plainEnglish: setup.nextAction.plainEnglish } : {}), ...(failure ? { failure } : {}) };
+    }
+    catch {
+        return { pending: [], ...(failure ? { failure } : {}) };
+    }
+}
+/** The console's post-save steps, in the words the CLI already uses for them. */
+const SETUP_STEPS = {
+    confirm_app_profile: "its name and description confirmed",
+    confirm_app_audience: "its audience confirmed",
+    provide_secrets: "the secrets it asked for"
+};
+function pendingSentence(pending) {
+    return `The app still needs: ${pending.map(step => SETUP_STEPS[step] ?? step).join("; ")}.`;
+}
+/**
+ * `isomorph retry` is what the help offers for resuming an operation, but it
+ * restarts a deployment — on an operation still waiting for its setup there is
+ * no deployment to restart, and running `productionise` again is what carries
+ * it on. Name the commands that actually work, and say which one does not.
+ */
+function setupRemediation(operationRef) {
+    return `Run \`isomorph profile\` and \`isomorph audience\`, then \`isomorph productionise\` again — not \`isomorph retry\`. Full list: \`isomorph setup --operation ${operationRef}\`.`;
+}
+async function execute(client, operationRef, appId, graph, approval) {
+    const args = { operationId: operationRef, appId, surface: "codex", graph, action: "save_baseline", mode: "EXECUTE" };
+    if (approval)
+        args.approval = approval;
+    return structured(await client.call("isomorph_execute_source_control", args)).sourceControlExecution ?? {};
+}
+async function waitForSave(client, operationRef, graph, first, output) {
+    let waitSeconds = boundedWait(first.nextAction?.waitSeconds);
+    for (let attempt = 0; attempt < 40; attempt += 1) {
+        const status = structured(await client.call("isomorph_get_operation_status", { operationId: operationRef, waitSeconds }));
+        const terminal = status.sourceSave?.status;
+        if (terminal === "SUCCEEDED" || terminal === "DUPLICATE") {
+            const sourceControlEvidence = status.sourceControlEvidence ?? status.sourceSave?.sourceControlEvidence;
+            const runnerEvidence = status.runnerEvidence ?? status.sourceSave?.runnerEvidence;
+            if (!sourceControlEvidence || !runnerEvidence)
+                throw new CliError("EVIDENCE_MISSING", "Isomorph did not return managed save evidence.", operationRef);
+            return { sourceControlEvidence, runnerEvidence };
+        }
+        if (terminal === "FAILED")
+            throw new CliError("FAILED", "Isomorph could not save the app.", operationRef);
+        if (terminal === "RETRYABLE_FAILURE")
+            throw new CliError("RETRYABLE_FAILURE", "Isomorph could not complete the save yet. Resume this operation safely.", operationRef);
+        waitSeconds = boundedWait(status.nextAction?.waitSeconds ?? status.waitSeconds);
+        output("Isomorph is still saving the app.");
+    }
+    throw new CliError("RETRYABLE_FAILURE", "Isomorph could not finish the save within the safe retry window.", operationRef);
+}
+function boundedWait(value) {
+    return Math.min(15, Math.max(0, Number.isFinite(value) ? Math.floor(value) : 15));
+}
+/** Isomorph accepts dotted MCP names (its handler keys) while publishing portable underscore names. */
+function matchesTool(actual, expected) {
+    return actual.replaceAll(".", "_") === expected;
+}
+function safeVerificationResult(value, statusEvidence) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return { verification: "completed" };
+    const record = value;
+    const decision = record.decision && typeof record.decision === "object" && !Array.isArray(record.decision)
+        ? record.decision
+        : undefined;
+    return {
+        verification: typeof decision?.status === "string"
+            ? decision.status
+            : typeof record.status === "string"
+                ? record.status
+                : "completed",
+        ...(typeof decision?.assuranceLevel === "string" ? { assuranceLevel: decision.assuranceLevel } : {}),
+        ...(typeof record.protectedUrl === "string" ? { protectedUrl: record.protectedUrl } : {}),
+        ...((record.sourceControlEvidence ?? statusEvidence?.sourceControlEvidence) && typeof (record.sourceControlEvidence ?? statusEvidence?.sourceControlEvidence) === "object" && !Array.isArray(record.sourceControlEvidence ?? statusEvidence?.sourceControlEvidence)
+            ? { sourceControlEvidence: record.sourceControlEvidence ?? statusEvidence?.sourceControlEvidence }
+            : {}),
+        ...((record.runnerEvidence ?? statusEvidence?.runnerEvidence) && typeof (record.runnerEvidence ?? statusEvidence?.runnerEvidence) === "object" && !Array.isArray(record.runnerEvidence ?? statusEvidence?.runnerEvidence)
+            ? { runnerEvidence: record.runnerEvidence ?? statusEvidence?.runnerEvidence }
+            : {})
+    };
+}
+function outcomeLine(summary) {
+    switch (summary.outcome) {
+        case "live": return `Isomorph deployed the app. Protected preview: ${summary.deployment?.protectedUrl ?? ""}`.trim();
+        case "production_live": return `The app is live in production: ${summary.production?.productionUrl ?? ""}`.trim();
+        case "waiting": return summary.waiting?.plainEnglish ?? "Isomorph needs one more step in the Isomorph console before it can deploy.";
+        // `running` and `no_deployment` both carry their own next step.
+        default: return summary.nextStep ?? "Isomorph saved the app; deployment has not started.";
+    }
+}
+const readApproval = readLine;
+/**
+ * Whether the app really calls governed AI: the gate's inventory of
+ * `isomorph.ai.*` call sites (`.isomorph/local/check-report.json`,
+ * `gate.inventory.aiCallsites`). Not the capability word — a starter that
+ * merely carried an `ai()` accessor was derived as `ai` and would have been
+ * refused `AI_NOT_READY` at a company without AI for an app that never asks
+ * for it (2026-09-14). The call sites are what the deployment PLAN sees.
+ */
+export async function appCallsAi(root) {
+    const report = await readReport(root);
+    const callsites = report?.gate?.inventory?.aiCallsites;
+    return Array.isArray(callsites) && callsites.length > 0;
+}
+async function finishDeployment(client, operationRef, output, options, verification = {}) {
+    let summary;
+    try {
+        summary = options.waitForDeployment === false ? outcomeFor(await fetchStatus(client, operationRef), operationRef) : await follow(client, operationRef, output, options.waitOptions);
+    }
+    catch (error) {
+        if (error instanceof CliError)
+            throw withOperation(error, operationRef);
+        throw new CliError("DEPLOYMENT_STATUS_UNAVAILABLE", `Isomorph could not follow the existing operation (${error instanceof Error ? error.message.replace(/https?:\/\/\S+|Bearer\s+\S+/gi, "").slice(0, 160) : "unknown error"}). Check again with \`isomorph status\`.`, operationRef);
+    }
+    output(outcomeLine(summary));
+    // The console asks for the app's name, audience and secrets before it
+    // offers promotion; say what is still open so a CLI-only builder knows.
+    let setup;
+    try {
+        setup = await getAppSetup(client, operationRef);
+    }
+    catch {
+        setup = undefined;
+    }
+    if (setup?.pending?.length)
+        output(`${setup.nextAction?.plainEnglish ?? "The app still needs setup."} Run \`isomorph setup --operation ${operationRef}\`.`);
+    return { cliVersion: CLI_VERSION, operationRef, result: { ...verification, ...summary, ...(setup ? { setup: { pending: setup.pending ?? [], ...(setup.nextAction?.plainEnglish ? { plainEnglish: setup.nextAction.plainEnglish } : {}) } } : {}) } };
+}
+function operationFinished(status) {
+    if (status.production)
+        return ["LIVE", "FAILED", "MANUAL_RECOVERY"].includes(status.production.state);
+    if (status.deployment)
+        return ["LIVE", "FAILED", "STALE", "RETRYABLE_FAILURE"].includes(status.deployment.state);
+    return status.operation?.stage === "failed";
+}
+async function readPending(root, tenantId, endpoint) {
+    let raw;
+    try {
+        raw = await readFile(resolve(root, ".isomorph/local/productionise.json"), "utf8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return undefined;
+        throw error;
+    }
+    const record = JSON.parse(raw);
+    if (!record.operationRef || !record.graph || typeof record.uploaded !== "boolean" || !record.sourceDigest)
+        throw new CliError("OPERATION_RECORD_INVALID", "The saved deployment reference cannot be read. Recover the operation from Isomorph before starting another.");
+    return record.tenantId === tenantId && record.endpoint === endpoint ? record : undefined;
+}
+async function writePending(root, record) {
+    const path = resolve(root, ".isomorph/local/productionise.json");
+    try {
+        await mkdir(dirname(path), { recursive: true });
+        const temporary = `${path}.${process.pid}.tmp`;
+        await writeFile(temporary, JSON.stringify(record), { mode: 0o600 });
+        await rename(temporary, path);
+    }
+    catch {
+        throw new CliError("OPERATION_RECORD_WRITE_FAILED", "Isomorph started the operation but could not save its local reference. Continue with isomorph status using this operation reference.", record.operationRef);
+    }
+}
+function withOperation(error, operationRef) {
+    return new CliError(error.code, error.message, operationRef, error.remediationHint, error.result);
+}

package/dist/packages/harbour-cli/src/remote-mcp-client.js

@@ -0,0 +1,121 @@
+import { CLI_VERSION } from "./version.js";
+import { CliError } from "./output.js";
+/** The code for a refusal the server did not label. Its own words still reach
+ * the builder; only the machine label is ours, and it says exactly that. */
+const UNLABELLED_REFUSAL = "ISOMORPH_REFUSED";
+/**
+ * Isomorph labels part of its refusals `CODE: sentence` on the wire — `src/mcp.ts`
+ * raises `APP_NOT_REGISTERED: …`, `SOURCE_UPLOAD_REQUIRED: …`, and the tool
+ * result carries that text and nothing else. Lifting the prefix into `code` is
+ * not classification: the label is the server's own, the sentence is kept
+ * whole either way, and a miss only means the refusal goes out unlabelled.
+ */
+const LABELLED = /^([A-Z][A-Z0-9_]{2,63}):[ \t]+(\S[\s\S]*)$/;
+function refusalText(result) {
+    return (result.content ?? []).map(item => item.text ?? "").join("\n").trim();
+}
+/**
+ * A tool refusal, carried whole: the server's own code, its own sentence and
+ * its own fix. `structuredContent` is read first because that is where a code
+ * belongs and where the server will put one once `toolError` carries one; today
+ * only the labelled prefix is available.
+ */
+export function serverRefusal(result) {
+    const text = refusalText(result);
+    const detail = result.structuredContent && typeof result.structuredContent === "object" ? result.structuredContent : undefined;
+    const declared = typeof detail?.code === "string" ? detail.code.trim() : "";
+    const hint = typeof detail?.remediationHint === "string" && detail.remediationHint.trim() ? detail.remediationHint.trim() : undefined;
+    const labelled = declared ? null : LABELLED.exec(text);
+    return new CliError(declared || labelled?.[1] || UNLABELLED_REFUSAL, (labelled?.[2] ?? text) || "Isomorph rejected the request.", undefined, hint);
+}
+/** A JSON-RPC error is Isomorph refusing the call itself (an unknown method, a
+ * body it could not parse). Its numeric code is the only one it has, so it is
+ * reported as such rather than flattened away. */
+function rpcRefusal(error, status) {
+    const text = error.message?.trim() ?? "";
+    const labelled = LABELLED.exec(text);
+    const code = labelled?.[1] ?? (typeof error.code === "number" ? `ISOMORPH_RPC_${error.code}` : `ISOMORPH_HTTP_${status}`);
+    return new CliError(code, (labelled?.[2] ?? text) || `Isomorph refused the request (HTTP ${status}).`);
+}
+async function readRpc(response) {
+    try {
+        return await response.json();
+    }
+    catch {
+        throw new Error(`Isomorph returned a response that was not JSON (HTTP ${response.status}).`);
+    }
+}
+export class RemoteMcpClient {
+    url;
+    tenant;
+    id = 0;
+    initialized = false;
+    token;
+    constructor(url, token, tenant) {
+        this.url = url;
+        this.tenant = tenant;
+        this.token = typeof token === "string" ? async () => token : token;
+    }
+    get endpoint() { return this.url; }
+    async initialize() {
+        if (this.initialized)
+            return;
+        await this.request("initialize", { protocolVersion: "2025-11-25", capabilities: {}, clientInfo: { name: "isomorph-cli", version: CLI_VERSION } });
+        await this.request("notifications/initialized", undefined, false);
+        this.initialized = true;
+    }
+    async call(name, args) {
+        const response = await this.request("tools/call", { name, arguments: args });
+        const result = response;
+        if (result.isError)
+            throw serverRefusal(result);
+        return result;
+    }
+    async request(method, params, expectResponse = true) {
+        const body = JSON.stringify({ jsonrpc: "2.0", id: ++this.id, method, ...(params === undefined ? {} : { params }) });
+        let response = await this.post(body);
+        // A 401 mid-command usually means the stored token was rotated by another
+        // process; re-resolve (which reloads the store) and retry once. A second
+        // 401 means the sign-in itself is gone.
+        if (response.status === 401)
+            response = await this.post(body);
+        if (response.status === 401)
+            throw new CliError("AUTH_REQUIRED", "Isomorph sign-in expired or was revoked. Run `isomorph login` again.");
+        if (!expectResponse)
+            return undefined;
+        const parsed = await readRpc(response);
+        if (parsed.error)
+            throw rpcRefusal(parsed.error, response.status);
+        // A non-ok response with no JSON-RPC error in it is the network between us
+        // and Isomorph, not Isomorph's answer, so it stays a plain Error: a long poll
+        // treats plain Errors as transient and tries again (see `waitForSettled`),
+        // and only `CliError` stops it. The wording is decided here rather than
+        // guessed from this string downstream.
+        if (!response.ok)
+            throw new Error(`Isomorph request failed (HTTP ${response.status}).`);
+        return parsed.result;
+    }
+    async post(body) {
+        const headers = { "content-type": "application/json", "mcp-protocol-version": "2025-11-25", "x-harbour-tenant": this.tenant };
+        const token = await this.token();
+        if (token)
+            headers.authorization = `Bearer ${token}`;
+        try {
+            return await fetch(this.url, { method: "POST", headers, body });
+        }
+        catch (error) {
+            // Plain Error for the same reason as the non-ok branch: a dropped
+            // connection mid-deployment is transient and the poll must be free to
+            // retry. `redact()` strips the URL before any of this is printed.
+            throw new Error(`Isomorph could not be reached (${error instanceof Error ? error.message : "no details"}).`);
+        }
+    }
+}
+export function structured(result) {
+    if (result.isError)
+        throw serverRefusal(result);
+    return result.structuredContent;
+}
+export function plainText(result) {
+    return result.content?.map(item => item.text ?? "").join("\n") ?? "";
+}