@supacloud/cli 0.77.0 → 0.79.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