@amerged/ohmyhost-mcp 0.1.22 → 0.1.24

package/src/apps/product-cli/{cli.ts → src/cli.ts}

@@ -9,6 +9,7 @@ import {
 import { assertOrganizationAccount } from "@ohmyhost/contracts/credit-pricing";
 import { assertDatabaseCompute } from "@ohmyhost/contracts/database-compute";
 import cliPackage from "../package.json" with { type: "json" };
+import { isUserSecretName } from "@ohmyhost/contracts/secret-names";
 import {
   assertProjectContext,
   assertProjectNotesReceipt,
@@ -72,6 +73,7 @@ import {
   parseGithubOrganizationConnectionStatus,
   parseCloudflareDnsAuthorizationStatus,
   parseDeploymentPlan,
+  parseProjectDataChangePlan,
   parseCurrentIdentity,
   parseOrganization,
   type PublicAccount,
@@ -307,7 +309,7 @@ const HELP_USAGE = Object.freeze({
     "ohmyhost export get EXPORT_ULID --project ULID --json (poll the original job; signed ZIP download lasts 24 hours)",
   "credits account": "ohmyhost credits account --organization ULID --json",
   "referral link":
-    "ohmyhost referral link --organization ULID --json (the workspace's link to share; a new user who signs up through it starts with a free Paid month and 1,000 credits, and their first payment gives this workspace the same)",
+    "ohmyhost referral link --organization ULID --json (the workspace's link to share; a new user whose first workspace comes from it starts with 30 days of Paid and 1,000 credits, and its first payment gives this workspace 1,000 credits plus 30 days of Paid unless a subscription or an unbounded grant already covers it)",
   "credits balance": "ohmyhost credits balance --organization ULID --json",
   "billing recharge get": "ohmyhost billing recharge get --organization ULID --json",
   "billing recharge set":
@@ -340,7 +342,11 @@ const HELP_USAGE = Object.freeze({
   "feedback submit":
     "ohmyhost feedback submit --organization ULID --kind bug|issue|feature_request --title TITLE --description REDACTED_REPORT [--project ULID] [--environment ULID] [--operation ULID] [--error-code CODE] [--client-version VERSION] --idempotency-key KEY --json",
   "project create":
-    "ohmyhost project create --organization ULID --name NAME [--data-mode shared|isolated] [--dev-access-mode protected|public] [--region us|eu] --idempotency-key KEY --json (the region is chosen once: us is the default, eu places the database, files and builds in the EU; it cannot be changed later)",
+    "ohmyhost project create --organization ULID --name NAME [--data-mode shared|isolated] [--dev-access-mode protected|public] [--region us|eu] --idempotency-key KEY --json (data mode is optional and defaults to shared; later assignments use project data plan/change without copying data; the region is chosen once: us is the default, eu places the database, files and builds in the EU; it cannot be changed later)",
+  "project data plan":
+    "ohmyhost project data plan --project ULID --change isolate_prod_keeps_data|isolate_dev_keeps_data|share_prod_keeps_data|reset_dev --json (shared is the optional creation default; review which data is kept or deleted; no data is copied)",
+  "project data change":
+    "ohmyhost project data change --project ULID --change isolate_prod_keeps_data|isolate_dev_keeps_data|share_prod_keeps_data|reset_dev --if-match ETAG --confirmation-token TOKEN --idempotency-key KEY --yes [--wait] --json (Owner only; use the reviewed plan's guards and the same key after uncertainty; no data is copied)",
   "project list": "ohmyhost project list [--cursor ULID] [--limit LIMIT] --json",
   "project context": "ohmyhost project context --project ULID --json",
   "project notes set":
@@ -356,7 +362,7 @@ const HELP_USAGE = Object.freeze({
     "ohmyhost project dev-access mode --project ULID --mode protected|public --idempotency-key KEY --yes --json",
   "project flag status": "ohmyhost project flag status --project ULID --json",
   "project flag set":
-    "ohmyhost project flag set --project ULID --enabled true|false --idempotency-key KEY --json (shows the small Powered by ohmyho.st flag on the production site; while it shows, a Free workspace may connect its own domain without the domain fee and each Paid period adds 250 credits)",
+    "ohmyhost project flag set --project ULID --enabled true|false --idempotency-key KEY --json (shows the small Powered by ohmyho.st flag on the production site; while it shows, this project's custom domain uses no domain credits and also works on Free, and each Paid period bought through Stripe adds 250 credits to the workspace, however many projects show the flag)",
   "project handle check":
     "ohmyhost project handle check --handle HANDLE --json (is this address free? answers with a reason and free alternatives; the address becomes HANDLE.check.omh.st)",
   "project handle set":
@@ -454,6 +460,90 @@ export const cliMetadataResult = (kind: "help" | "version", topic?: string): Cli
       })
     : success("version", { status: "succeeded", cli_version: CLI_VERSION });
 
+/**
+ * How to correct a command the parser refused. It quotes the command's usage line only, never an
+ * argument, so a secret typed into the wrong place is not echoed back.
+ */
+export const invalidCommandAction = (argv: readonly string[], commandPrefix: string): string => {
+  const label = recognizedCommandLabel(argv);
+  if (label === "secret set" || label === "secret delete") {
+    const action = label === "secret set" ? "set" : "delete";
+    const at = argv.findIndex((value, index) => value === "secret" && argv[index + 1] === action);
+    const name = at < 0 ? undefined : argv[at + 2];
+    if (name !== undefined && !isUserSecretName(name, action))
+      return action === "set"
+        ? "Choose a customer secret name of at most 128 uppercase letters, digits and underscores, starting with a letter. OHMYHOST_* and DATABASE_URL, HYPERDRIVE, BETTER_AUTH_SECRET, BETTER_AUTH_URL, ASSETS, FILES, IMAGES and STORAGE are reserved for the platform. Rename the application's own variable and its source references; platform bindings are installed automatically. Nothing was sent; changing only the idempotency key will not help."
+        : "Choose an existing customer secret name of at most 128 uppercase letters, digits and underscores, starting with a letter. The installed platform keys OHMYHOST_STORAGE_KEY, OHMYHOST_MAIL_KEY and BETTER_AUTH_SECRET cannot be deleted. Older reserved-name collisions can be removed with secret delete; deployed platform keys stay managed by ohmyho.st. Nothing was sent; changing only the idempotency key will not help.";
+  }
+  const usage = Object.hasOwn(HELP_USAGE, label)
+    ? HELP_USAGE[label as CustomerCommandLabel].split("\n")[0]
+    : undefined;
+  if (usage === undefined)
+    return "Unknown command; nothing was sent. 'ohmyhost --help --json' lists every command with its flags. If a documented command is missing, this CLI is older than https://ohmyho.st/client-release.json: install the published version.";
+  // A required --project may come from this checkout's link; an optional one never needs it.
+  const linkable = /(?:^|\s)--project ULID/u.test(usage) && !argv.includes("--project");
+  return `The arguments of '${label}' are invalid or incomplete; nothing was sent. Usage: ${usage}.${
+    linkable
+      ? ` --project may be omitted only inside a directory linked with '${commandPrefix} link' for this OHMYHOST_ENVIRONMENT; otherwise pass --project ULID.`
+      : ""
+  }`;
+};
+
+/** The next step after an unexpected client failure; the stderr diagnostic line identifies it. */
+export const INTERNAL_ERROR_ACTION =
+  "The ohmyhost client stopped on an unexpected error; the stderr line starting with [ohmyhost: identifies it. Compare 'ohmyhost --version' with https://ohmyho.st/client-release.json and install the published client if it is older, then run the same command again with the same --idempotency-key. If the current client fails the same way, report it with feedback submit (kind bug, error code internal_error) and quote that stderr line.";
+
+/** The local credential store or saved-login index failed; a sandbox is the usual cause. */
+export const CREDENTIAL_STORE_UNAVAILABLE_ACTION =
+  "This computer's credential store (for example macOS Keychain or Windows Credential Manager) or the saved-login list in ~/.ohmyhost/profiles could not be read or written; nothing was changed. If the agent runs in a sandbox, run the command with access to them before asking the customer to sign in again. If the store is locked, ask the customer to unlock it, then run the command again. On a server, container or CI runner without a credential store, do not run login: load OHMYHOST_TOKEN from a private env file with a token from the portal's API Tokens page.";
+
+const RESPONSE_CONTRACT_INVALID_ACTION =
+  "The ohmyho.st API answered in a form this client version does not accept, usually because the client is older than the service. Compare 'ohmyhost --version' with https://ohmyho.st/client-release.json; if it is older, install the published CLI and MCP and reload MCP. Then run the same command again with the same --idempotency-key: the change may already have been applied. If the current version answers this too, report it with feedback submit (kind bug, error code response_contract_invalid).";
+
+const REQUEST_TIMEOUT_ACTION =
+  "The ohmyho.st API did not answer within 30 seconds. Run the same command again with the same --idempotency-key; the change may already be under way, and a new key could apply it twice.";
+
+const LOGOUT_UNCONFIRMED_ACTION =
+  "The saved login was removed from this computer, but ohmyho.st did not confirm that its session ended. Running logout again cannot retry this, because the login is gone; do not sign in again just to revoke it. Tell the customer the session end was not confirmed.";
+
+const STATEMENT_FILE_INVALID_ACTION =
+  "Put one INSERT, UPDATE or DELETE statement that starts with that keyword (no leading comment or WITH), UTF-8, at most 64 KiB, in the file named by --statement-file, then rerun with the same --idempotency-key.";
+
+/** The command that signs a saved login in again as the same user, organization and alias. */
+const signInCommand = (commandPrefix: string, profile: LocalProfile | undefined): string =>
+  profile === undefined
+    ? `${commandPrefix} login --json`
+    : `${commandPrefix} login${
+        profile.organizationId === null ? "" : ` --organization ${profile.organizationId}`
+      } --user ${profile.userId} --profile-name ${profile.name} --json`;
+
+/** The sign-in service ended a saved login, which was then removed from this computer. */
+export const endedLoginAction = (
+  commandPrefix: string,
+  profile: LocalProfile | undefined,
+): string =>
+  `The sign-in of ${
+    profile === undefined
+      ? "this computer's saved login"
+      : `saved login ${profile.name} (user ${profile.userId}${
+          profile.organizationId === null ? "" : `, organization ${profile.organizationId}`
+        })`
+  } ended and it was removed. Run '${signInCommand(commandPrefix, profile)}' to sign it in again.`;
+
+/** Renewing a saved login failed without ending it; it was kept. */
+export const refreshFailedAction = (
+  commandPrefix: string,
+  profile: LocalProfile | undefined,
+): string =>
+  `Renewing the saved login${profile === undefined ? "" : ` ${profile.name}`} at the sign-in service failed. Run the same command again in a minute, with the same --idempotency-key if it has one. If it fails again, run '${signInCommand(commandPrefix, profile)}' and send the customer the link and code.`;
+
+/** The flags a failed login is repeated with; the boundary proof needs brace-free signatures. */
+interface LoginFlags {
+  readonly organizationId: string | undefined;
+  readonly userId: string | undefined;
+  readonly profileName: string | undefined;
+}
+
 class ProductCliFailure extends Error {
   public constructor(
     public readonly exitCode: number,
@@ -489,7 +579,7 @@ export class ProductCli {
           2,
           "invalid_command",
           false,
-          "Check 'ohmyhost --help'.",
+          invalidCommandAction(argv, this.dependencies.commandPrefix),
         );
       }
       this.recordDiagnostic({
@@ -497,7 +587,13 @@ export class ProductCli {
         subsystem: "parser",
         errorKind: "unexpected",
       });
-      return failure("unknown", 1, "internal_error", false, "Retry the command.");
+      return failure(
+        recognizedCommandLabel(argv),
+        1,
+        "internal_error",
+        false,
+        INTERNAL_ERROR_ACTION,
+      );
     }
     return this.runCommand(command, signal);
   }
@@ -788,6 +884,9 @@ export class ProductCli {
         });
       }
       if (command.kind === "project-create") return await this.createProject(command, signal);
+      if (command.kind === "project-data-plan") return await this.planProjectData(command, signal);
+      if (command.kind === "project-data-change")
+        return await this.changeProjectData(command, signal);
       if (command.kind === "project-list") return await this.listProjects(command, signal);
       if (command.kind === "project-handle-check")
         return await this.checkProjectHandle(command, signal);
@@ -871,23 +970,21 @@ export class ProductCli {
         );
       }
       if (command.kind === "database-write") {
-        const file = await open(command.statementFile, "r"),
-          buffer = Buffer.alloc(65_537);
-        let statement: string;
+        const statement = await readStatementFile(command.statementFile);
         try {
-          const stat = await file.stat();
-          if (!stat.isFile() || stat.size > 65_536) throw new InvalidCommandError();
-          let length = 0;
-          while (length < buffer.length) {
-            const read = await file.read(buffer, length, buffer.length - length, null);
-            if (read.bytesRead === 0) break;
-            length += read.bytesRead;
-          }
-          if (length > 65_536) throw new InvalidCommandError();
-          statement = new TextDecoder("utf-8", { fatal: true }).decode(buffer.subarray(0, length));
-        } finally {
-          buffer.fill(0);
-          await file.close();
+          // The statement alone decides whether the file is usable; its parameters are checked next.
+          parseProjectDatabaseWrite({
+            environment: command.environment,
+            statement,
+            parameters: [],
+          });
+        } catch {
+          throw new ProductCliFailure(
+            2,
+            "statement_file_invalid",
+            false,
+            STATEMENT_FILE_INVALID_ACTION,
+          );
         }
         const body = parseProjectDatabaseWrite({
           environment: command.environment,
@@ -1173,7 +1270,13 @@ export class ProductCli {
         expiresAt,
       };
       const account = await this.dependencies.accountProfile(async () => signedIn.accessToken);
-      if (!isProfileUserId(account.userId)) throw this.unverifiedLogin();
+      // A failed verification repeats this login with the flags it was given.
+      const loginFlags = {
+        organizationId,
+        userId: expectedUserId,
+        profileName: this.dependencies.profileName,
+      };
+      if (!isProfileUserId(account.userId)) throw this.unverifiedLogin(loginFlags);
       if (expectedUserId !== undefined && account.userId !== expectedUserId)
         throw new ProductCliFailure(
           4,
@@ -1206,11 +1309,11 @@ export class ProductCli {
         scopedId === null
           ? null
           : account.organizations.find((candidate) => candidate.id === scopedId);
-      if (organization === undefined) throw this.unverifiedLogin();
+      if (organization === undefined) throw this.unverifiedLogin(loginFlags);
       try {
         assertVerifiedLogin(identity, account.userId, scopedId);
       } catch (error) {
-        if (error instanceof AccountVerificationError) throw this.unverifiedLogin();
+        if (error instanceof AccountVerificationError) throw this.unverifiedLogin(loginFlags);
         throw error;
       }
       const login = {
@@ -1276,12 +1379,16 @@ export class ProductCli {
   }
 
   /** The provider answered with another account than the one this login requested. */
-  private unverifiedLogin(): ProductCliFailure {
+  private unverifiedLogin(flags: LoginFlags): ProductCliFailure {
     return new ProductCliFailure(
       4,
       "login_verification_failed",
       true,
-      `The signed-in account could not be verified; nothing was saved. Run '${this.dependencies.commandPrefix} login --json' again.`,
+      `The signed-in account could not be verified; nothing was saved. Run '${this.dependencies.commandPrefix} login${
+        flags.organizationId === undefined ? "" : ` --organization ${flags.organizationId}`
+      }${flags.userId === undefined ? "" : ` --user ${flags.userId}`}${
+        flags.profileName === undefined ? "" : ` --profile-name ${flags.profileName}`
+      } --json' again with the same flags and send the customer the new link and code.`,
     );
   }
 
@@ -1317,7 +1424,12 @@ export class ProductCli {
         this.dependencies.lifecycleTimeoutMs,
       );
     } catch (error) {
-      if (error instanceof AccountVerificationError) throw this.unverifiedLogin();
+      if (error instanceof AccountVerificationError)
+        throw this.unverifiedLogin({
+          organizationId: organization.id,
+          userId: profile.userId,
+          profileName: profile.name,
+        });
       if (!(error instanceof ProfileOrganizationFixedError)) throw error;
       throw new ProductCliFailure(
         2,
@@ -1375,21 +1487,12 @@ export class ProductCli {
           "Remote token revocation is not available in this release.",
         );
       }
+      // The login is already gone, so nothing this computer holds can repeat the revocation.
       if (isTimeout(revocationError)) {
-        throw new ProductCliFailure(
-          8,
-          "request_timeout",
-          true,
-          "Remote revocation timed out; local credentials were removed.",
-        );
+        throw new ProductCliFailure(8, "request_timeout", false, LOGOUT_UNCONFIRMED_ACTION);
       }
       if (revocationError instanceof LifecycleTransportError) {
-        throw new ProductCliFailure(
-          6,
-          "token_revocation_failed",
-          true,
-          "Remote revocation failed; the local credential was removed.",
-        );
+        throw new ProductCliFailure(6, "token_revocation_failed", false, LOGOUT_UNCONFIRMED_ACTION);
       }
       throw revocationError;
     }
@@ -1446,6 +1549,38 @@ export class ProductCli {
     return success("operation reconcile", { status: "accepted", reconciliation });
   }
 
+  private async planProjectData(
+    command: Extract<ProductCliCommand, { kind: "project-data-plan" }>,
+    signal: AbortSignal,
+  ): Promise<CliResult> {
+    const api = await this.authenticatedApi(command.credentialStore, signal);
+    return success("project data plan", {
+      status: "planned",
+      plan: parseProjectDataChangePlan(
+        await api.planProjectDataChange({ projectId: command.projectId, change: command.change }),
+      ),
+    });
+  }
+  private async changeProjectData(
+    command: Extract<ProductCliCommand, { kind: "project-data-change" }>,
+    signal: AbortSignal,
+  ): Promise<CliResult> {
+    const api = await this.authenticatedApi(command.credentialStore, signal);
+    let operation = parseOperation(
+      await api.createProjectDataChange({
+        projectId: command.projectId,
+        change: command.change,
+        ifMatch: command.ifMatch,
+        confirmationToken: command.confirmationToken,
+        idempotencyKey: command.idempotencyKey,
+      }),
+    );
+    if (command.wait) operation = await this.waitForOperation(api, operation, signal);
+    return success("project data change", {
+      status: command.wait ? "completed" : "accepted",
+      operation,
+    });
+  }
   private async createProject(
     command: Extract<ProductCliCommand, { kind: "project-create" }>,
     signal: AbortSignal,
@@ -1833,13 +1968,33 @@ export class ProductCli {
               environment: command.environment,
             }),
           );
-    let operation = parseOperation(
-      await api.createDeployment({
+    let accepted: unknown;
+    try {
+      accepted = await api.createDeployment({
         projectId: command.projectId,
         planId: plan === null ? String(command.planId) : String(plan["id"]),
         idempotencyKey: command.idempotencyKey,
-      }),
-    );
+      });
+    } catch (error) {
+      // A rerun of --commit re-plans, so its key meets a new plan ID; a new key would build the
+      // same commit a second time. The deployment the key started is followed instead.
+      const reused = plan === null ? undefined : reusedKeyProblem(error);
+      if (reused === undefined) throw error;
+      return failure(
+        "deploy",
+        7,
+        reused.code,
+        false,
+        `This key already started a deployment from an earlier run of this command; a new key would build the same commit again. Run 'ohmyhost project status --project ${command.projectId} --json' and follow latest_operation with 'ohmyhost operation get OPERATION_ULID --json'.`,
+        undefined,
+        undefined,
+        reused.requestId,
+        reused.docsUrl,
+        undefined,
+        reused.message,
+      );
+    }
+    let operation = parseOperation(accepted);
     if (command.wait) operation = await this.waitForOperation(api, operation, signal);
     // Dev access follows the project-selected mode; the clean URL alone is insufficient when protected.
     const notes =
@@ -1861,35 +2016,62 @@ export class ProductCli {
     signal: AbortSignal,
   ): Promise<CliResult> {
     const api = await this.authenticatedApi(command.credentialStore, signal);
+    // The operation read answers an unknown, foreign or mistyped ID before any stream opens.
+    let operation = parseOperation(await api.getOperation(command.operationId));
     let eventCount = 0;
-    for await (const event of await api.streamOperationEvents(command.operationId, signal)) {
-      const parsed = parseOperationEvent(event);
-      this.dependencies.operationEventSink?.write(`${JSON.stringify(parsed)}\n`);
-      eventCount += 1;
-      if (
-        parsed["type"] === "OperationSucceeded" ||
-        parsed["type"] === "OperationFailed" ||
-        parsed["type"] === "OperationCancelled"
-      ) {
-        break;
+    let lastEventId: string | undefined;
+    for (let connection = 0; connection < OPERATION_STREAM_CONNECTIONS; connection += 1) {
+      if (connection > 0)
+        await this.dependencies.waitUntil(
+          new Date(this.dependencies.now().getTime() + 1_000),
+          signal,
+        );
+      const events =
+        lastEventId === undefined
+          ? await api.streamOperationEvents(command.operationId, signal)
+          : await api.streamOperationEvents(command.operationId, signal, lastEventId);
+      for await (const event of events) {
+        const parsed = parseOperationEvent(event);
+        this.dependencies.operationEventSink?.write(`${JSON.stringify(parsed)}\n`);
+        eventCount += 1;
+        lastEventId = String(parsed["event_id"]);
+        if (
+          parsed["type"] === "OperationSucceeded" ||
+          parsed["type"] === "OperationFailed" ||
+          parsed["type"] === "OperationCancelled"
+        )
+          return success("logs", { status: "completed", event_count: eventCount });
       }
+      throwIfAborted(signal);
+      // The server also closes a stream without a final event, for example when an interactive
+      // sign-in expires. Only the operation itself says whether it ended meanwhile.
+      operation = parseOperation(await api.getOperation(command.operationId));
+      if (operation.state !== "queued" && operation.state !== "running")
+        return success("logs", { status: "completed", event_count: eventCount, operation });
     }
-    return success("logs", { status: "completed", event_count: eventCount });
+    throw new ProductCliFailure(
+      8,
+      "operation_stream_ended",
+      true,
+      `The event stream ended before operation ${command.operationId} finished, and it is still running; nothing was cancelled. Poll 'ohmyhost operation get ${command.operationId} --json' about every 60 seconds until it is succeeded, failed or cancelled.`,
+      operation,
+    );
   }
   private async deploymentLogs(
     command: Extract<ProductCliCommand, { kind: "deployment-logs" }>,
     signal: AbortSignal,
   ): Promise<CliResult> {
     const api = await this.authenticatedApi(command.credentialStore, signal);
-    let count = 0;
-    for await (const event of await api.streamDeploymentLogs(
-      { projectId: command.projectId, deploymentId: command.deploymentId },
-      signal,
-    )) {
-      this.dependencies.operationEventSink?.write(`${JSON.stringify(event)}\n`);
-      count += 1;
-    }
-    return success("deployment logs", { status: "completed", event_count: count });
+    // The diagnostics are one bounded page; a plain read answers a missing deployment at once,
+    // where its event stream retried a 404 without end.
+    const page = await api.getDeploymentLogs({
+      projectId: command.projectId,
+      deploymentId: command.deploymentId,
+      limit: 100,
+    });
+    for (const item of page.items)
+      this.dependencies.operationEventSink?.write(`${JSON.stringify(item)}\n`);
+    return success("deployment logs", { status: "completed", event_count: page.items.length });
   }
 
   private async planRollback(
@@ -2016,7 +2198,7 @@ export class ProductCli {
           )
         : secret;
       return success("secret set", {
-        status: command.wait ? "ready" : "stored",
+        status: command.wait && completed.delivery_state === "ready" ? "ready" : "stored",
         secret: completed,
       });
     } finally {
@@ -2047,7 +2229,7 @@ export class ProductCli {
         )
       : deleted;
     return success("secret delete", {
-      status: command.wait ? "ready" : deleted.status,
+      status: command.wait && delivery.delivery_state === "ready" ? "ready" : deleted.status,
       secret: { name: deleted.name, ...secretDeliveryProjection(delivery) },
     });
   }
@@ -2069,13 +2251,16 @@ export class ProductCli {
           10,
           "secret_delivery_failed",
           true,
-          "Inspect secret metadata and deployment logs, then retry reconciliation.",
+          `The secret is saved, but delivering it to the running app failed (last_error in 'ohmyhost secret list --project ${projectId} --environment ${environmentId} --json'). Do not set the value again: ohmyho.st retries delivery automatically, and the next deployment of this environment also delivers it. Read secret list again in a few minutes; if delivery_state stays failed, report last_error with feedback submit (kind bug, error code secret_delivery_failed).`,
         );
       }
+      // Before an environment's first deployment nothing runs to deliver to: the value arrives
+      // with that deployment, so waiting could only time out.
       if (
-        page.delivery_state === "ready" &&
-        page.desired_generation >= desiredGeneration &&
-        page.applied_generation >= desiredGeneration
+        page.delivery_state === "not_deployed" ||
+        (page.delivery_state === "ready" &&
+          page.desired_generation >= desiredGeneration &&
+          page.applied_generation >= desiredGeneration)
       ) {
         // Every item carries the environment's generations; only the item with the stored
         // secret's name describes the secret that was just set. A deletion has no item left
@@ -2099,7 +2284,7 @@ export class ProductCli {
       8,
       "secret_delivery_wait_timeout",
       true,
-      "Run 'ohmyhost secret list --json' to inspect delivery metadata.",
+      `The secret is saved, but it had not reached the running app after about 2 minutes. Read 'ohmyhost secret list --project ${projectId} --environment ${environmentId} --json': pending means delivery is still under way, and not_deployed means it arrives with the first deployment. Do not set the value again.`,
     );
   }
 
@@ -2135,7 +2320,7 @@ export class ProductCli {
         8,
         "operation_wait_timeout",
         true,
-        `Run 'ohmyhost operation get ${operation.id} --json' to inspect the existing operation before resubmitting a mutation.`,
+        `The operation is still running; this command stopped waiting after about 2 minutes and cancelled nothing. Poll 'ohmyhost operation get ${operation.id} --json' about every 60 seconds until it is succeeded, failed or cancelled. Do not submit the same change again; a new key starts a second operation.`,
         operation,
       );
     if (operation.state === "failed" && operation.error !== undefined)
@@ -2181,8 +2366,14 @@ export class ProductCli {
     } catch (error) {
       if (!(error instanceof TokenRefreshRejectedError)) throw error;
       // The provider ended this login; only this saved login is removed.
+      const ended = this.#profile;
       await this.forgetLogin(store);
-      throw new ProductCliFailure(5, "authentication_required", false, this.loginAction());
+      throw new ProductCliFailure(
+        5,
+        "authentication_required",
+        false,
+        endedLoginAction(this.dependencies.commandPrefix, ended),
+      );
     }
     if (refresh.refreshed) await store.replace(refresh.credential);
     return refresh.credential.accessToken;
@@ -2239,14 +2430,14 @@ export class ProductCli {
         );
       }
       if (isTimeout(error)) {
-        throw new ProductCliFailure(8, "request_timeout", true, "Retry the command.");
+        throw new ProductCliFailure(8, "request_timeout", true, REQUEST_TIMEOUT_ACTION);
       }
       if (error instanceof LifecycleTransportError) {
         throw new ProductCliFailure(
           5,
           "token_refresh_failed",
           true,
-          "Run 'ohmyhost login' if retrying does not succeed.",
+          refreshFailedAction(this.dependencies.commandPrefix, this.#profile),
         );
       }
       throw error;
@@ -2322,10 +2513,16 @@ const classifyFailure = (
   actingAs?: Readonly<Record<string, unknown>>,
 ): CliResult => {
   if (signal.aborted || isCancellation(error)) {
-    return failure(command, 130, "command_cancelled", true, "Run the command again.");
+    return failure(
+      command,
+      130,
+      "command_cancelled",
+      true,
+      "The command was stopped by an interrupt or termination signal, for example the shell's command timeout, before it finished. Run it again with the same --idempotency-key; a change may already be under way. Give login and commands with --wait or --follow several minutes, or run them in the background.",
+    );
   }
   if (isTimeout(error)) {
-    return failure(command, 8, "request_timeout", true, "Retry the command.");
+    return failure(command, 8, "request_timeout", true, REQUEST_TIMEOUT_ACTION);
   }
   if (error instanceof ProductCliFailure) {
     return failure(
@@ -2343,25 +2540,45 @@ const classifyFailure = (
       2,
       "secret_input_invalid",
       false,
-      "Pipe a non-empty UTF-8 value of at most 5120 bytes through standard input.",
+      command === "export create"
+        ? "Pipe the ZIP password through standard input: non-blank UTF-8 of at most 1024 bytes. A final line break becomes part of the password."
+        : "Pipe a non-empty UTF-8 value of at most 5120 bytes through standard input.",
     );
   }
   if (error instanceof WorkosContractError) {
     if (error.code === "access_denied") {
-      return failure(command, 4, "device_authorization_denied", false, "Run login again.");
+      return failure(
+        command,
+        4,
+        "device_authorization_denied",
+        false,
+        "The customer declined the sign-in in the browser; nothing was saved. Ask the customer whether to sign in, then run the same login command again and send them the new link and code.",
+      );
     }
     if (error.code === "expired_token") {
-      return failure(command, 4, "device_authorization_expired", false, "Run login again.");
+      return failure(
+        command,
+        4,
+        "device_authorization_expired",
+        false,
+        "Nobody finished the sign-in within 30 minutes; nothing was saved. Run the same login command again and send the customer the new link and code at once.",
+      );
     }
-    return failure(command, 4, "device_authorization_failed", true, "Run login again.");
+    return failure(
+      command,
+      4,
+      "device_authorization_failed",
+      true,
+      "The sign-in service answered unexpectedly; nothing was saved. Run the same login command again; if it fails twice more, ask the customer to try again later.",
+    );
   }
   if (error instanceof CredentialStoreUnavailableError) {
     return failure(
       command,
       3,
       "credential_store_unavailable",
-      true,
-      "Unlock or repair the selected credential store and retry.",
+      false,
+      CREDENTIAL_STORE_UNAVAILABLE_ACTION,
     );
   }
   if (error instanceof ResponseContractError) {
@@ -2370,7 +2587,7 @@ const classifyFailure = (
       7,
       "response_contract_invalid",
       false,
-      "Retry only after the client or server contract is repaired.",
+      RESPONSE_CONTRACT_INVALID_ACTION,
     );
   }
   if (error instanceof PublicResponseTooLargeError) {
@@ -2396,6 +2613,7 @@ const classifyFailure = (
         problem.requestId,
         problem.docsUrl,
         ACCOUNT_SENSITIVE_PROBLEMS.has(problem.code) ? actingAs : undefined,
+        problem.message,
       );
     } catch {
       return failure(
@@ -2403,7 +2621,7 @@ const classifyFailure = (
         7,
         "response_contract_invalid",
         false,
-        "Retry only after the client or server contract is repaired.",
+        RESPONSE_CONTRACT_INVALID_ACTION,
       );
     }
   }
@@ -2413,13 +2631,67 @@ const classifyFailure = (
       7,
       "response_contract_invalid",
       false,
-      "Retry only after the client or server contract is repaired.",
+      RESPONSE_CONTRACT_INVALID_ACTION,
     );
   }
   if (error instanceof NetworkTransportError) {
-    return failure(command, 8, "network_error", true, "Check connectivity and retry.");
+    return failure(
+      command,
+      8,
+      "network_error",
+      true,
+      "The request did not reach the ohmyho.st API, or its answer was cut off. If the agent runs in a sandbox without network access, run the command with network access. Otherwise run the same command again with the same --idempotency-key; the change may already have been applied, and a new key could apply it twice.",
+    );
+  }
+  return failure(command, 1, "internal_error", false, INTERNAL_ERROR_ACTION);
+};
+
+/** A 409 idempotency_key_reused problem, with what its answer carries. */
+const reusedKeyProblem = (error: unknown): ReturnType<typeof parseSafeProblem> | undefined => {
+  if (!looksLikeProblem(error)) return undefined;
+  try {
+    const problem = parseSafeProblem(error);
+    return problem.code === "idempotency_key_reused" ? problem : undefined;
+  } catch {
+    return undefined;
+  }
+};
+
+/** One stream and at most three reconnects before an unfinished operation is handed back. */
+const OPERATION_STREAM_CONNECTIONS = 4;
+
+/**
+ * The single DML statement of `database write --statement-file`: a regular UTF-8 file of at most
+ * 64 KiB. Anything else, including a missing file, is refused before any request.
+ */
+const readStatementFile = async (path: string): Promise<string> => {
+  const invalid = () =>
+    new ProductCliFailure(2, "statement_file_invalid", false, STATEMENT_FILE_INVALID_ACTION);
+  let file: Awaited<ReturnType<typeof open>>;
+  try {
+    file = await open(path, "r");
+  } catch {
+    throw invalid();
+  }
+  const buffer = Buffer.alloc(65_537);
+  try {
+    const stat = await file.stat();
+    if (!stat.isFile() || stat.size > 65_536) throw invalid();
+    let length = 0;
+    while (length < buffer.length) {
+      const read = await file.read(buffer, length, buffer.length - length, null);
+      if (read.bytesRead === 0) break;
+      length += read.bytesRead;
+    }
+    if (length > 65_536) throw invalid();
+    return new TextDecoder("utf-8", { fatal: true }).decode(buffer.subarray(0, length));
+  } catch (error) {
+    if (error instanceof ProductCliFailure) throw error;
+    throw invalid();
+  } finally {
+    buffer.fill(0);
+    await file.close();
   }
-  return failure(command, 1, "internal_error", false, "Retry the command.");
 };
 
 const psqlUnavailable = (): CliResult =>
@@ -2448,6 +2720,7 @@ const failure = (
   requestId?: string,
   docsUrl?: string,
   actingAs?: Readonly<Record<string, unknown>>,
+  message?: string,
 ): CliResult => {
   const document: CliErrorDocument = {
     version: 1,
@@ -2462,6 +2735,7 @@ const failure = (
       ...(requestId === undefined ? {} : { request_id: requestId }),
       ...(docsUrl === undefined ? {} : { docs_url: docsUrl }),
       ...(operation?.error === undefined ? {} : { message: operation.error.message }),
+      ...(message === undefined ? {} : { message }),
       ...(actingAs === undefined ? {} : { acting_as: actingAs }),
     },
   };
@@ -2490,6 +2764,8 @@ const parsedCommandName = (command: ProductCliCommand): CommandLabel => {
   if (command.kind === "feedback-submit") return "feedback submit";
   if (command.kind === "feedback-status") return "feedback status";
   if (command.kind === "project-create") return "project create";
+  if (command.kind === "project-data-plan") return "project data plan";
+  if (command.kind === "project-data-change") return "project data change";
   if (command.kind === "organization-create") return "organization create";
   if (command.kind === "organization-list") return "organization list";
   if (command.kind === "organization-use") return "organization use";