@supacloud/cli 0.77.0 → 0.78.0

package/README.md

@@ -79,6 +79,94 @@ deployment. An unknown mutation outcome remains unknown; reconcile the same
 activation identity rather than blindly deploying again. These commands require
 Management API credentials except local plan/build and authoring commands.
 
+### Isolated Application Previews
+
+```sh
+supacloud-cli app preview-plan --env test --id orders --environment_id test --release_id RELEASE_SHA256 --branch_ref preview-orders
+supacloud-cli app preview --env test --id orders --environment_id test --release_id RELEASE_SHA256 --configuration_id CONFIG_UUID --ttl_seconds 3600 --wait --timeout_seconds 300
+supacloud-cli app previews --env test --id orders --environment_id test
+supacloud-cli app preview-status --env test --id orders --environment_id test --preview_id PREVIEW_UUID --wait --timeout_seconds 300
+supacloud-cli app preview-cleanup --env test --id orders --environment_id test --preview_id PREVIEW_UUID
+```
+
+The platform owns branch provisioning, queue/Storage namespaces, test Secrets,
+configuration cloning, activation and runtime readiness. The CLI never performs
+these operations through SSH or sequential client-side resource mutations.
+Creation defaults to `schema_only`; copying source rows requires explicitly
+selecting `--data_mode full_clone`. Creation requires an immutable source
+configuration ID and verifies the branch release identity against the source
+manifest. A `provisioning` receipt means accepted, not ready.
+
+New previews use the platform's default 24-hour TTL. `--ttl_seconds` accepts 300
+through 604800 seconds for creation or read-only planning. `expires_at` remains
+in the public receipt; a plan has no deadline unless a TTL is requested. Receipt
+expiry requires the matching platform cleanup contract (#1774), not the older
+CLI-only lifecycle contract.
+
+`--wait` on creation observes only the accepted Preview ID; it never repeats
+creation. `preview-status --wait` continues observing that same ID. The observation
+budget is 300 seconds by default and accepts 1 through 3600 seconds with
+`--timeout_seconds`; creation's source verification and initial POST precede that
+budget, while status includes its initial GET. Header and body share the remaining
+request budget. Completed readiness ends waiting; a failed/cleaned receipt, failed
+query or identity drift ends it with nonzero status. A wait timeout returns
+`waiting.status: "timed_out"` with the last validated receipt and the exact
+same-ID continuation in `reconciliation`. It does not mark provisioning failed,
+retry a failed lifecycle GET, delete resources or promote an environment.
+
+`preview-plan` is read-only. Preview list/status requests may resume persisted
+provisioning on the server, so they are classified as writes, including in
+read-only and production profiles. The platform may clean eligible expired
+previews, but never interrupts a serving preview or empties nonempty Storage
+automatically. Explicit cleanup remains available. Failed previews return
+nonzero with the validated receipt and cleanup state. Unknown create outcomes
+are never retried: list existing previews and reconcile their receipts first.
+No production deployment, database promotion or data rollback is implied.
+Runtime readiness is not authenticated business-flow acceptance.
+
+```gherkin
+Feature: Platform-owned application previews
+  Scenario: Read-only planning
+    Given an explicit release and proposed branch ref
+    When preview-plan runs in read-only mode
+    Then only a GET plan request is sent
+    And no preview is created
+
+  Scenario: Accepted is not ready
+    Given an immutable source release and configuration
+    When preview creates an isolated environment
+    Then exactly one create request is sent
+    And a provisioning receipt is returned without claiming readiness
+
+  Scenario: TTL is validated before dispatch
+    Given a lifetime outside 300 through 604800 integer seconds
+    When preview or preview-plan is requested
+    Then no HTTP request is sent
+
+  Scenario: Wait preserves the selected preview
+    Given a valid provisioning receipt and an exhausted observation budget
+    When preview --wait returns
+    Then its exit status is nonzero and the accepted receipt is preserved
+    And reconciliation selects the same Preview ID without another creation
+
+  Scenario: Ready requires verified platform evidence
+    Given a provisioning preview selected by its scope, digest and Preview ID
+    When its complete readiness receipt is observed
+    Then waiting succeeds with that receipt
+    And foreign or malformed receipts never become success
+
+  Scenario: Safety guards precede effects
+    Given a read-only or unconfirmed production profile
+    When preview creation, status recovery or cleanup is requested
+    Then the CLI rejects the request before HTTP dispatch
+
+  Scenario: Unknown outcome preserves reconciliation
+    Given a create response is lost or belongs to another environment
+    When the CLI handles that response
+    Then it reports OUTCOME_UNKNOWN without retrying creation
+    And it retains the selected scope for receipt reconciliation
+```
+
 ### Framework source upgrades
 
 Breaking source-contract changes use the compiler's migration command, which is

package/dist/index.js

@@ -179093,8 +179093,18 @@ function resolveSupaCloudContext(env = process.env, cwd = process.cwd(), selecti
 var ACTION_POLICY = {
   deploy: { write: ["deploy"] },
   applications: {
-    read: ["list_releases", "get_release", "get_runtime", "get_deployment_evidence", "get_configuration", "logs"],
-    write: ["upload_release", "put_configuration", "activate_release", "reconcile_activation", "retire_activation"]
+    read: ["list_releases", "get_release", "get_runtime", "get_deployment_evidence", "get_configuration", "logs", "get_preview_plan"],
+    write: [
+      "upload_release",
+      "put_configuration",
+      "activate_release",
+      "reconcile_activation",
+      "retire_activation",
+      "create_preview",
+      "list_previews",
+      "get_preview",
+      "cleanup_preview"
+    ]
   },
   project: {
     read: ["get", "endpoints", "health", "logs", "api_keys", "settings", "tasks", "task_detail", "task_stats", "dlq", "background_settings"],
@@ -179189,8 +179199,8 @@ var ACTION_POLICY = {
   ai: { local: ["show_skill", "install_skill"] },
   app: {
     local: ["init", "generate", "dev", "watch", "verify-plan", "compile", "check", "graph", "explain", "export-tools", "context", "doctor", "fix", "plan", "build"],
-    read: ["status", "logs"],
-    write: ["upload", "configure", "deploy", "rollback", "reconcile", "retire"]
+    read: ["status", "logs", "preview-plan"],
+    write: ["upload", "configure", "deploy", "rollback", "reconcile", "retire", "preview", "previews", "preview-status", "preview-cleanup"]
   },
   db: {
     local: ["context", "lint", "explain", "diff", "role_sql"],
@@ -179528,19 +179538,34 @@ class HttpTransport {
     }
   }
   async get(path, options = {}) {
+    const timeoutMs = validatedPostTimeout(options);
     const maxResponseBytes = validatedGetResponseLimit(options);
     const maxJsonBytes = validatedJsonResponseLimit(options.maxJsonBytes);
     const responseTimeoutMs = validatedResponseTimeout(options.responseTimeoutMs);
+    const totalTimeoutMs = validatedResponseTimeout(options.totalTimeoutMs);
     if (maxResponseBytes !== undefined && maxJsonBytes !== undefined) {
       throw new RangeError("HTTP response limit options are mutually exclusive");
     }
+    if (totalTimeoutMs !== undefined && (options.retry !== false || maxJsonBytes === undefined)) {
+      throw new RangeError("HTTP total timeout requires bounded JSON and retry: false");
+    }
+    const deadline = totalTimeoutMs === undefined ? undefined : performance.now() + totalTimeoutMs;
     try {
-      const res = await fetchWithRetry(`${this.baseUrl}${path}`, {
+      const request = options.retry === false ? fetchWithTimeout : fetchWithRetry;
+      const res = await request(`${this.baseUrl}${path}`, {
         method: "GET",
         headers: this.headers()
-      }, DEFAULT_TIMEOUT, this.insecureTls);
+      }, totalTimeoutMs === undefined ? timeoutMs : Math.min(timeoutMs, totalTimeoutMs), this.insecureTls);
       if (maxJsonBytes !== undefined) {
-        const data = await boundedResponseJson(res, maxJsonBytes, responseTimeoutMs);
+        const remaining = deadline === undefined ? undefined : Math.floor(deadline - performance.now());
+        if (remaining !== undefined && remaining <= 0) {
+          res.body?.cancel().catch(() => {
+            return;
+          });
+          return responseReadFailure(res.status);
+        }
+        const bodyTimeout = remaining === undefined ? responseTimeoutMs : Math.min(responseTimeoutMs ?? remaining, remaining);
+        const data = await boundedResponseJson(res, maxJsonBytes, bodyTimeout);
         return data === null ? responseReadFailure(res.status) : { ok: res.ok, status: res.status, data };
       }
       const data = maxResponseBytes === undefined ? await res.json().catch(() => null) : await boundedResponseJson(res, maxResponseBytes);
@@ -187228,6 +187253,332 @@ var ApplicationActivationWriteSchema2 = ApplicationActivationWriteSchema;
 var ApplicationActivationResultSchema2 = ApplicationActivationResultSchema;
 var ApplicationActivationRetirementResultSchema2 = ApplicationActivationRetirementResultSchema;
 
+// src/shared/tools/application-preview-tools.ts
+var APPLICATION_PREVIEW_ACTIONS = [
+  "get_preview_plan",
+  "create_preview",
+  "list_previews",
+  "get_preview",
+  "cleanup_preview"
+];
+var previewIdSchema = String2({ pattern: "^[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12}$" });
+var branchRefSchema = String2({ pattern: "^[a-z0-9-]{1,20}$" });
+var ttlSecondsSchema = Integer({ minimum: 300, maximum: 604800 });
+var waitSecondsSchema = Integer({ minimum: 1, maximum: 3600 });
+var timestampSchema = String2({
+  pattern: "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$",
+  maxLength: 24
+});
+var APPLICATION_PREVIEW_FIELDS = {
+  preview_id: optional(previewIdSchema, "[get_preview/cleanup_preview] Preview receipt ID"),
+  branch_ref: optional(branchRefSchema, "[get_preview_plan] Proposed branch ref; create assigns its own"),
+  branch_name: optional(String2({ minLength: 1, maxLength: 80 }), "[create_preview] Branch display name"),
+  data_mode: optional(stringEnum(["schema_only", "full_clone"]), "[get_preview_plan/create_preview] Default schema_only; full_clone copies rows"),
+  ttl_seconds: optional(ttlSecondsSchema, "[get_preview_plan/create_preview] Lifetime from 300 to 604800 seconds; creation defaults to the platform TTL"),
+  wait: optional(Boolean2(), "[create_preview/get_preview] Wait for verified readiness of this preview only"),
+  timeout_seconds: optional(waitSecondsSchema, "[create_preview/get_preview] Observation budget with wait, from 1 to 3600 seconds (default 300)")
+};
+var strict = { additionalProperties: false };
+var phase = stringEnum(["pending", "ready", "failed", "cleaned"]);
+var check5 = String2({ pattern: "^[a-z][a-z0-9_]{0,63}$" });
+var checks = _Array_(check5, { maxItems: 64, uniqueItems: true });
+var revision = Union([ApplicationConfigurationIdSchema2, Null()]);
+var receiptSchema = _Object_({
+  schema: Literal("supacloud.application-preview.v1"),
+  preview_id: previewIdSchema,
+  project_ref: branchRefSchema,
+  application_id: ApplicationIdSchema2,
+  environment_id: ApplicationIdSchema2,
+  release_id: ApplicationReleaseIdSchema2,
+  expires_at: Union([timestampSchema, Null()]),
+  status: stringEnum(["planned", "provisioning", "ready", "failed", "cleaned"]),
+  resources: _Object_({
+    build_artifact: _Object_({ status: phase, release_id: ApplicationReleaseIdSchema2 }, strict),
+    database_branch: _Object_({ status: phase, branch_ref: branchRefSchema, data_mode: stringEnum(["schema_only", "full_clone"]) }, strict),
+    queue_namespace: _Object_({ status: phase, namespace: String2({ minLength: 1, maxLength: 128 }) }, strict),
+    storage_namespace: _Object_({ status: phase, namespace: branchRefSchema }, strict),
+    test_secret: _Object_({ status: phase, name: String2({ pattern: "^[A-Z0-9_-]{1,128}$" }), value_issued: Literal(false) }, strict),
+    configuration_revision: _Object_({ status: phase, configuration_id: revision }, strict),
+    application_activation: _Object_({ status: phase, activation_id: Union([previewIdSchema, Null()]) }, strict),
+    smoke_test: _Object_({ status: phase, checks, passed: checks, failed: checks }, strict)
+  }, strict),
+  cleanup: _Object_({
+    required: Boolean2(),
+    completed: Boolean2(),
+    error: Union([String2({ pattern: "^[A-Z0-9_]{1,128}$" }), Null()])
+  }, strict),
+  branch_name: Optional(String2({ maxLength: 80 })),
+  queue_name: Optional(String2({ maxLength: 128 })),
+  test_secret_name: Optional(String2({ pattern: "^[A-Z0-9_]{1,128}$" })),
+  source_configuration_id: Optional(revision),
+  created_at: Optional(timestampSchema),
+  updated_at: Optional(timestampSchema)
+}, strict);
+function required5(args, field) {
+  const value = args[field];
+  if (typeof value !== "string" || !value.trim())
+    throw new Error(`'${field}' is required`);
+  return value.trim();
+}
+var mandatoryChecks = [
+  "release_artifact",
+  "database_branch",
+  "queue_namespace",
+  "storage_namespace",
+  "test_secret",
+  "configuration_revision",
+  "application_activation",
+  "application_readiness",
+  "tenant_runtime"
+];
+var actionFields = {
+  get_preview_plan: ["release_id", "branch_ref", "data_mode", "configuration_id", "ttl_seconds"],
+  create_preview: ["release_id", "configuration_id", "data_mode", "branch_name", "ttl_seconds", "wait", "timeout_seconds"],
+  list_previews: [],
+  get_preview: ["preview_id", "wait", "timeout_seconds"],
+  cleanup_preview: ["preview_id"]
+};
+function timestamp(value) {
+  return Number.isFinite(Date.parse(value)) && new Date(value).toISOString() === value;
+}
+function receipt(value, identity) {
+  if (!Check2(receiptSchema, value) || value.project_ref !== identity.ref || value.application_id !== identity.id || value.environment_id !== identity.environment || identity.previewId && value.preview_id !== identity.previewId || value.resources.build_artifact.release_id !== value.release_id || value.resources.storage_namespace.namespace !== value.resources.database_branch.branch_ref) {
+    throw new Error("Invalid preview receipt");
+  }
+  if (value.expires_at !== null && !timestamp(value.expires_at) || value.created_at !== undefined && !timestamp(value.created_at) || value.updated_at !== undefined && !timestamp(value.updated_at) || value.expires_at !== null && value.created_at !== undefined && !Check2(ttlSecondsSchema, (Date.parse(value.expires_at) - Date.parse(value.created_at)) / 1000)) {
+    throw new Error("Invalid preview expiry");
+  }
+  if (value.status === "ready") {
+    if (value.resources.smoke_test.status !== "ready" || value.resources.smoke_test.failed.length > 0 || mandatoryChecks.some((check) => !value.resources.smoke_test.checks.includes(check) || !value.resources.smoke_test.passed.includes(check)) || value.resources.smoke_test.passed.some((check) => !value.resources.smoke_test.checks.includes(check)) || Object.values(value.resources).some((resource) => resource.status !== "ready") || !value.resources.configuration_revision.configuration_id || !value.resources.application_activation.activation_id) {
+      throw new Error("Incomplete preview readiness");
+    }
+  }
+  if (value.status === "cleaned" && (!value.cleanup.completed || value.cleanup.required || [
+    value.resources.database_branch,
+    value.resources.queue_namespace,
+    value.resources.storage_namespace,
+    value.resources.test_secret
+  ].some((resource) => resource.status !== "cleaned"))) {
+    throw new Error("Incomplete preview cleanup");
+  }
+  const {
+    branch_name: _branchName,
+    queue_name: _queueName,
+    test_secret_name: _secretName,
+    source_configuration_id: _sourceConfiguration,
+    created_at: _createdAt,
+    updated_at: _updatedAt,
+    ...publicReceipt
+  } = value;
+  return publicReceipt;
+}
+async function sourceManifest(http, path, ref, id, releaseId) {
+  const result = await http.get(`${path}/releases/${releaseId}`, { maxJsonBytes: 196608, responseTimeoutMs: 30000 });
+  if (!result.ok)
+    return { result };
+  try {
+    const data = result.data;
+    if (!data || typeof data !== "object" || !("project_ref" in data) || data.project_ref !== ref || !("application_id" in data) || data.application_id !== id || !("release" in data))
+      throw new Error;
+    const release = parseApplicationReleaseRecord(data.release);
+    if (release.project_ref !== ref || release.application_id !== id || release.release_id !== releaseId)
+      throw new Error;
+    return { result, manifest: release.manifest_sha256 };
+  } catch {
+    return { result };
+  }
+}
+async function waitForPreview(http, path, operation, identity, initial, timeoutSeconds, startedAt = performance.now()) {
+  const deadline = startedAt + timeoutSeconds * 1000;
+  let current = initial;
+  const state = () => ({
+    ...identity,
+    preview_id: initial.preview_id,
+    preview: current,
+    reconciliation: {
+      action: "get_preview",
+      ref: identity.project_ref,
+      id: identity.application_id,
+      environment_id: identity.environment_id,
+      preview_id: initial.preview_id,
+      wait: true,
+      timeout_seconds: timeoutSeconds
+    }
+  });
+  while (true) {
+    if (current.status === "ready")
+      return releaseControlSuccess(operation, {
+        ...identity,
+        preview: current,
+        waiting: { status: "ready", timeout_seconds: timeoutSeconds }
+      });
+    if (current.status !== "provisioning")
+      return releaseControlFailure(operation, "MUTATION_NOT_SUCCEEDED", null, {
+        ...state(),
+        waiting: { status: "stopped", timeout_seconds: timeoutSeconds }
+      });
+    const remaining = Math.floor(deadline - performance.now());
+    if (remaining < 2)
+      return releaseControlFailure(operation, "MUTATION_NOT_SUCCEEDED", null, {
+        ...state(),
+        waiting: { status: "timed_out", timeout_seconds: timeoutSeconds }
+      });
+    const requestBudget = Math.min(120000, remaining);
+    const result = await http.get(`${path}/previews/${initial.preview_id}`, {
+      retry: false,
+      timeoutMs: requestBudget,
+      responseTimeoutMs: requestBudget,
+      totalTimeoutMs: requestBudget,
+      maxJsonBytes: 1048576
+    });
+    if (!result.ok)
+      return releaseControlFailure(operation, "HTTP_ERROR", result.transportError ? null : result.status, {
+        ...state(),
+        waiting: { status: "observation_failed", timeout_seconds: timeoutSeconds }
+      });
+    try {
+      const next = receipt(result.data, {
+        ref: identity.project_ref,
+        id: identity.application_id,
+        environment: identity.environment_id,
+        previewId: initial.preview_id
+      });
+      if (next.status === "planned" || next.release_id !== initial.release_id || next.expires_at !== initial.expires_at || next.resources.database_branch.branch_ref !== initial.resources.database_branch.branch_ref || next.resources.database_branch.data_mode !== initial.resources.database_branch.data_mode || current.resources.application_activation.activation_id !== null && next.resources.application_activation.activation_id !== current.resources.application_activation.activation_id || current.resources.configuration_revision.configuration_id !== null && next.resources.configuration_revision.configuration_id !== current.resources.configuration_revision.configuration_id) {
+        throw new Error("Preview identity changed during observation");
+      }
+      current = next;
+    } catch {
+      return releaseControlFailure(operation, "INVALID_RESPONSE", result.status, {
+        ...state(),
+        waiting: { status: "observation_failed", timeout_seconds: timeoutSeconds }
+      });
+    }
+    if (current.status === "provisioning") {
+      await new Promise((resolve) => setTimeout(resolve, Math.max(0, Math.min(1000, deadline - performance.now()))));
+    }
+  }
+}
+async function applicationPreviewAction(http, args, project) {
+  const action = required5(args, "action"), ref = required5(args, "ref"), id = required5(args, "id");
+  const environment = required5(args, "environment_id");
+  if (!Check2(ApplicationIdSchema2, environment))
+    throw new Error("Invalid environment ID");
+  const fields = new Set(["action", "ref", "id", "environment_id", ...actionFields[action] ?? []]);
+  if (Object.entries(args).some(([key, value]) => value !== undefined && !fields.has(key))) {
+    throw new Error("Invalid option for preview action");
+  }
+  if (args["ttl_seconds"] !== undefined && !Check2(ttlSecondsSchema, args["ttl_seconds"])) {
+    throw new Error("ttl_seconds must be an integer from 300 to 604800");
+  }
+  if (args["wait"] !== undefined && typeof args["wait"] !== "boolean")
+    throw new Error("wait must be boolean");
+  if (args["timeout_seconds"] !== undefined && (args["wait"] !== true || !Check2(waitSecondsSchema, args["timeout_seconds"]))) {
+    throw new Error("timeout_seconds requires wait and must be an integer from 1 to 3600");
+  }
+  const timeoutSeconds = args["wait"] === true ? args["timeout_seconds"] ?? 300 : undefined;
+  const startedAt = action === "get_preview" && timeoutSeconds !== undefined ? performance.now() : undefined;
+  const operation = `applications.${action}`;
+  const identity = { project_ref: ref, application_id: id, environment_id: environment };
+  const applicationPath = `/v1/projects/${project}/applications/${encodeURIComponent(id)}`;
+  const path = `${applicationPath}/environments/${encodeURIComponent(environment)}`;
+  const previewId = action === "get_preview" || action === "cleanup_preview" ? required5(args, "preview_id") : undefined;
+  const mutation = action === "create_preview" || action === "cleanup_preview";
+  const requestBudget = startedAt === undefined ? 120000 : Math.min(120000, timeoutSeconds * 1000);
+  const options = {
+    timeoutMs: requestBudget,
+    maxJsonBytes: 1048576,
+    responseTimeoutMs: requestBudget,
+    retry: false,
+    ...startedAt === undefined ? {} : { totalTimeoutMs: requestBudget }
+  };
+  let sourceHash;
+  let releaseId;
+  let result;
+  if (action === "get_preview_plan" || action === "create_preview") {
+    releaseId = required5(args, "release_id");
+    if (!Check2(ApplicationReleaseIdSchema2, releaseId))
+      throw new Error("Invalid release ID");
+    if (action === "get_preview_plan") {
+      const query = new URLSearchParams({ release_id: releaseId, branch_ref: required5(args, "branch_ref") });
+      if (typeof args["data_mode"] === "string")
+        query.set("data_mode", args["data_mode"]);
+      if (typeof args["configuration_id"] === "string")
+        query.set("configuration_id", args["configuration_id"]);
+      if (args["ttl_seconds"] !== undefined)
+        query.set("ttl_seconds", String(args["ttl_seconds"]));
+      result = await http.get(`${path}/preview-plan?${query}`, options);
+    } else {
+      const configurationId = required5(args, "configuration_id");
+      if (!Check2(ApplicationConfigurationIdSchema2, configurationId))
+        throw new Error("Invalid configuration ID");
+      const source = await sourceManifest(http, applicationPath, ref, id, releaseId);
+      if (!source.manifest)
+        return releaseControlFailure(operation, source.result.ok ? "INVALID_RESPONSE" : "HTTP_ERROR", source.result.status, { ...identity, release_id: releaseId, configuration_id: configurationId });
+      sourceHash = source.manifest;
+      result = await http.post(`${path}/previews`, {
+        release_id: releaseId,
+        configuration_id: configurationId,
+        data_mode: args["data_mode"] ?? "schema_only",
+        ...args["branch_name"] === undefined ? {} : { branch_name: args["branch_name"] },
+        ...args["ttl_seconds"] === undefined ? {} : { ttl_seconds: args["ttl_seconds"] }
+      }, options);
+    }
+  } else if (action === "list_previews") {
+    result = await http.get(`${path}/previews`, options);
+  } else if (previewId) {
+    if (!Check2(previewIdSchema, previewId))
+      throw new Error("Invalid preview ID");
+    result = action === "cleanup_preview" ? await http.deleteReleaseMutation(`${path}/previews/${previewId}`) : await http.get(`${path}/previews/${previewId}`, options);
+  } else {
+    throw new Error("Unknown preview action");
+  }
+  const state = {
+    ...identity,
+    ...previewId ? { preview_id: previewId } : {},
+    ...releaseId ? { source_release_id: releaseId } : {},
+    reconciliation: previewId ? { action: "get_preview", ref, id, environment_id: environment, preview_id: previewId } : { action: "list_previews", ref, id, environment_id: environment }
+  };
+  if (!result.ok)
+    return mutation ? releaseControlMutationFailure(operation, result, state) : releaseControlFailure(operation, "HTTP_ERROR", result.status, state);
+  try {
+    if (action === "list_previews") {
+      const inventorySchema = _Object_({
+        ..._Object_({ project_ref: branchRefSchema, application_id: ApplicationIdSchema2, environment_id: ApplicationIdSchema2 }).properties,
+        previews: _Array_(receiptSchema, { maxItems: 1000 })
+      }, strict);
+      if (!Check2(inventorySchema, result.data) || result.data.project_ref !== ref || result.data.application_id !== id || result.data.environment_id !== environment)
+        throw new Error;
+      const previews = result.data.previews.map((value) => receipt(value, { ref, id, environment }));
+      if (new Set(previews.map((value) => value.preview_id)).size !== previews.length)
+        throw new Error;
+      return releaseControlSuccess(operation, { ...identity, previews });
+    }
+    const preview = receipt(result.data, {
+      ref,
+      id,
+      environment,
+      ...previewId === undefined ? {} : { previewId }
+    });
+    if (action === "get_preview_plan") {
+      if (preview.status !== "planned" || preview.release_id !== releaseId || preview.resources.database_branch.branch_ref !== args["branch_ref"] || preview.resources.database_branch.data_mode !== (args["data_mode"] ?? "schema_only") || (args["ttl_seconds"] === undefined ? preview.expires_at !== null : preview.expires_at === null))
+        throw new Error;
+    } else {
+      if (preview.status === "planned" || preview.resources.database_branch.branch_ref !== `pv${preview.preview_id.replaceAll("-", "").slice(0, 18)}`)
+        throw new Error;
+      if (action === "create_preview" && (preview.release_id !== applicationReleaseId(preview.resources.database_branch.branch_ref, id, sourceHash) || preview.resources.database_branch.data_mode !== (args["data_mode"] ?? "schema_only") || !Check2(receiptSchema, result.data) || result.data.source_configuration_id !== args["configuration_id"] || preview.expires_at === null || result.data.created_at === undefined || args["ttl_seconds"] !== undefined && Date.parse(preview.expires_at) - Date.parse(result.data.created_at) !== args["ttl_seconds"] * 1000))
+        throw new Error;
+    }
+    if (preview.status === "failed" || action === "cleanup_preview" && preview.status !== "cleaned") {
+      return releaseControlFailure(operation, "MUTATION_NOT_SUCCEEDED", result.status, { ...identity, preview });
+    }
+    if (timeoutSeconds !== undefined)
+      return await waitForPreview(http, path, operation, identity, preview, timeoutSeconds, startedAt);
+    return releaseControlSuccess(operation, { ...identity, preview });
+  } catch {
+    return releaseControlFailure(operation, mutation ? "OUTCOME_UNKNOWN" : "INVALID_RESPONSE", result.status, state);
+  }
+}
+
 // src/shared/tools/application-tools.ts
 var APPLICATION_TOOL_SCHEMA = {
   action: withDescription(stringEnum([
@@ -187241,6 +187592,7 @@ var APPLICATION_TOOL_SCHEMA = {
     "activate_release",
     "reconcile_activation",
     "retire_activation",
+    ...APPLICATION_PREVIEW_ACTIONS,
     "logs"
   ]), "Action"),
   ref: withDescription(String2(), "Project ref"),
@@ -187258,7 +187610,8 @@ var APPLICATION_TOOL_SCHEMA = {
   service: optional(String2(), "[logs] Application target/service filter"),
   search: optional(String2(), "[logs] Full-text log filter"),
   start: optional(String2(), "[logs] ISO start timestamp"),
-  end: optional(String2(), "[logs] ISO end timestamp")
+  end: optional(String2(), "[logs] ISO end timestamp"),
+  ...APPLICATION_PREVIEW_FIELDS
 };
 var responseSchema = _Object_({
   project_ref: String2(),
@@ -187382,6 +187735,9 @@ function registerApplicationTools(server2, http) {
       throw new Error("Invalid application ID");
     const path = `/v1/projects/${project}/applications/${encodeURIComponent(id)}/releases`;
     const operation = `applications.${action}`;
+    if (APPLICATION_PREVIEW_ACTIONS.some((value) => value === action)) {
+      return applicationPreviewAction(http, args, project);
+    }
     if (action === "activate_release" || action === "reconcile_activation" || action === "retire_activation") {
       return activationAction(http, args, project);
     }
@@ -188750,6 +189106,34 @@ Actions: routes, upsert_route, update_route, delete_route, config, get_certifica
 }
 
 // src/shared/tools/branch-tools.ts
+var SHA256_PATTERN = /^[0-9a-f]{64}$/;
+var PROMOTION_PLAN_MAX_JSON_BYTES = 512 * 1024;
+var PROMOTION_BLOCK_MESSAGES = {
+  parent_ahead: "Parent history is ahead; recreate or rebase the preview branch.",
+  checksum_mismatch: "Parent and branch migration checksums differ.",
+  stored_checksum_mismatch: "Stored checksum does not match migration SQL.",
+  name_conflict: "Migration name already exists in the parent.",
+  out_of_order_migration: "Migration precedes the latest parent migration.",
+  empty_migration: "Migration has no executable statements.",
+  non_transactional_sql: "Migration requires a separate maintenance path.",
+  unsupported_sql: "Migration exceeds the project-scoped SQL policy."
+};
+var PROMOTION_FAILURE_CODES = new Set([
+  "promotion_locked",
+  "promotion_plan_changed",
+  "promotion_blocked",
+  "destructive_confirmation_required",
+  "promotion_apply_failed",
+  "promotion_readback_failed",
+  "promotion_failed",
+  "promotion_plan_failed",
+  "promotion_plan_required",
+  "branch_not_active"
+]);
+var PROMOTION_WARNINGS = [
+  "Only recorded migrations are promoted; branch data and untracked schema changes are not copied.",
+  "Migration SQL can modify parent data and must be reviewed."
+];
 function resolveProjectRef(ref, projectRef) {
   const resolved = typeof ref === "string" && ref.trim() ? ref.trim() : projectRef || "";
   if (!resolved)
@@ -188761,32 +189145,188 @@ function requireString(value, field) {
     throw new Error(`'${field}' is required`);
   return value.trim();
 }
+function isRecord4(value) {
+  return !!value && typeof value === "object" && !Array.isArray(value);
+}
+function isSha256(value) {
+  return typeof value === "string" && SHA256_PATTERN.test(value);
+}
+function parsePromotionEntry(candidate) {
+  if (!isRecord4(candidate))
+    return null;
+  const { version, name, checksum, statement_count: statementCount, statements, destructive } = candidate;
+  if (typeof version !== "string" || !/^[A-Za-z0-9][A-Za-z0-9_.-]{0,127}$/.test(version))
+    return null;
+  if (name !== null && (typeof name !== "string" || name.length > 256 || /[\x00-\x1f\x7f]/.test(name)))
+    return null;
+  if (!isSha256(checksum))
+    return null;
+  if (typeof statementCount !== "number" || !Number.isSafeInteger(statementCount) || statementCount < 0)
+    return null;
+  if (typeof destructive !== "boolean")
+    return null;
+  if (statements !== undefined && (!Array.isArray(statements) || statements.length !== statementCount || statements.some((statement) => typeof statement !== "string"))) {
+    return null;
+  }
+  return {
+    version,
+    name,
+    checksum,
+    statement_count: statementCount,
+    destructive
+  };
+}
+function parsePromotionBlock(candidate) {
+  if (!isRecord4(candidate))
+    return null;
+  const { code, version, name, message } = candidate;
+  if (typeof code !== "string" || !Object.hasOwn(PROMOTION_BLOCK_MESSAGES, code))
+    return null;
+  if (typeof version !== "string" || !/^[A-Za-z0-9][A-Za-z0-9_.-]{0,127}$/.test(version))
+    return null;
+  if (name !== null && (typeof name !== "string" || name.length > 256 || /[\x00-\x1f\x7f]/.test(name)))
+    return null;
+  if (typeof message !== "string")
+    return null;
+  const blockCode = code;
+  return {
+    code: blockCode,
+    version,
+    name,
+    message: PROMOTION_BLOCK_MESSAGES[blockCode]
+  };
+}
+function uniqueVersions(entries) {
+  const versions = entries.map((entry) => entry.version);
+  return new Set(versions).size === versions.length;
+}
+function samePromotionEntry(left, right) {
+  return left.version === right.version && left.checksum === right.checksum && left.name === right.name && left.statement_count === right.statement_count && left.destructive === right.destructive;
+}
+function parsePromotionPlan(candidate, expectedScope) {
+  if (!isRecord4(candidate))
+    return null;
+  const {
+    mode,
+    parent_ref: parentRef,
+    branch_ref: branchRef,
+    safe_to_apply: safeToApply,
+    plan_checksum: planChecksum,
+    pending,
+    applied,
+    blocked,
+    warnings,
+    requires_destructive_confirmation: requiresDestructiveConfirmation,
+    ignored_branch_data: ignoredBranchData
+  } = candidate;
+  if (mode !== "migrations" || typeof parentRef !== "string" || typeof branchRef !== "string" || typeof safeToApply !== "boolean" || !isSha256(planChecksum) || !Array.isArray(pending) || !Array.isArray(applied) || !Array.isArray(blocked) || !Array.isArray(warnings) || typeof requiresDestructiveConfirmation !== "boolean" || ignoredBranchData !== true) {
+    return null;
+  }
+  if (parentRef !== expectedScope.parentRef || branchRef !== expectedScope.branchRef)
+    return null;
+  const pendingEntries = pending.map(parsePromotionEntry);
+  const appliedEntries = applied.map(parsePromotionEntry);
+  const blockingFindings = blocked.map(parsePromotionBlock);
+  if (pendingEntries.some((entry) => entry === null) || appliedEntries.some((entry) => entry === null) || blockingFindings.some((entry) => entry === null) || warnings.some((warning) => typeof warning !== "string")) {
+    return null;
+  }
+  const normalizedPending = pendingEntries.filter((entry) => entry !== null);
+  const normalizedApplied = appliedEntries.filter((entry) => entry !== null);
+  const normalizedBlocked = blockingFindings.filter((entry) => entry !== null);
+  const hasDestructivePending = normalizedPending.some((entry) => entry.destructive);
+  if (!uniqueVersions(normalizedPending) || !uniqueVersions(normalizedApplied) || !uniqueVersions([...normalizedPending, ...normalizedApplied]) || normalizedPending.some((entry) => entry.statement_count === 0) || safeToApply !== (normalizedBlocked.length === 0) || requiresDestructiveConfirmation !== hasDestructivePending) {
+    return null;
+  }
+  return {
+    mode,
+    parent_ref: parentRef,
+    branch_ref: branchRef,
+    safe_to_apply: safeToApply,
+    plan_checksum: planChecksum,
+    pending: normalizedPending,
+    applied: normalizedApplied,
+    blocked: normalizedBlocked,
+    warnings: [...PROMOTION_WARNINGS],
+    requires_destructive_confirmation: requiresDestructiveConfirmation,
+    ignored_branch_data: true
+  };
+}
+function parsePromotionResult(candidate, expectedScope, reviewedPending) {
+  if (!isRecord4(candidate) || candidate.promoted !== true || candidate.mode !== "migrations" || candidate.project_ref !== expectedScope.parentRef || candidate.branch_ref !== expectedScope.branchRef || candidate.branch_data_copied !== false || !Array.isArray(candidate.applied)) {
+    return null;
+  }
+  const applied = candidate.applied.map(parsePromotionEntry);
+  if (applied.some((entry) => entry === null))
+    return null;
+  const normalizedApplied = applied.filter((entry) => entry !== null);
+  if (!uniqueVersions(normalizedApplied) || normalizedApplied.length !== reviewedPending.length)
+    return null;
+  const reviewedByVersion = new Map(reviewedPending.map((entry) => [entry.version, entry]));
+  if (normalizedApplied.some((entry) => {
+    const reviewed = reviewedByVersion.get(entry.version);
+    return !reviewed || !samePromotionEntry(entry, reviewed);
+  }))
+    return null;
+  const plan = parsePromotionPlan(candidate.plan, expectedScope);
+  if (!plan || !plan.safe_to_apply || plan.pending.length > 0)
+    return null;
+  const readbackByVersion = new Map(plan.applied.map((entry) => [entry.version, entry]));
+  if (normalizedApplied.some((entry) => {
+    const readback = readbackByVersion.get(entry.version);
+    return !readback || !samePromotionEntry(entry, readback);
+  }))
+    return null;
+  return {
+    promoted: true,
+    mode: "migrations",
+    project_ref: expectedScope.parentRef,
+    branch_ref: expectedScope.branchRef,
+    applied: normalizedApplied,
+    plan,
+    branch_data_copied: false
+  };
+}
+function safePromotionCode(result) {
+  if (!isRecord4(result.data) || typeof result.data.code !== "string")
+    return;
+  return PROMOTION_FAILURE_CODES.has(result.data.code) ? result.data.code : undefined;
+}
+function appliedVersions(result) {
+  if (result.transportError || result.responseReadError || !isRecord4(result.data) || !Array.isArray(result.data.applied))
+    return [];
+  const entries = result.data.applied.map(parsePromotionEntry);
+  if (entries.some((entry) => !entry))
+    return [];
+  const validated = entries.filter((entry) => entry !== null);
+  return uniqueVersions(validated) ? validated.map((entry) => entry.version) : [];
+}
+function promotionFailure(response, json, unknownOutcome) {
+  if (json)
+    return response;
+  const state = JSON.parse(response.content[0].text);
+  if (!isRecord4(state) || !isRecord4(state.error))
+    return response;
+  const lines = [
+    unknownOutcome ? "Promotion outcome is unknown; do not repeat the request automatically." : "Promotion request was not verified.",
+    `Error: ${state.error.code}`,
+    `Project: ${state.project_ref}; branch: ${state.branch_ref}`,
+    ...typeof state.reason === "string" ? [`Reason: ${state.reason}`] : [],
+    ...state.mutation_sent === false ? ["No promotion request was sent."] : [],
+    ...typeof state.plan_checksum === "string" ? [`Reviewed checksum: ${state.plan_checksum}`] : [],
+    ...Array.isArray(state.reported_applied_versions) && state.reported_applied_versions.length > 0 ? [`Server-reported applied versions: ${state.reported_applied_versions.join(", ")}`] : [],
+    "Fetch a fresh promotion_plan and review ledger state before another promote."
+  ];
+  return { isError: true, content: [{ type: "text", text: lines.join(`
+`) }] };
+}
 function responseError(result) {
-  if (result.data && typeof result.data === "object") {
-    const data = result.data;
-    const message = data.error || data.message;
-    if (typeof message === "string") {
-      const details = [message];
-      if (Array.isArray(data.applied) && data.applied.length > 0) {
-        const versions = data.applied.map((entry) => entry && typeof entry === "object" ? entry.version : null).filter((version) => typeof version === "string");
-        details.push(`Applied before failure: ${versions.join(", ") || data.applied.length}`);
-        details.push("Fetch a fresh promotion_plan before retrying.");
-      }
-      if (data.replacement_committed === true) {
-        details.push(`Database replacement committed; recovery is required${typeof data.backup_database === "string" ? ` using backup ${data.backup_database}` : ""}.`);
-      }
-      return details.join(`
-`);
-    }
+  if (isRecord4(result.data)) {
+    const message = result.data.error || result.data.message;
+    if (typeof message === "string")
+      return message;
   }
   return `Request failed with HTTP ${result.status}`;
 }
-function isPromotionPlan(candidate) {
-  if (!candidate || typeof candidate !== "object")
-    return false;
-  const plan = candidate;
-  return plan.mode === "migrations" && typeof plan.safe_to_apply === "boolean" && typeof plan.plan_checksum === "string" && Array.isArray(plan.pending) && Array.isArray(plan.applied) && Array.isArray(plan.blocked) && Array.isArray(plan.warnings) && typeof plan.requires_destructive_confirmation === "boolean";
-}
 function projectPath(ref) {
   return `/v1/projects/${encodeURIComponent(ref)}/branches`;
 }
@@ -188828,14 +189368,10 @@ function readOnlyResult() {
     content: [{ type: "text", text: "⚠️ Branch write blocked in read-only mode." }]
   };
 }
-function formatPromotionResult(responseValue) {
-  if (!responseValue || typeof responseValue !== "object")
-    return "Migrations promoted.";
-  const response = responseValue;
-  const applied = Array.isArray(response.applied) ? response.applied : [];
-  const versions = applied.map((entry) => entry && typeof entry === "object" ? entry.version : null).filter((version) => typeof version === "string");
+function formatPromotionResult(response) {
+  const versions = response.applied.map((entry) => entry.version);
   return [
-    `Migration promotion completed: ${applied.length} applied.`,
+    `Migration promotion completed: ${response.applied.length} applied.`,
     ...versions.length > 0 ? [`Versions: ${versions.join(", ")}`] : [],
     "Branch data was not automatically copied to the parent project."
   ].join(`
@@ -188855,13 +189391,19 @@ function registerBranchTools(server2, http, options = {}) {
     name: optional(String2(), "[create] Branch name"),
     data_mode: optional(stringEnum(["schema_only", "full_clone"]), "[create] Preview data mode (default: schema_only)"),
     plan_checksum: optional(String2(), "[promote] Reviewed plan checksum from promotion_plan"),
-    confirm_destructive: optional(Boolean2(), "[promote] Confirm reviewed destructive migrations")
+    confirm_destructive: optional(Boolean2(), "[promote] Confirm reviewed destructive migrations"),
+    json: optional(Boolean2(), "[promotion_plan/promote] Return machine-readable JSON")
   }, async (args) => {
     const action = requireString(args.action, "action");
     const ref = resolveProjectRef(args.ref, options.projectRef);
     const writeAction = action === "create" || action === "delete" || action === "promote";
-    if (writeAction && options.readOnly)
-      return readOnlyResult();
+    if (writeAction && options.readOnly) {
+      return args.json && action === "promote" ? releaseControlFailure("branch.promote", "MUTATION_NOT_SUCCEEDED", null, {
+        project_ref: ref,
+        branch_ref: args.branch_ref,
+        reason: "READ_ONLY"
+      }) : readOnlyResult();
+    }
     let result;
     if (action === "list") {
       result = await http.get(projectPath(ref));
@@ -188876,29 +189418,91 @@ function registerBranchTools(server2, http, options = {}) {
       result = await http.delete(branchPath(ref, branchRef));
     } else if (action === "promotion_plan") {
       const branchRef = requireString(args.branch_ref, "branch_ref");
-      result = await http.get(`${branchPath(ref, branchRef)}/promote/plan`);
-      if (result.ok && isPromotionPlan(result.data)) {
-        return { content: [{ type: "text", text: formatPromotionPlan(result.data) }] };
+      const scope = { project_ref: ref, branch_ref: branchRef };
+      result = await http.get(`${branchPath(ref, branchRef)}/promote/plan`, {
+        maxJsonBytes: PROMOTION_PLAN_MAX_JSON_BYTES,
+        responseTimeoutMs: 5000
+      });
+      if (!result.ok) {
+        return promotionFailure(releaseControlFailure("branch.promotion_plan", "HTTP_ERROR", result.transportError ? null : result.status, scope), args.json === true, false);
       }
+      const plan = parsePromotionPlan(result.data, { parentRef: ref, branchRef });
+      if (result.status !== 200 || !plan) {
+        return promotionFailure(releaseControlFailure("branch.promotion_plan", "INVALID_RESPONSE", result.status, scope), args.json === true, false);
+      }
+      return args.json ? releaseControlSuccess("branch.promotion_plan", { ...scope, plan }) : { content: [{ type: "text", text: formatPromotionPlan(plan) }] };
     } else if (action === "promote") {
       const branchRef = requireString(args.branch_ref, "branch_ref");
       const planChecksum = requireString(args.plan_checksum, "plan_checksum");
+      if (!isSha256(planChecksum))
+        throw new Error("'plan_checksum' must be a 64-character lowercase SHA-256 checksum");
+      const state = {
+        project_ref: ref,
+        branch_ref: branchRef,
+        plan_checksum: planChecksum,
+        automatic_retry: false,
+        reconciliation: { action: "promotion_plan", ref, branch_ref: branchRef }
+      };
+      const preflight = await http.get(`${branchPath(ref, branchRef)}/promote/plan`, {
+        maxJsonBytes: PROMOTION_PLAN_MAX_JSON_BYTES,
+        responseTimeoutMs: 5000
+      });
+      const beforeMutation = { ...state, mutation_sent: false };
+      if (!preflight.ok) {
+        return promotionFailure(releaseControlFailure("branch.promote", "HTTP_ERROR", preflight.transportError ? null : preflight.status, { ...beforeMutation, reason: "PREFLIGHT_FAILED" }), args.json === true, false);
+      }
+      const plan = parsePromotionPlan(preflight.data, { parentRef: ref, branchRef });
+      if (preflight.status !== 200 || !plan) {
+        return promotionFailure(releaseControlFailure("branch.promote", "INVALID_RESPONSE", preflight.status, { ...beforeMutation, reason: "PREFLIGHT_UNVERIFIED" }), args.json === true, false);
+      }
+      const preflightReason = plan.plan_checksum !== planChecksum ? "PLAN_CHANGED" : !plan.safe_to_apply ? "PLAN_BLOCKED" : plan.requires_destructive_confirmation && args.confirm_destructive !== true ? "DESTRUCTIVE_CONFIRMATION_REQUIRED" : null;
+      if (preflightReason) {
+        return promotionFailure(releaseControlFailure("branch.promote", "MUTATION_NOT_SUCCEEDED", null, { ...beforeMutation, reason: preflightReason, observed_plan_checksum: plan.plan_checksum }), args.json === true, false);
+      }
+      if (plan.pending.length === 0) {
+        return args.json ? releaseControlSuccess("branch.promote", {
+          ...beforeMutation,
+          promoted: false,
+          unchanged: true,
+          mode: "migrations",
+          applied: [],
+          plan,
+          branch_data_copied: false,
+          reviewed_plan_checksum: planChecksum
+        }) : { content: [{ type: "text", text: "Migration promotion unchanged: no pending migrations; no promotion request sent." }] };
+      }
       result = await http.post(`${branchPath(ref, branchRef)}/promote`, {
         mode: "migrations",
         plan_checksum: planChecksum,
         confirm_destructive: args.confirm_destructive === true
+      }, {
+        maxJsonBytes: PROMOTION_PLAN_MAX_JSON_BYTES,
+        responseTimeoutMs: 5000,
+        timeoutMs: 30000
       });
+      if (!result.ok) {
+        return promotionFailure(releaseControlMutationFailure("branch.promote", result, {
+          ...state,
+          mutation_sent: true,
+          reported_applied_versions: appliedVersions(result),
+          ...safePromotionCode(result) ? { server_code: safePromotionCode(result) } : {}
+        }), args.json === true, result.transportError === true || result.responseReadError === true || result.status === 408 || result.status >= 500);
+      }
+      const promoted = parsePromotionResult(result.data, { parentRef: ref, branchRef }, plan.pending);
+      if (result.status !== 200 || !promoted) {
+        return promotionFailure(releaseControlFailure("branch.promote", "OUTCOME_UNKNOWN", result.status, { ...state, mutation_sent: true }), args.json === true, true);
+      }
+      return args.json ? releaseControlSuccess("branch.promote", {
+        ...promoted,
+        unchanged: false,
+        mutation_sent: true,
+        reviewed_plan_checksum: planChecksum
+      }) : { content: [{ type: "text", text: formatPromotionResult(promoted) }] };
     } else {
       throw new Error(`Unknown branch action: ${action}`);
     }
     if (!result.ok) {
-      return {
-        isError: true,
-        content: [{ type: "text", text: `❌ ${responseError(result)}` }]
-      };
-    }
-    if (action === "promote") {
-      return { content: [{ type: "text", text: formatPromotionResult(result.data) }] };
+      return { isError: true, content: [{ type: "text", text: responseError(result) }] };
     }
     return { content: [{ type: "text", text: JSON.stringify(result.data, null, 2) }] };
   });
@@ -189433,7 +190037,7 @@ import { resolve as resolve11 } from "node:path";
 // src/shared/tools/lite-cli-command.ts
 import { existsSync as existsSync8, readFileSync as readFileSync7, statSync as statSync6 } from "node:fs";
 import { isAbsolute as isAbsolute3, join as join8, relative as relative3, resolve as resolve10 } from "node:path";
-function isRecord4(value) {
+function isRecord5(value) {
   return value !== null && typeof value === "object" && !Array.isArray(value);
 }
 function resolveLiteCommand(workdir, environment = process.env) {
@@ -189448,7 +190052,7 @@ function resolveLiteCommand(workdir, environment = process.env) {
   if (!existsSync8(manifestPath))
     return ["supacloud-lite"];
   const manifest = JSON.parse(readFileSync7(manifestPath, "utf8"));
-  if (!isRecord4(manifest) || manifest.name !== "@supacloud/lite" || !isRecord4(manifest.bin)) {
+  if (!isRecord5(manifest) || manifest.name !== "@supacloud/lite" || !isRecord5(manifest.bin)) {
     throw new Error("Invalid installed @supacloud/lite package manifest");
   }
   const entry = manifest.bin["supacloud-lite"];
@@ -193380,18 +193984,30 @@ var REMOTE_APP_ACTIONS = {
   rollback: "activate_release",
   reconcile: "reconcile_activation",
   retire: "retire_activation",
-  logs: "logs"
+  logs: "logs",
+  "preview-plan": "get_preview_plan",
+  preview: "create_preview",
+  previews: "list_previews",
+  "preview-status": "get_preview",
+  "preview-cleanup": "cleanup_preview"
 };
 var REMOTE_APP_DESCRIPTIONS = {
-  ref: "[upload/configure/deploy/status/rollback/reconcile/retire] Project ref (defaults to context)",
-  id: "[upload/configure/deploy/status/rollback/reconcile/retire] Application ID",
-  environment_id: "[configure/deploy/status/rollback/reconcile/retire] Environment ID",
-  configuration_id: "[deploy/rollback] Required immutable configuration revision",
+  ref: "[upload/configure/deploy/status/rollback/reconcile/retire/preview-plan/preview/previews/preview-status/preview-cleanup] Project ref (defaults to context)",
+  id: "[upload/configure/deploy/status/rollback/reconcile/retire/preview-plan/preview/previews/preview-status/preview-cleanup] Application ID",
+  environment_id: "[configure/deploy/status/rollback/reconcile/retire/preview-plan/preview/previews/preview-status/preview-cleanup] Environment ID",
+  configuration_id: "[deploy/rollback/preview] Required immutable configuration revision",
   activation_id: "[deploy/rollback/reconcile/retire] Required explicit activation ID",
   expected_activation_id: "[deploy/rollback] Required current activation ID, or absent for first activation",
   configuration_path: "[configure] Configuration write JSON including revision and expected revision",
   manifest_path: "[upload] Local delivery.manifest.json",
-  release_id: "[deploy/rollback/reconcile] Required immutable application release ID"
+  release_id: "[deploy/rollback/reconcile/preview-plan/preview] Required immutable application release ID",
+  preview_id: "[preview-status/preview-cleanup] Preview receipt ID",
+  branch_ref: "[preview-plan] Proposed branch ref; preview assigns its own",
+  branch_name: "[preview] Branch display name",
+  data_mode: "[preview-plan/preview] Default schema_only; full_clone copies rows",
+  ttl_seconds: "[preview-plan/preview] Lifetime from 300 to 604800 seconds; creation defaults to the platform TTL",
+  wait: "[preview/preview-status] Wait for verified readiness of the selected preview",
+  timeout_seconds: "[preview/preview-status] Observation budget with --wait, from 1 to 3600 seconds (default 300)"
 };
 var { action: _remoteAction, ...remoteFields } = APPLICATION_TOOL_SCHEMA;
 var REMOTE_APP_SCHEMA = Partial(_Object_(remoteFields)).properties;
@@ -194396,7 +195012,12 @@ function registerAppTools(server2, options = {}) {
       "rollback",
       "reconcile",
       "retire",
-      "logs"
+      "logs",
+      "preview-plan",
+      "preview",
+      "previews",
+      "preview-status",
+      "preview-cleanup"
     ]), "App action; upload/configure only prepare, rollback activates an explicit old release without schema downgrade"),
     kind: optional(stringEnum(["module", "command", "query", "controller", "job", "contract", "resource"]), "[generate] Scaffold kind"),
     template: optional(stringEnum(["minimal", "http", "command", "edge"]), "[init] Minimal application by default; explicit http/command/edge recipes"),
@@ -195840,7 +196461,7 @@ var RELEASE_CANARY_DISABLE_RECEIPT_KEYS = new Set(["fixtureId", "state", "idempo
 var RELEASE_CANARY_DISABLE_RPC_PATH = "/rest/v1/rpc/fa_release_canary_fixture_disable";
 var RELEASE_CANARY_PENDING_RPC_PATH = "/rest/v1/rpc/fa_release_canary_fixture_pending";
 var RELEASE_CANARY_CLAIM_MAX_LENGTH = 2048;
-function isRecord5(value) {
+function isRecord6(value) {
   return value !== null && typeof value === "object" && !Array.isArray(value);
 }
 function canonicalTimestamp4(value) {
@@ -195856,7 +196477,7 @@ function backupBelongsToProject(backupId, projectRef) {
   return BACKUP_ID.test(backupId) && backupId.startsWith(`logical-full_${projectRef}_`);
 }
 function verifiedBackup(value, projectRef) {
-  if (!isRecord5(value) || typeof value.backup_id !== "string" || !backupBelongsToProject(value.backup_id, projectRef) || value.project_ref !== projectRef || typeof value.database !== "string" || !SAFE_DATABASE.test(value.database) || value.kind !== "logical-full" || !canonicalTimestamp4(value.created_at) || !canonicalTimestamp4(value.completed_at) || new Date(value.completed_at).valueOf() < new Date(value.created_at).valueOf() || typeof value.bytes !== "number" || !Number.isSafeInteger(value.bytes) || value.bytes <= 0 || typeof value.sha256 !== "string" || !SHA256.test(value.sha256))
+  if (!isRecord6(value) || typeof value.backup_id !== "string" || !backupBelongsToProject(value.backup_id, projectRef) || value.project_ref !== projectRef || typeof value.database !== "string" || !SAFE_DATABASE.test(value.database) || value.kind !== "logical-full" || !canonicalTimestamp4(value.created_at) || !canonicalTimestamp4(value.completed_at) || new Date(value.completed_at).valueOf() < new Date(value.created_at).valueOf() || typeof value.bytes !== "number" || !Number.isSafeInteger(value.bytes) || value.bytes <= 0 || typeof value.sha256 !== "string" || !SHA256.test(value.sha256))
     return null;
   return {
     backup_id: value.backup_id,
@@ -195870,7 +196491,7 @@ function verifiedBackup(value, projectRef) {
   };
 }
 function backupInventory(value, projectRef) {
-  if (!isRecord5(value) || !Array.isArray(value.backups))
+  if (!isRecord6(value) || !Array.isArray(value.backups))
     return null;
   const backups = value.backups.map((backup) => verifiedBackup(backup, projectRef));
   if (backups.some((backup) => backup === null))
@@ -195949,7 +196570,7 @@ function readInventoryFailure(operation, read) {
   return null;
 }
 function postgrestStatus(value) {
-  if (!isRecord5(value) || value.component !== "postgrest" || !["running", "stopped"].includes(String(value.desired)) || !["running", "stopped", "starting", "error"].includes(String(value.actual)) || !["healthy", "unhealthy", "unknown"].includes(String(value.health)))
+  if (!isRecord6(value) || value.component !== "postgrest" || !["running", "stopped"].includes(String(value.desired)) || !["running", "stopped", "starting", "error"].includes(String(value.actual)) || !["healthy", "unhealthy", "unknown"].includes(String(value.health)))
     return null;
   return {
     desired: value.desired,
@@ -195970,7 +196591,7 @@ function readPostgrestFailure(operation, read) {
   return read.response.status === 200 && read.status ? null : releaseControlFailure(operation, "INVALID_RESPONSE", read.response.status);
 }
 function isRestartReceipt(value) {
-  return isRecord5(value) && value.service === "postgrest" && value.action === "restart" && value.success === true;
+  return isRecord6(value) && value.service === "postgrest" && value.action === "restart" && value.success === true;
 }
 function releaseCanaryStageInput(subject, requestId) {
   if (typeof subject !== "string" || !UUID.test(subject))
@@ -195980,7 +196601,7 @@ function releaseCanaryStageInput(subject, requestId) {
   return { p_subject: subject, p_request_id: requestId };
 }
 function releaseCanaryStageReceipt(value) {
-  if (!isRecord5(value) || Object.keys(value).some((key) => !RELEASE_CANARY_STAGE_RECEIPT_KEYS.has(key)) || Object.keys(value).length !== RELEASE_CANARY_STAGE_RECEIPT_KEYS.size || typeof value.fixtureId !== "string" || !UUID.test(value.fixtureId) || typeof value.tenantKey !== "string" || !RELEASE_CANARY_TENANT_KEY.test(value.tenantKey) || value.state !== "staged" || value.idempotent !== true)
+  if (!isRecord6(value) || Object.keys(value).some((key) => !RELEASE_CANARY_STAGE_RECEIPT_KEYS.has(key)) || Object.keys(value).length !== RELEASE_CANARY_STAGE_RECEIPT_KEYS.size || typeof value.fixtureId !== "string" || !UUID.test(value.fixtureId) || typeof value.tenantKey !== "string" || !RELEASE_CANARY_TENANT_KEY.test(value.tenantKey) || value.state !== "staged" || value.idempotent !== true)
     return null;
   return {
     fixtureId: value.fixtureId,
@@ -196023,7 +196644,7 @@ function releaseCanaryDisableInput(fixtureId, disableRequestId, issuer, subject)
   };
 }
 function releaseCanaryDisableReceipt(receiptCandidate, fixtureId) {
-  if (!isRecord5(receiptCandidate) || Object.keys(receiptCandidate).some((key) => !RELEASE_CANARY_DISABLE_RECEIPT_KEYS.has(key)) || Object.keys(receiptCandidate).length !== RELEASE_CANARY_DISABLE_RECEIPT_KEYS.size || receiptCandidate.fixtureId !== fixtureId || receiptCandidate.state !== "disabled" || typeof receiptCandidate.idempotent !== "boolean")
+  if (!isRecord6(receiptCandidate) || Object.keys(receiptCandidate).some((key) => !RELEASE_CANARY_DISABLE_RECEIPT_KEYS.has(key)) || Object.keys(receiptCandidate).length !== RELEASE_CANARY_DISABLE_RECEIPT_KEYS.size || receiptCandidate.fixtureId !== fixtureId || receiptCandidate.state !== "disabled" || typeof receiptCandidate.idempotent !== "boolean")
     return null;
   return { fixtureId, state: "disabled", idempotent: receiptCandidate.idempotent };
 }
@@ -196196,7 +196817,7 @@ function handleScopeRebind(args) {
     } catch {
       throw new Error(`Scope file '${filePath}' is not valid JSON`);
     }
-    if (!isRecord5(parsed) || typeof parsed.baseCommit !== "string" || !/^[0-9a-f]{40}$/.test(parsed.baseCommit)) {
+    if (!isRecord6(parsed) || typeof parsed.baseCommit !== "string" || !/^[0-9a-f]{40}$/.test(parsed.baseCommit)) {
       throw new Error(`Scope file '${filePath}' has missing or invalid baseCommit`);
     }
     const previousBaseCommit = parsed.baseCommit;
@@ -196260,7 +196881,7 @@ function handleScopeInspect(args) {
   } catch {
     throw new Error(`Scope file '${args.file}' is not valid JSON`);
   }
-  if (!isRecord5(parsed) || typeof parsed.baseCommit !== "string" || !/^[0-9a-f]{40}$/.test(parsed.baseCommit)) {
+  if (!isRecord6(parsed) || typeof parsed.baseCommit !== "string" || !/^[0-9a-f]{40}$/.test(parsed.baseCommit)) {
     throw new Error(`Scope file '${args.file}' has missing or invalid baseCommit`);
   }
   const scopeSha256 = genericScopedReleaseScopeSha256(parsed);
@@ -196422,7 +197043,7 @@ function registerReleaseTools(server2, http, options = {}) {
       if (!mutation.ok || mutation.status !== 200) {
         return mutationFailure("release.logical_backup.create", mutation);
       }
-      const responseBackup = isRecord5(mutation.data) ? verifiedBackup(mutation.data.backup, projectRef) : null;
+      const responseBackup = isRecord6(mutation.data) ? verifiedBackup(mutation.data.backup, projectRef) : null;
       const afterFailure = readInventoryFailure("release.logical_backup.create", after);
       const addedBackup = after.inventory && newlyCreatedBackup(before.inventory, after.inventory);
       if (!responseBackup || afterFailure || !addedBackup || !equalBackup(responseBackup, addedBackup)) {
@@ -196447,7 +197068,7 @@ function registerReleaseTools(server2, http, options = {}) {
       if (!mutation.ok || mutation.status !== 200) {
         return mutationFailure("release.logical_backup.restore", mutation);
       }
-      const responseBackup = isRecord5(mutation.data) ? verifiedBackup(mutation.data.restored_backup, projectRef) : null;
+      const responseBackup = isRecord6(mutation.data) ? verifiedBackup(mutation.data.restored_backup, projectRef) : null;
       const after = await readInventory(http, projectRef);
       const afterFailure = readInventoryFailure("release.logical_backup.restore", after);
       const restoredInventoryBackup = after.inventory?.find((backup) => backup.backup_id === request.backup_id);
@@ -197964,7 +198585,7 @@ function registerRemoteDevTools(server2, options = {}) {
 // package.json
 var package_default = {
   name: "@supacloud/cli",
-  version: "0.77.0",
+  version: "0.78.0",
   description: "Project-scoped CLI for SupaCloud users",
   type: "module",
   main: "./dist/index.js",
@@ -198286,6 +198907,11 @@ EXAMPLES
   ${preferredCommand} app configure --ref abc123 --id orders --environment_id test --configuration_path configuration.json
   ${preferredCommand} app deploy --ref abc123 --id orders --environment_id test --release_id <sha256> --configuration_id <uuid> --activation_id <uuid> --expected_activation_id absent
   ${preferredCommand} app status --ref abc123 --id orders --environment_id test
+  ${preferredCommand} app preview-plan --ref abc123 --id orders --environment_id test --release_id <sha256> --branch_ref preview-orders
+  ${preferredCommand} app preview --ref abc123 --id orders --environment_id test --release_id <sha256> --configuration_id <uuid> --ttl_seconds 3600 --wait
+  ${preferredCommand} app previews --ref abc123 --id orders --environment_id test
+  ${preferredCommand} app preview-status --ref abc123 --id orders --environment_id test --preview_id <uuid> --wait --timeout_seconds 300
+  ${preferredCommand} app preview-cleanup --ref abc123 --id orders --environment_id test --preview_id <uuid>
   ${preferredCommand} app logs --ref abc123 --id orders --environment_id test
   ${preferredCommand} app rollback --ref abc123 --id orders --environment_id test --release_id <old-sha256> --configuration_id <uuid> --activation_id <new-uuid> --expected_activation_id <current-uuid>
   ${preferredCommand} app check --root . --strict

package/dist/shared/tools/app-tools.d.ts

@@ -9,6 +9,11 @@ declare const REMOTE_APP_ACTIONS: {
     readonly reconcile: "reconcile_activation";
     readonly retire: "retire_activation";
     readonly logs: "logs";
+    readonly "preview-plan": "get_preview_plan";
+    readonly preview: "create_preview";
+    readonly previews: "list_previews";
+    readonly "preview-status": "get_preview";
+    readonly "preview-cleanup": "cleanup_preview";
 };
 export interface AppToolOptions {
     getApplications?: () => ((args: Record<string, unknown>) => Promise<ToolResult>) | undefined;
@@ -29,6 +34,13 @@ export interface AppToolArguments {
     configuration_path?: string;
     manifest_path?: string;
     release_id?: string;
+    preview_id?: string;
+    branch_ref?: string;
+    branch_name?: string;
+    data_mode?: "schema_only" | "full_clone";
+    ttl_seconds?: number;
+    wait?: boolean;
+    timeout_seconds?: number;
     kind?: "module" | "command" | "query" | "controller" | "job" | "contract" | "resource";
     template?: "minimal" | "http" | "command" | "edge";
     name?: string;

package/dist/shared/tools/application-preview-tools.d.ts

@@ -0,0 +1,74 @@
+import { Type, type Static } from "typebox";
+import type { HttpTransport } from "../transports/http";
+export declare const APPLICATION_PREVIEW_ACTIONS: readonly ["get_preview_plan", "create_preview", "list_previews", "get_preview", "cleanup_preview"];
+export declare const APPLICATION_PREVIEW_FIELDS: {
+    preview_id: Type.TOptional<Type.TString>;
+    branch_ref: Type.TOptional<Type.TString>;
+    branch_name: Type.TOptional<Type.TString>;
+    data_mode: Type.TOptional<Type.TEnum<("schema_only" | "full_clone")[]>>;
+    ttl_seconds: Type.TOptional<Type.TInteger>;
+    wait: Type.TOptional<Type.TBoolean>;
+    timeout_seconds: Type.TOptional<Type.TInteger>;
+};
+declare const receiptSchema: Type.TObject<{
+    schema: Type.TLiteral<"supacloud.application-preview.v1">;
+    preview_id: Type.TString;
+    project_ref: Type.TString;
+    application_id: Type.TString;
+    environment_id: Type.TString;
+    release_id: Type.TString;
+    expires_at: Type.TUnion<[Type.TString, Type.TNull]>;
+    status: Type.TEnum<("failed" | "ready" | "planned" | "cleaned" | "provisioning")[]>;
+    resources: Type.TObject<{
+        build_artifact: Type.TObject<{
+            status: Type.TEnum<("pending" | "failed" | "ready" | "cleaned")[]>;
+            release_id: Type.TString;
+        }>;
+        database_branch: Type.TObject<{
+            status: Type.TEnum<("pending" | "failed" | "ready" | "cleaned")[]>;
+            branch_ref: Type.TString;
+            data_mode: Type.TEnum<("schema_only" | "full_clone")[]>;
+        }>;
+        queue_namespace: Type.TObject<{
+            status: Type.TEnum<("pending" | "failed" | "ready" | "cleaned")[]>;
+            namespace: Type.TString;
+        }>;
+        storage_namespace: Type.TObject<{
+            status: Type.TEnum<("pending" | "failed" | "ready" | "cleaned")[]>;
+            namespace: Type.TString;
+        }>;
+        test_secret: Type.TObject<{
+            status: Type.TEnum<("pending" | "failed" | "ready" | "cleaned")[]>;
+            name: Type.TString;
+            value_issued: Type.TLiteral<false>;
+        }>;
+        configuration_revision: Type.TObject<{
+            status: Type.TEnum<("pending" | "failed" | "ready" | "cleaned")[]>;
+            configuration_id: Type.TUnion<[Type.TString, Type.TNull]>;
+        }>;
+        application_activation: Type.TObject<{
+            status: Type.TEnum<("pending" | "failed" | "ready" | "cleaned")[]>;
+            activation_id: Type.TUnion<[Type.TString, Type.TNull]>;
+        }>;
+        smoke_test: Type.TObject<{
+            status: Type.TEnum<("pending" | "failed" | "ready" | "cleaned")[]>;
+            checks: Type.TArray<Type.TString>;
+            passed: Type.TArray<Type.TString>;
+            failed: Type.TArray<Type.TString>;
+        }>;
+    }>;
+    cleanup: Type.TObject<{
+        required: Type.TBoolean;
+        completed: Type.TBoolean;
+        error: Type.TUnion<[Type.TString, Type.TNull]>;
+    }>;
+    branch_name: Type.TOptional<Type.TString>;
+    queue_name: Type.TOptional<Type.TString>;
+    test_secret_name: Type.TOptional<Type.TString>;
+    source_configuration_id: Type.TOptional<Type.TUnion<[Type.TString, Type.TNull]>>;
+    created_at: Type.TOptional<Type.TString>;
+    updated_at: Type.TOptional<Type.TString>;
+}>;
+export declare function applicationPreviewAction(http: HttpTransport, args: Record<string, unknown>, project: string): Promise<import("./release-control-response").ReleaseControlToolResponse>;
+export type ApplicationPreviewReceipt = Static<typeof receiptSchema>;
+export {};

package/dist/shared/tools/application-preview-tools.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/shared/tools/application-tools.d.ts

@@ -2,7 +2,14 @@ import { Type } from "typebox";
 import type { HttpTransport } from "../transports/http";
 import { type ToolServer } from "../tool-server";
 export declare const APPLICATION_TOOL_SCHEMA: {
-    action: Type.TEnum<("list_releases" | "get_release" | "upload_release" | "activate_release" | "logs" | "get_runtime" | "get_deployment_evidence" | "get_configuration" | "put_configuration" | "reconcile_activation" | "retire_activation")[]>;
+    preview_id: Type.TOptional<Type.TString>;
+    branch_ref: Type.TOptional<Type.TString>;
+    branch_name: Type.TOptional<Type.TString>;
+    data_mode: Type.TOptional<Type.TEnum<("schema_only" | "full_clone")[]>>;
+    ttl_seconds: Type.TOptional<Type.TInteger>;
+    wait: Type.TOptional<Type.TBoolean>;
+    timeout_seconds: Type.TOptional<Type.TInteger>;
+    action: Type.TEnum<("list_releases" | "get_release" | "upload_release" | "activate_release" | "logs" | "get_runtime" | "get_deployment_evidence" | "get_configuration" | "get_preview_plan" | "put_configuration" | "reconcile_activation" | "retire_activation" | "create_preview" | "list_previews" | "get_preview" | "cleanup_preview")[]>;
     ref: Type.TString;
     id: Type.TString;
     environment_id: Type.TOptional<Type.TString>;

package/dist/shared/tools/branch-promotion-http-status.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/shared/tools/branch-tools.d.ts

@@ -1,6 +1,7 @@
 import type { HttpTransport } from "../transports/http";
 import { type ToolServer } from "../tool-server";
-export declare function registerBranchTools(server: ToolServer, http: HttpTransport, options?: {
+export type BranchHttpTransport = Pick<HttpTransport, "get" | "post" | "delete">;
+export declare function registerBranchTools(server: ToolServer, http: BranchHttpTransport, options?: {
     projectRef?: string;
     readOnly?: boolean;
 }): void;

package/dist/shared/transports/http.d.ts

@@ -18,6 +18,10 @@ export interface HttpResult<T = unknown> {
     responseReadError?: true;
 }
 export interface HttpGetOptions {
+    timeoutMs?: number;
+    retry?: boolean;
+    /** Complete header/body budget for a bounded JSON GET with retries disabled. */
+    totalTimeoutMs?: number;
     maxResponseBytes?: number;
     maxJsonBytes?: number;
     responseTimeoutMs?: number;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@supacloud/cli",
-  "version": "0.77.0",
+  "version": "0.78.0",
   "description": "Project-scoped CLI for SupaCloud users",
   "type": "module",
   "main": "./dist/index.js",