@isomorph.ai/cli 0.2.0

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

@@ -0,0 +1,382 @@
+import { structured } from "./remote-mcp-client.js";
+import { CliError } from "./output.js";
+const DEPLOYMENT_TERMINAL = new Set(["LIVE", "FAILED", "STALE", "RETRYABLE_FAILURE"]);
+const PRODUCTION_TERMINAL = new Set(["LIVE", "FAILED", "MANUAL_RECOVERY"]);
+export function summarize(status) {
+    return {
+        ...(status.operation?.stage ? { stage: status.operation.stage } : {}),
+        ...(status.sourceSave?.status ? { sourceSave: { status: status.sourceSave.status } } : {}),
+        ...(status.deployment ? { deployment: pickDeployment(status.deployment) } : {}),
+        ...(status.production ? { production: pickProduction(status.production) } : {}),
+        ...(status.waiting ? { waiting: { stage: status.waiting.stage, plainEnglish: status.waiting.plainEnglish } } : {}),
+        ...(status.nextAction?.plainEnglish ? { nextStep: status.nextAction.plainEnglish } : {}),
+        ...(status.nextTool ? { nextTool: status.nextTool } : {})
+    };
+}
+function pickDeployment(value) {
+    return {
+        state: value.state,
+        ...(value.status ? { status: value.status } : {}),
+        ...(value.message ? { message: value.message } : {}),
+        ...(value.protectedUrl ? { protectedUrl: value.protectedUrl } : {}),
+        ...(value.versionId ? { versionId: value.versionId } : {}),
+        ...(value.failure ? { failure: pickFailure(value.failure) } : {})
+    };
+}
+function pickFailure(value) {
+    return { ...(value.message ? { message: value.message } : {}), ...(value.retryable !== undefined ? { retryable: value.retryable } : {}), ...(value.remediationHint ? { remediationHint: value.remediationHint } : {}) };
+}
+/**
+ * The refusal reason source intake stored on the operation. Read the same way
+ * `pickDeployment` reads a deployment failure: keep the server's own code,
+ * wording and remediation, drop anything blank, and report nothing at all when
+ * the server supplied nothing — so a caller can tell "no detail" apart from
+ * "detail that happened to be empty".
+ */
+export function pickSourceFailure(status) {
+    const failure = status.operation?.source?.failure;
+    if (!failure || typeof failure !== "object")
+        return undefined;
+    const code = text(failure.code);
+    const message = text(failure.message);
+    const remediationHint = text(failure.remediationHint);
+    if (!code && !message && !remediationHint)
+        return undefined;
+    return {
+        ...(code ? { code } : {}),
+        ...(failure.retryable !== undefined ? { retryable: failure.retryable } : {}),
+        ...(message ? { message } : {}),
+        ...(remediationHint ? { remediationHint } : {})
+    };
+}
+function text(value) {
+    return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+function pickProduction(value) {
+    return {
+        state: value.state,
+        ...(value.status ? { status: value.status } : {}),
+        ...(value.message ? { message: value.message } : {}),
+        ...(value.productionUrl ? { productionUrl: value.productionUrl } : {}),
+        ...(value.versionId ? { versionId: value.versionId } : {}),
+        ...(value.previewVersionId ? { previewVersionId: value.previewVersionId } : {}),
+        ...(value.failure ? { failure: pickFailure(value.failure) } : {})
+    };
+}
+export async function fetchStatus(client, operationRef, waitSeconds = 0) {
+    await client.initialize();
+    return structured(await client.call("isomorph_get_operation_status", { operationId: operationRef, waitSeconds }));
+}
+/** True when nothing more will change without a person acting. */
+export function isSettled(status) {
+    if (status.waiting)
+        return true;
+    if (status.production)
+        return PRODUCTION_TERMINAL.has(status.production.state);
+    if (status.deployment)
+        return DEPLOYMENT_TERMINAL.has(status.deployment.state);
+    return false;
+}
+/** What the wait was before `--max-wait` existed: a caller that never passes it waits exactly as long as it did. */
+const DEFAULT_MAX_WAIT_MS = 30 * 60_000;
+/** A line at least this often while nothing changes, so a wrapper with its own idle timeout (an agent's shell tool) keeps seeing output; see `follow`. */
+const HEARTBEAT_MS = 60_000;
+/**
+ * Follow the operation until the preview deployment (or an in-flight production
+ * promotion) settles. Isomorph long-polls up to 15 s per call and returns early
+ * on change, so the loop is bounded by wall clock rather than by call count.
+ * `noDeploymentGraceMs` covers the gap between the source save succeeding and
+ * the deployment attempt being recorded; past it, a saved operation with no
+ * deployment is reported as such instead of waited on forever.
+ *
+ * Returns for exactly three reasons, and the status says which: it settled;
+ * nothing was in flight when the grace window closed; or something was in
+ * flight when the ceiling passed. The ceiling is never thrown — see `follow`.
+ * Two waits, two bounds: the grace window while nothing is in flight, the
+ * ceiling once something is. Each long-poll and each pause is cut to what is
+ * left of the bound, so `--max-wait N` answers within N seconds — an agent's
+ * tool with a total cap of N sees the answer instead of killing the command.
+ */
+export async function waitForSettled(client, operationRef, output, options = {}) {
+    const now = options.now ?? Date.now;
+    const sleep = options.sleep ?? (ms => new Promise(resolve => setTimeout(resolve, ms)));
+    const maxWaitMs = options.maxWaitMs ?? DEFAULT_MAX_WAIT_MS;
+    const graceMs = options.noDeploymentGraceMs ?? 90_000;
+    const startedAt = now();
+    // Until the first status says what is in flight, the shorter bound holds.
+    let bound = Math.min(graceMs, maxWaitMs);
+    let last;
+    let lastLine = "";
+    let lastOutputAt = startedAt;
+    let consecutiveFailures = 0;
+    while (true) {
+        const callStarted = now();
+        const remainingMs = startedAt + bound - callStarted;
+        // Nothing more fits inside the bound: the watch answers with what it last saw.
+        if (last && remainingMs <= 1_000)
+            return last;
+        let status;
+        try {
+            status = await fetchStatus(client, operationRef, Math.min(15, Math.max(0, Math.floor(remainingMs / 1000))));
+            consecutiveFailures = 0;
+        }
+        catch (error) {
+            // A deployment takes minutes and one status call out of dozens can fail
+            // transiently (gateway timeout, dropped connection). The operation is
+            // unaffected by our polling, so keep watching; give up only after a run
+            // of failures, and say what the last one was instead of a generic error.
+            if (error instanceof CliError)
+                throw error; // e.g. AUTH_REQUIRED: retrying cannot help.
+            consecutiveFailures += 1;
+            if (consecutiveFailures >= 5)
+                throw new CliError("DEPLOYMENT_STATUS_UNAVAILABLE", `Isomorph stopped answering status checks (${safeMessage(error)}). The deployment may still be running; check again with \`isomorph status\`.`, operationRef);
+            output("Isomorph did not answer that status check; trying again.");
+            await sleep(Math.min(15_000, 3_000 * consecutiveFailures));
+            continue;
+        }
+        last = status;
+        if (isSettled(status))
+            return status;
+        const at = now();
+        bound = status.deployment || status.production ? maxWaitMs : graceMs;
+        const line = progressLine(status);
+        if (line !== lastLine) {
+            output(line);
+            lastLine = line;
+            lastOutputAt = at;
+        }
+        else if (at - lastOutputAt >= HEARTBEAT_MS) {
+            output(runningLine(status, at - startedAt, operationRef));
+            lastOutputAt = at;
+        }
+        // Isomorph returns immediately when nothing is in flight yet; do not spin — and never past the bound.
+        const elapsed = at - callStarted;
+        if (elapsed < 3_000)
+            await sleep(Math.min(3_000 - elapsed, Math.max(0, startedAt + bound - at)));
+    }
+}
+function safeMessage(error) {
+    const raw = error instanceof Error ? error.message : String(error);
+    return raw.replace(/https?:\/\/\S+|Bearer\s+\S+/gi, "").replace(/\s+/g, " ").trim().slice(0, 160) || "no details";
+}
+function activity(status) {
+    return status.production ? "promoting the app to production" : status.deployment ? "deploying the app" : "preparing the deployment";
+}
+function progressLine(status) {
+    const stage = status.production ?? status.deployment;
+    return stage ? `Isomorph is ${activity(status)}${stage.message ? ` (${stage.message})` : ""}.` : "Isomorph saved the app and is preparing the deployment.";
+}
+/**
+ * The one sentence for a watch that has not ended: the heartbeat prints it as
+ * time passes, and a ceiling that passes returns it as the next step. A
+ * wrapper that stops watching, or an agent whose tool did, runs the command
+ * it names and continues the same operation — it never starts another.
+ */
+function runningLine(status, elapsedMs, operationRef) {
+    const seconds = Math.round(elapsedMs / 1000);
+    return `Isomorph is still ${activity(status)} (${Math.floor(seconds / 60)}m${seconds % 60}s). Safe to stop watching: \`${continueCommand(operationRef)}\` picks it up; do not start another.`;
+}
+/**
+ * The one command that resumes a watch, as the CLI's help and the agent guide
+ * print it too. Bounded at two minutes so a wrapper with an idle timeout gets
+ * an answer and runs it again, rather than cutting a 30-minute wait off and
+ * learning nothing.
+ */
+export function continueCommand(operationRef) {
+    return `isomorph status --operation ${operationRef} --wait --max-wait 120 --json`;
+}
+/** The exit-relevant outcome of a status — success, a step the maker must take, an operation still in flight — as the summary with its `outcome` named; a failure is thrown. */
+export function outcomeFor(status, operationRef) {
+    const summary = summarize(status);
+    // A failed stage, reported as the stage recorded it: its sentence, then its
+    // fix, with the summary attached so the envelope carries the version the
+    // console's releases tab and the email name. Only a stage that recorded no
+    // sentence at all gets the generic one.
+    const failed = (code, stage, fallback, suffix = "") => new CliError(code, `${stage.failure?.message ?? stage.message ?? fallback}${suffix}`, operationRef, stage.failure?.remediationHint, summary);
+    if (status.production?.state === "LIVE")
+        return { ...summary, outcome: "production_live" };
+    if (status.production && PRODUCTION_TERMINAL.has(status.production.state))
+        throw failed("PRODUCTION_PROMOTION_FAILED", status.production, "Isomorph could not complete the production promotion.");
+    if (status.waiting)
+        return { ...summary, outcome: "waiting" };
+    // A promotion in flight rides on a LIVE preview; the promotion is what is being followed.
+    if (status.production)
+        return { ...summary, outcome: "running" };
+    if (status.deployment?.state === "LIVE")
+        return { ...summary, outcome: "live" };
+    if (status.deployment && DEPLOYMENT_TERMINAL.has(status.deployment.state)) {
+        const retryable = status.deployment.failure?.retryable === true;
+        throw failed(retryable ? "DEPLOYMENT_RETRYABLE_FAILURE" : "DEPLOYMENT_FAILED", status.deployment, "Isomorph could not complete the deployment.", retryable ? " Run `isomorph retry` to start it again." : "");
+    }
+    if (status.deployment)
+        return { ...summary, outcome: "running" };
+    // No deployment yet has two very different causes. A save that stalled or
+    // failed (RETRYABLE_FAILURE, FAILED) is resumed by running `productionise`
+    // again — observed 2026-09-14 (fourier "Dad Jokes"): a builder read the
+    // administrator sentence for a save that was simply resumable. Only a
+    // SUCCEEDED save with no deployment behind it is the company-setup case.
+    const save = status.sourceSave?.status;
+    if (save && save !== "SUCCEEDED")
+        return { ...summary, outcome: "no_deployment", nextStep: summary.nextStep ?? `Isomorph has not finished saving the app (${save}). Run \`isomorph productionise\` again for this app: it resumes the same save and deploys; nothing is deployed twice.` };
+    return { ...summary, outcome: "no_deployment", nextStep: summary.nextStep ?? "Isomorph saved the app but has not started a deployment for this company yet. Ask your Isomorph administrator to connect deployment." };
+}
+/**
+ * `waitForSettled` then `outcomeFor`, as the one summary a command returns.
+ *
+ * A ceiling that passes is a `running` outcome and never an error: exit 0, the
+ * operation untouched, and the summary says how long this command watched and
+ * names the exact command that resumes the same watch. Measured 2026-09-12:
+ * the ceiling was a thrown `DEPLOYMENT_TIMEOUT`, an agent's shell tool cut the
+ * silent 30-minute wait off long before it, the agent started a second deploy
+ * to get "a status-producing call", and the first one's refusal reached the
+ * human by email and never reached the agent. The heartbeat, the bounded
+ * `--max-wait`, and this outcome each close one part of that.
+ */
+export async function follow(client, operationRef, output, options = {}) {
+    const now = options.now ?? Date.now;
+    const startedAt = now();
+    const status = await waitForSettled(client, operationRef, output, options);
+    const summary = outcomeFor(status, operationRef);
+    if (summary.outcome !== "running")
+        return summary;
+    const elapsedMs = now() - startedAt;
+    return { ...summary, elapsedSeconds: Math.round(elapsedMs / 1000), nextStep: runningLine(status, elapsedMs, operationRef) };
+}
+export async function retryDeployment(client, operationRef, output, options = {}) {
+    await client.initialize();
+    const result = structured(await client.call("isomorph_retry_deployment", { operationId: operationRef }));
+    output(result.retry?.replayed ? "Isomorph had already accepted this retry." : "Isomorph accepted the deployment retry.");
+    if (options.wait === false)
+        return summarize(await fetchStatus(client, operationRef));
+    return follow(client, operationRef, output, options.waitOptions);
+}
+/**
+ * Promotion mirrors the console's "I tested this version" button: the maker
+ * must have opened the live preview and say so, and the version they tested
+ * is pinned so a redeployed preview is refused as stale rather than promoted
+ * unseen.
+ */
+export async function promoteToProduction(client, operationRef, output, options = {}) {
+    const status = await fetchStatus(client, operationRef);
+    if (status.production && !PRODUCTION_TERMINAL.has(status.production.state)) {
+        output("Isomorph is already promoting this app to production.");
+        return options.wait === false ? summarize(status) : follow(client, operationRef, output, options.waitOptions);
+    }
+    const deployment = status.deployment;
+    if (deployment?.state !== "LIVE" || !deployment.versionId || !deployment.protectedUrl)
+        throw new CliError("LIVE_PREVIEW_REQUIRED", "The preview must be live before it can be promoted. Check `isomorph status` first.", operationRef);
+    output(`Open the protected preview and test it: ${deployment.protectedUrl}`);
+    output("When it works as expected, type Tested. then press Enter to promote it to production.");
+    const reply = await (options.readConfirmation ?? readLine)();
+    if (reply !== "Tested.")
+        throw new CliError("PROMOTION_NOT_CONFIRMED", "The production promotion was not confirmed.", operationRef);
+    const result = structured(await client.call("isomorph_promote_to_production", {
+        operationId: operationRef,
+        expectedPreviewVersionId: deployment.versionId,
+        confirmation: { schema: "isomorph.stage-approval/1.0", step: "confirm_preview_tested_and_promote", approved: true, approvedByUser: true, userApprovalText: reply }
+    }));
+    output("Isomorph accepted the production promotion.");
+    if (options.wait === false)
+        return { ...summarize(status), ...(result.production ? { production: pickProduction(result.production) } : {}) };
+    return follow(client, operationRef, output, options.waitOptions);
+}
+export async function readLine() {
+    if (!process.stdin.isTTY) {
+        const chunks = [];
+        for await (const chunk of process.stdin)
+            chunks.push(Buffer.from(chunk));
+        return Buffer.concat(chunks).toString("utf8").trim();
+    }
+    return new Promise(resolve => { process.stdin.setEncoding("utf8"); process.stdin.once("data", value => resolve(String(value).trim())); });
+}
+export async function getAppSetup(client, operationRef) {
+    await client.initialize();
+    return structured(await client.call("isomorph_get_app_setup", { operationId: operationRef }));
+}
+export async function confirmProfile(client, operationRef, input, output) {
+    const setup = await getAppSetup(client, operationRef);
+    const displayName = input.displayName ?? setup.profile?.suggested?.displayName ?? setup.profile?.displayName;
+    const description = input.description ?? setup.profile?.suggested?.description ?? setup.profile?.description;
+    if (!displayName || !description)
+        throw new CliError("PROFILE_INCOMPLETE", "Give the app a name (--name) and a description (--description); Isomorph had no suggestion to fall back on.", operationRef);
+    if (!setup.profile?.profileVersion)
+        throw new CliError("PROFILE_VERSION_MISSING", "Isomorph did not return the app details version.", operationRef);
+    await client.call("isomorph_confirm_app_profile", { operationId: operationRef, displayName, description, expectedVersion: setup.profile.profileVersion });
+    output(`Isomorph recorded the app's name and description: ${displayName}.`);
+    return getAppSetup(client, operationRef);
+}
+export async function confirmAudience(client, operationRef, emails, output) {
+    await client.initialize();
+    await client.call("isomorph_confirm_app_audience", { operationId: operationRef, emails });
+    output(emails.length ? `Isomorph recorded the app's audience: ${emails.length} colleague${emails.length === 1 ? "" : "s"}.` : "Isomorph recorded that only you can open the app for now.");
+    return getAppSetup(client, operationRef);
+}
+export async function listSecrets(client, operationRef) {
+    return (await getAppSetup(client, operationRef)).secrets;
+}
+/**
+ * The value is read by the CLI itself — from the terminal with echo off, or
+ * from stdin when the caller pipes it — and sent straight to Isomorph. It is
+ * never printed, never placed in the result, and never seen by an AI tool that
+ * merely launched this command.
+ */
+export async function setSecret(client, operationRef, input, output) {
+    await client.initialize();
+    const value = (await input.readValue()).replace(/\r?\n$/, "");
+    if (!value)
+        throw new CliError("SECRET_VALUE_REQUIRED", "No value was entered.", operationRef);
+    const result = structured(await client.call("isomorph_set_app_secret", { operationId: operationRef, name: input.name, value, scope: input.personal ? "personal" : "app", ...(input.personal ? { acknowledgePersonal: true } : {}) }));
+    output(`Isomorph stored the value for ${input.name}.${result.resumedOperationIds?.length ? " The paused deployment is resuming." : ""}`);
+    return { ...(result.secret ? { secret: result.secret } : {}), resumedOperationIds: result.resumedOperationIds ?? [] };
+}
+export async function dismissSecret(client, operationRef, name, output) {
+    await client.initialize();
+    const result = structured(await client.call("isomorph_dismiss_app_secret", { operationId: operationRef, name }));
+    output(`Isomorph recorded that ${name} is not needed.`);
+    return { ...(result.secret ? { secret: result.secret } : {}), resumedOperationIds: result.resumedOperationIds ?? [] };
+}
+/** Read one line from the controlling terminal with echo off, so the value
+ * never lands in shell history, scrollback, or a parent process's capture. */
+export async function readSecretFromTerminal(prompt) {
+    const { openSync, readSync, closeSync } = await import("node:fs");
+    let fd;
+    try {
+        fd = openSync("/dev/tty", "r+");
+    }
+    catch {
+        throw new CliError("NO_TERMINAL", "No terminal is available to enter the value. Pipe it on stdin with --value-stdin instead.");
+    }
+    const { writeSync } = await import("node:fs");
+    writeSync(fd, prompt);
+    const stty = await import("node:child_process");
+    try {
+        stty.execSync("stty -echo", { stdio: ["inherit", "ignore", "ignore"] });
+    }
+    catch { /* best effort: some terminals cannot toggle echo */ }
+    const chunks = [];
+    const buffer = Buffer.alloc(1);
+    try {
+        while (true) {
+            const read = readSync(fd, buffer, 0, 1, null);
+            if (read === 0 || buffer[0] === 0x0a)
+                break;
+            if (buffer[0] !== 0x0d)
+                chunks.push(Buffer.from(buffer));
+        }
+    }
+    finally {
+        try {
+            stty.execSync("stty echo", { stdio: ["inherit", "ignore", "ignore"] });
+        }
+        catch { /* ignore */ }
+        writeSync(fd, "\n");
+        closeSync(fd);
+    }
+    return Buffer.concat(chunks).toString("utf8");
+}
+export async function readSecretFromStdin() {
+    const chunks = [];
+    for await (const chunk of process.stdin)
+        chunks.push(Buffer.from(chunk));
+    return Buffer.concat(chunks).toString("utf8");
+}

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

@@ -0,0 +1,273 @@
+/** The one line for a failure that arrived with no detail at all. It is a
+ * statement about what this CLI knows, not a claim about what happened, so it
+ * is safe to print when — and only when — there is genuinely nothing to show. */
+export const NO_DETAIL = "Isomorph could not complete the request.";
+/**
+ * The failure as it was actually reported: the code it came with and the words
+ * it came with, redacted and capped. Nothing here infers what went wrong.
+ *
+ * Every non-`CliError` used to go through a keyword classifier over the message
+ * text, which did not merely lose the reason — it asserted false ones. A refusal
+ * reading "Isomorph has no saved app for this operation yet" matched on `save`
+ * and printed as "Saving to company code storage failed safely; nothing was
+ * deployed", sending a human after a code-storage failure that never happened
+ * and leaving an agent with nothing true to act on. Detail we do not have is
+ * now reported as detail we do not have.
+ */
+export function safeError(error) {
+    const code = error instanceof CliError ? error.code : "CLI_FAILED";
+    const raw = error instanceof Error ? error.message : typeof error === "string" ? error : "";
+    // The hint is a separate field rather than more sentence: it is often as long
+    // as the message, and appending it would push the reason itself past the cap.
+    const hint = error instanceof CliError && error.remediationHint ? redact(error.remediationHint) : "";
+    return { code, message: redact(raw) || NO_DETAIL, ...(hint ? { remediationHint: hint } : {}) };
+}
+/** Anything that must never reach a terminal, a log or an envelope. */
+const SECRETS = /https?:\/\/\S+|Bearer\s+\S+|(?:x-harbour|authorization|content-type)[^\n]*/gi;
+/** The bound on one reported string. It is the width of a terminal paragraph
+ * and of a field an agent has to read in full, and it is what
+ * `tests/cli-server-failure-detail.test.ts` holds the envelope to. This change
+ * does not raise it: a bigger fixed head-cap fails again on a longer message,
+ * because the problem is which end is kept, not how much. */
+const DETAIL_BOUND = 240;
+/** Marks where this CLI cut, so neither a human nor an agent reads the two
+ * retained halves as one continuous sentence. */
+const ELISION = " \u2026 ";
+/**
+ * Redact, then bound — keeping both ends.
+ *
+ * Bounding used to be `.slice(0, DETAIL_BOUND)`: keep the head, drop the tail.
+ * Server failure text is built the other way round. The boilerplate and the
+ * error class lead; the identifying token — the file, the command, the exit
+ * status — is last. Measured 2026-09-11 on one vibecoder session: a 317-char
+ * `transform.non-retryable: kit.check-failed:` refusal named `files-journey.mjs`
+ * at index 266, and a second, independently reproduced refusal the same day put
+ * it at index 278 of 295. Both sat past 240; neither filename was ever printed.
+ * The builder repaired the wrong file twice, at 2m23s and 2m12s of pipeline.
+ *
+ * The cap did not merely shorten those messages, it removed the answer and left
+ * a grammatical sentence behind, so two engineers with full log access read
+ * "...(real App Gateway" and went hunting in CloudWatch rather than registering
+ * that the CLI had cut it.
+ *
+ * So an over-long string now keeps BOTH ends — the head carries the error class,
+ * the tail carries the file and the exit status — with `ELISION` marking the
+ * gap. `DETAIL_BOUND` is unchanged, so nothing larger reaches a terminal or an
+ * envelope than before; the same characters are spent on both ends instead of
+ * one. Every string `safeError` reports goes through here, `remediationHint`
+ * included: hints have the same shape, and the command a builder has to run is
+ * the last one in them.
+ *
+ * This reads nothing and decides nothing from the words themselves — the split
+ * is positional. Stripping "known boilerplate prefixes" was considered and
+ * rejected for exactly that reason: it needs a maintained list of the server's
+ * phrasings, it deletes words the server actually said, and it is the kind of
+ * meaning-guessing the classifier deleted above was deleted for.
+ */
+function redact(value) {
+    const said = value.replace(SECRETS, "").replace(/\s+/g, " ").trim();
+    if (said.length <= DETAIL_BOUND)
+        return said;
+    const keep = DETAIL_BOUND - ELISION.length;
+    const headEnd = Math.floor(keep / 2);
+    return `${wholeWordsBefore(said, headEnd)}${ELISION}${wholeWordsAfter(said, said.length - (keep - headEnd))}`;
+}
+/** How far from a seam this will look for a word boundary. Bounded, so text
+ * with no spaces near the seam keeps its full share either way. */
+const SNAP = 24;
+/** `said.slice(0, end)` and `said.slice(start)`, backed off to a word boundary
+ * when the seam falls inside a word. The elision has to read as a cut: the
+ * engineer who read "(real App Gateway " went to CloudWatch rather than
+ * noticing the CLI had truncated it, and a seam that reads as a typo is the
+ * same failure in miniature. */
+function wholeWordsBefore(said, end) {
+    if (said[end] === " ")
+        return said.slice(0, end);
+    const at = said.lastIndexOf(" ", end);
+    return at > 0 && end - at <= SNAP ? said.slice(0, at) : said.slice(0, end);
+}
+function wholeWordsAfter(said, start) {
+    if (said[start - 1] === " ")
+        return said.slice(start);
+    const at = said.indexOf(" ", start);
+    return at >= 0 && at - start <= SNAP ? said.slice(at + 1) : said.slice(start);
+}
+/**
+ * What a failed command reports: the JSON envelope on stdout and the line on
+ * stderr. One place, so the human line and the envelope always carry the same
+ * reason and the same fix.
+ */
+export function failureEnvelope(error, cliVersion) {
+    const operationRef = error instanceof CliError ? error.operationRef : undefined;
+    const result = error instanceof CliError ? error.result : undefined;
+    return { schema: "isomorph.cli-result/1.0", cliVersion, status: "FAILED", operationStarted: Boolean(operationRef), ...(operationRef ? { operationRef } : {}), error: safeError(error), ...(result !== undefined ? { result } : {}) };
+}
+/**
+ * The envelope for a command that finished without error: `SUCCEEDED`, or
+ * `RUNNING` when the operation it followed is still in flight (the result's
+ * `outcome`, set by `follow`) — see `CliEnvelope.status`.
+ */
+export function operationEnvelope(result, operationRef, cliVersion) {
+    const running = result?.outcome === "running";
+    return { schema: "isomorph.cli-result/1.0", cliVersion, status: running ? "RUNNING" : "SUCCEEDED", operationStarted: true, operationRef, result };
+}
+/**
+ * The reason and the fix on one line, and — when the failure is a deployment
+ * or a promotion the result knows the version of — the stage line beneath it,
+ * so the builder and whoever reads the console or the email are looking at
+ * the same attempt.
+ */
+export function renderFailure(envelope) {
+    const error = envelope.error;
+    const result = (envelope.result ?? {});
+    const stages = ["production", "deployment"].filter(kind => result[kind]?.failure && result[kind]?.versionId).map(kind => `\n${stageLine(kind, result[kind])}`);
+    return `${error?.message ?? NO_DETAIL}${error?.remediationHint ? ` ${error.remediationHint}` : ""}${stages.join("")}\n`;
+}
+/**
+ * Server-supplied text on its way to a terminal, given exactly the treatment
+ * `safeError` gives the failure path: secrets stripped, whitespace collapsed,
+ * bounded at `DETAIL_BOUND` keeping both ends.
+ *
+ * `safeError` was `redact`’s only caller. `renderSummary` printed the server’s
+ * words straight from the payload, so on the success-shaped path — a deployment
+ * that reports a failure inside an otherwise-successful envelope, which is what
+ * `status` and `productionise` emit after a failed build — that text reached the
+ * terminal both unredacted and unbounded. A presigned URL, a bearer token or a
+ * forwarded header dump printed verbatim into whatever captured stdout, and a
+ * pathological message printed whole.
+ *
+ * That is the opposite defect to the one the tail-keeping change fixed: that
+ * one lost information, this one leaks and floods. One function and not a
+ * second implementation, because a second implementation is how the two paths
+ * came to differ at all.
+ */
+function said(value) {
+    return value ? redact(value) : "";
+}
+/**
+ * Human-readable stdout for runs without `--json`: the operation reference and
+ * whatever link or next step Isomorph reported, nothing internal.
+ *
+ * Every server-supplied string printed here goes through `said`. What does not
+ * is listed below, because each is a value whose whole job is to be reproduced
+ * verbatim, and each would be destroyed by the very rules that make redaction
+ * worth doing:
+ *
+ *  - `protectedUrl`, `productionUrl` — `SECRETS` strips URLs, and these two are
+ *    the app’s address: the thing the builder ran the command to get.
+ *  - `operationRef` — the handle every later `--operation` needs, and already
+ *    exempt on the failure path: `safeError` redacts the message and the hint,
+ *    never the reference they travel with. The same policy on both paths.
+ *  - `deployment.versionId`, `production.versionId` — printed only on a failed
+ *    stage, and for the same reason: it is the reference the console and the
+ *    email carry for that attempt, and a bounded or reworded one names nothing.
+ *  - `secrets.asks[].name` and `.prefilledFromPath` — identifiers, not prose. A
+ *    secret named `AUTHORIZATION_TOKEN` matches the header pattern and would be
+ *    erased whole, printing `Secret : needs a value`; the path is read off the
+ *    local checkout rather than sent by the server.
+ *  - `audience.emails` — the builder’s own confirmed list, echoed back. A
+ *    240-character bound over a joined list silently drops members, which is
+ *    the information loss the tail-keeping change was about.
+ *  - `ask.status`, `ask.scope`, `secrets.available`, `audience.confirmed` and
+ *    the three mapped `pending` steps — compared against fixed literals, so
+ *    only Isomorph’s own words ever print. An unmapped `pending` step is the
+ *    server’s own id, so that one does go through `said`.
+ *
+ * `deployment.message` and `production.message` are declared on the payload and
+ * never printed here; nothing routes them, and a line that printed one would
+ * need `said` like the rest. The `--json` envelope is unchanged: it carries the
+ * raw structured result by design and this is about what is printed. Whether
+ * the envelope should be redacted too is a decision about that contract, not
+ * one to take in the renderer.
+ */
+export function renderSummary(envelope) {
+    const lines = [];
+    const result = (envelope.result ?? {});
+    if (envelope.operationRef)
+        lines.push(`Operation reference: ${envelope.operationRef}`);
+    const verification = said(result.verification);
+    const assurance = said(result.assuranceLevel);
+    if (verification)
+        lines.push(`Saved app: ${verification}${assurance ? ` (${assurance})` : ""}`);
+    if (result.production) {
+        lines.push(stageLine("production", result.production));
+        if (result.production.failure?.message)
+            lines.push(`  ${failureText(result.production.failure)}`);
+    }
+    if (result.deployment) {
+        lines.push(stageLine("deployment", result.deployment));
+        if (result.deployment.failure?.message)
+            lines.push(`  ${failureText(result.deployment.failure)}`);
+    }
+    // Gated on the redacted value rather than the raw one, so guidance that is
+    // nothing but a link falls through to the next step instead of printing a
+    // label with nothing after it.
+    const waiting = said(result.waiting?.plainEnglish);
+    const nextStep = said(result.nextStep);
+    if (waiting)
+        lines.push(`Action needed: ${waiting}`);
+    else if (nextStep)
+        lines.push(`Next: ${nextStep}`);
+    const setup = envelope.result?.setup;
+    const secrets = setup?.secrets ?? envelope.result?.secrets;
+    if (setup?.profile) {
+        lines.push(`App name: ${said(setup.profile.displayName) || "(none)"}${setup.profile?.confirmed ? " (confirmed)" : setup.profile?.suggested?.displayName ? ` — suggested: ${said(setup.profile.suggested.displayName)}` : " (not confirmed)"}`);
+        if (setup.profile?.description || setup.profile?.suggested?.description)
+            lines.push(`Description: ${said(setup.profile?.confirmed ? setup.profile.description : setup.profile?.suggested?.description ?? setup.profile?.description)}`);
+        if (setup.audience?.available === false)
+            lines.push(`Audience: ${said(setup.audience.plainEnglish) || "console only"}`);
+        else
+            lines.push(`Audience: ${setup.audience?.confirmed ? (setup.audience.emails?.length ? setup.audience.emails.join(", ") : "only you") + " (confirmed)" : "not confirmed"}`);
+    }
+    if (secrets) {
+        if (secrets.available === false)
+            lines.push(`Secrets: ${said(secrets.plainEnglish) || "console only"}`);
+        else if (!secrets.asks?.length)
+            lines.push("Secrets: none asked for");
+        else
+            for (const ask of secrets.asks)
+                lines.push(`Secret ${ask.name}: ${ask.status === "UNSET" ? "needs a value" : ask.status === "SET" ? "set" : "not needed"}${ask.scope === "personal" ? " (personal)" : ""}${ask.prefilledFromPath ? ` (from ${ask.prefilledFromPath})` : ""}`);
+    }
+    // productionise carries only the open steps; the setup commands carry the full view.
+    const openSteps = setup?.pending?.length ? setup.pending.map(step => step === "confirm_app_profile" ? "confirm the app's name and description" : step === "confirm_app_audience" ? "confirm who may open it" : step === "provide_secrets" ? "provide the secrets it asked for" : said(step)) : [];
+    if (openSteps.length)
+        lines.push(`Still needed: ${openSteps.join("; ")}${envelope.result.setup?.plainEnglish && !setup?.profile ? ` — run \`isomorph setup --operation ${envelope.operationRef ?? "<reference>"}\`` : ""}`);
+    else if (setup?.profile)
+        lines.push("Setup complete.");
+    return `${lines.join("\n")}\n`;
+}
+/**
+ * `Preview deployment: FAILED (fourier#app#preview#000001) — <url>`. On a
+ * failure the version is the reference the console's releases tab and the
+ * email carry, printed so everyone is looking at the same attempt. It is an
+ * identifier, exempt from `said` for the reason the operation reference is.
+ */
+function stageLine(kind, stage) {
+    const [label, state, url] = kind === "production" ? ["Production", stage.state, stage.productionUrl] : ["Preview deployment", stage.status ?? stage.state, stage.protectedUrl];
+    return `${label}: ${said(state)}${stage.failure && stage.versionId ? ` (${stage.versionId})` : ""}${url ? ` — ${url}` : ""}`;
+}
+/**
+ * The message, then the hint, each redacted and bounded on its own — exactly
+ * as `safeError` bounds them separately, so the hint never spends the
+ * message's budget. `|| NO_DETAIL` for the reason `safeError` has it: redaction
+ * can empty a string, and a failure reported as two spaces is worse than one
+ * that says plainly this CLI has nothing to show.
+ */
+function failureText(failure) {
+    const hint = said(failure.remediationHint);
+    return `${said(failure.message) || NO_DETAIL}${hint ? ` ${hint}` : ""}`;
+}
+export class CliError extends Error {
+    code;
+    operationRef;
+    remediationHint;
+    result;
+    /** `result` becomes the envelope's `result`: what the command knew about the operation when it failed. */
+    constructor(code, message, operationRef, remediationHint, result) {
+        super(message);
+        this.code = code;
+        this.operationRef = operationRef;
+        this.remediationHint = remediationHint;
+        this.result = result;
+    }
+}