@stacksjs/defaults 0.70.365 → 0.70.367

package/ai/skills/stacks-browse/SKILL.md

@@ -45,6 +45,11 @@ you to `brew install --cask chromium` or set `BROWSE_BROWSER`.
 - Docs: `http://localhost:3005`
 - API: `http://localhost:3008`
 
+For headless dashboard QA, start the server with
+`STACKS_NO_NATIVE=1 ./buddy dev --dashboard`. Never point `CRAFT_BIN` at a
+missing file to suppress the native window because invalid binary overrides are
+configuration errors.
+
 > Pages with an open HMR/SSE connection never reach "network idle"; the driver waits for
 > the load event (with a timeout) plus a short settle, so it won't hang on the dev server.
 
@@ -133,7 +138,10 @@ diagnostics without printing every visited path or overflowing element.
 
 When testing a Stacks app, check:
 - **Dashboard routes** — admin pages rendering? (`localhost:3002`)
-- **API health** — `GET localhost:3008/health` returns ok?
+- **API health** — `GET localhost:3008/api/health` returns ok? (`/api/health`, not
+  `/health`: the probe is mounted under `/api` so it cannot collide with a page of
+  the same name, and the API port answers `/api` only - every other path is a 404
+  there by design, so point page checks at the frontend instead.)
 - **Auth flow** — `/login`, `/register`
 - **CMS/blog** — `/blog`, post detail pages, `/blog/feed.xml`, `/blog/sitemap.xml`
 - **STX components** — do custom components render server-side?

package/ai/skills/stacks-dashboard/SKILL.md

@@ -111,12 +111,60 @@ inject message HTML into the dashboard document.
 - `/deployments/{id}` - one persisted Deployment model record
 
 The deployment page composes `DeploymentList`, `DeploymentTable`,
-`DeployScript`, and `LiveTerminalOutput`. Script reads and atomic writes use
+`DeploymentPreviewDialog`, `DeployScript`, and `LiveTerminalOutput`. The
+Preview action first collects the environment and optional domain, then calls
+the guarded `POST /api/dashboard/deployments/preview` Action. That Action runs
+the native `buddy deploy --dry-run --json` planner and returns its versioned,
+non-mutating plan. The dialog renders the ordered operations and resolved sites
+before the user may continue to the separate real deployment confirmation.
+Script reads and atomic writes use
 `GET|PUT /api/dashboard/deployments/script`. The terminal uses
 `GET /api/dashboard/deployments/terminal` and pauses polling while the document
 is hidden. Do not create separate `/deployments/scripts` or
 `/deployments/live-terminal` pages.
 
+Deployment recovery uses `POST /api/dashboard/deployments/rollback/preview`
+followed by `POST /api/dashboard/deployments/rollback`. The preview must run
+the native `buddy deploy:rollback --dry-run` path successfully, and execution
+must re-run that preview, compare its revision, and require the typed target
+environment confirmation. Never implement rollback by editing release links,
+restarting services directly, or guessing a prior release from Deployment
+model rows. Deployment rows are application history. Preserved releases and
+activation are owned by ts-cloud.
+
+### Operations control plane
+
+The Operations sidebar entry deliberately remains one item. Section navigation
+lives in `Dashboard/Operations/OperationsNavigation.stx`:
+
+- `/operations/changes` - unified change review, active work, release approvals
+- `/operations/scheduler` - registered task runs and persisted pause state
+- `/operations/recovery` - destinations, policies, recovery points, restore drills
+- `/operations/migrations` - model diff, schema effects, ledger reconciliation
+- `/operations/incidents` - native alerts, health rules, ownership, silence state
+- `/operations/audit` - append-only operator events and correlations
+
+Operational state belongs in the ts-cloud control plane initialized by
+`Operations/control-plane.ts`. Use its stores for durable operations, events,
+releases, approvals, alerts, backups, actors, and environments. Do not create a
+parallel dashboard-only JSON file or duplicate those entities in application
+models. Application domain records still follow the normal `app/Models` and
+`useApi` convention. Use dashboard Actions for aggregate operational views and
+guard every route in `dashboard-api.ts`.
+
+Every mutating operator action must resolve the authenticated actor and append
+or correlate a control-plane event. Use `trackOperatorOperation()` for bounded
+synchronous work and the native durable queue for long-running backup, restore,
+or provider work. Empty states must reflect real absence of configuration or
+events. Never seed operational pages with sample incidents, releases, backups,
+or health data.
+
+Migration execution must start from `previewPendingMigrations()`, audit the
+ledger against live schema effects, hash the reviewed plan, and recheck it
+immediately before `buddy migrate`. Only `reconcileMigrationLedger()` may
+repair provable ledger drift. Partial and unverifiable migrations require human
+review and must not be silently recorded.
+
 ### Utilities
 - `/health`, `/insights`, `/logs` - operational health and logs
 - `/servers`, `/serverless`, `/realtime` - runtime infrastructure
@@ -354,20 +402,19 @@ drawers must use the shared `dashboard-modal-layer` class so their interactive
 surface starts beside that sidebar and returns to `left: 0` on mobile and in
 the Craft native-sidebar shell.
 
-Use the shared `Dashboard/UI/Modal` and `Dashboard/UI/ConfirmDialog`
-components when possible. A custom overlay root must use this shape:
-
-```html
-<div class="fixed inset-y-0 overflow-y-auto right-0 z-[55] dashboard-modal-layer">
-  <button class="absolute inset-0" aria-label="Close dialog"></button>
-  <!-- dialog panel -->
-</div>
-```
+Use `Dashboard/UI/Modal`, `Dashboard/UI/Drawer`, and
+`Dashboard/UI/ConfirmDialog` for page dialogs, inspectors, forms, and
+confirmations. They own native `<dialog>` behavior, scroll locking, focus
+restoration, Escape and backdrop handling, accessibility labels, and the
+sidebar-aware boundary. `Dashboard/Modals/BaseModal` and
+`Dashboard/Modals/Popups/Alert` are compatibility wrappers over that same
+primitive, not alternate overlay implementations.
 
-Do not solve sidebar overlap by increasing z-index alone. That places the
-dialog above the sidebar without centering it in the available content area.
-Keep overlay children `absolute`, not `fixed`, so they remain bounded by the
-sidebar-aware root.
+Do not add a page-owned `fixed inset-0` overlay. A purpose-built application
+surface such as the global command palette or mobile navigation may own a
+custom layer only when the shared dialog or drawer semantics do not fit. It
+must still use `dashboard-modal-layer` and provide complete keyboard, focus,
+and ARIA behavior. Do not solve sidebar overlap by increasing z-index alone.
 
 ### Live dashboard audit
 
@@ -378,6 +425,9 @@ the project root:
 bun storage/framework/defaults/ai/skills/stacks-dashboard/scripts/audit.ts
 # Or target a non-default origin:
 bun storage/framework/defaults/ai/skills/stacks-dashboard/scripts/audit.ts --base-url http://127.0.0.1:3002
+
+# Exercise hydrated navigation, console errors, failed requests, and layout:
+bun storage/framework/defaults/ai/skills/stacks-browse/scripts/browse.ts crawl http://localhost:3002/ --max 500 --settle 350 --summary
 ```
 
 Pass a base URL as the first argument when the dashboard is not on
@@ -388,6 +438,13 @@ dashboard API. It fails on missing page renders, invalid fragment contracts,
 empty or non-HTML pages, unresolved component tags, 5xx or method-mismatch
 APIs, HTML API fallbacks, invalid JSON, and HTTP-200 error payloads.
 
+The dependency-free browser crawl follows the rendered link graph in a real
+browser and fails on non-200 pages, console errors, failed subrequests, or
+horizontal overflow. Seed source-only routes with repeated `--path` flags,
+including optional or parameterized pages that the current data set does not
+link. The HTTP audit and browser crawl cover different boundaries, so run both
+for exhaustive dashboard work.
+
 Run this after dashboard route, Action, STX, model, migration, or dev-server
 changes. Record provider-backed or destructive success paths as explicit
 environment boundaries. Never replace a failed live contract with sample data

package/ai/skills/stacks-deploy/SKILL.md

@@ -16,6 +16,23 @@ The deployment workflow for Stacks applications.
 buddy deploy
 ```
 
+Preview the complete environment-aware plan before changing anything:
+
+```bash
+buddy deploy --dry-run
+buddy deploy --dry-run --env staging
+buddy deploy --dry-run --site docs
+buddy deploy --dry-run --json
+```
+
+The preview uses the same environment transformation and ts-cloud site
+classification as a real deploy. It reports the ordered validation,
+infrastructure, build, package, release, runtime, gateway, DNS, TLS, and
+optional container operations. It exits before prerequisite setup, builds,
+packaging, hooks, provider calls, persistence, DNS, TLS, or service restarts.
+The JSON form emits a versioned `STACKS_DEPLOY_PREVIEW_JSON=` line for API and
+tool consumers.
+
 ## Deployment Prerequisites
 
 1. **AWS credentials configured**: `buddy configure:aws`
@@ -87,6 +104,7 @@ buddy deploy
 
 ```bash
 buddy deploy                  # deploy to cloud
+buddy deploy --dry-run        # preview without changing anything
 buddy cloud --diff            # preview infrastructure changes before deploying
 buddy cloud --ssh             # SSH into deployed server
 buddy cloud:remove            # tear down infrastructure

package/ai/skills/stacks-desktop/SKILL.md

@@ -23,8 +23,17 @@ Craft window. `buddy build:desktop` compiles a small Stacks launcher and places
 the launcher, pinned Craft runtime, manifest, provenance, and checksums in
 `storage/framework/desktop-dist`.
 
-Set `CRAFT_BIN` to an executable Craft binary in CI or when Craft is not checked
-out at `~/Code/Tools/craft`.
+Craft is normally installed through pantry and resolved from PATH. Set
+`CRAFT_BIN` to an explicit compiled native binary in CI or local Craft
+development. When testing local SDK source as well, set `CRAFT_SDK_SRC` to its
+`src/index.ts` entry. Set `STACKS_NO_NATIVE=1` only when a deliberately web-only
+dashboard process is required, such as headless browser QA. A missing
+`CRAFT_BIN` is an error and is never treated as a headless flag.
+
+Native development windows load the dashboard through its loopback HTTP
+origin. Keep pretty HTTPS domains for browser access. WKWebView does not assume
+that a developer's local certificate authority is trusted, and a failed TLS
+navigation otherwise appears as a blank native window.
 
 ## API
 

package/ai/skills/stacks-stx/SKILL.md

@@ -91,6 +91,30 @@ STX signals are callable. Read with `count()`, replace with
 `count.update(value => value + 1)`. Do not use Vue-style `.value` access in
 STX templates or `resources/functions`.
 
+### Client loop conditionals
+
+Attribute loops create a client-owned scope. Their item and index aliases may
+be used with either reactive attribute conditionals or STX block conditionals.
+The compiler promotes a block chain that reads those aliases into one reactive
+runtime chain:
+
+```html
+<template :for="(field, index) in fields()">
+  @if(field.editable)
+    <input x-model="drafts[field.key]">
+  @elseif(index === 0)
+    <span>First read-only field</span>
+  @else
+    <span>{{ field.value }}</span>
+  @endif
+</template>
+```
+
+Loop aliases are scoped to the owning element and inherited by nested client
+loops. A condition outside that element remains server-owned. Do not mix a
+server context value into a client loop chain. Serialize the value into client
+state when the browser must reevaluate it.
+
 ### Native form binding
 
 Use `x-model` for two-way form state instead of pairing `:value` with a
@@ -260,6 +284,7 @@ await addLayout('admin', { nav: true, footer: true })
 - **Server-to-client values are explicit** - a JSON-serializable top-level value exported by `<script server>` can be referenced by name in `<script client>`. STX serializes only referenced values and never overwrites a client-owned declaration
 - **`storage/framework/stx/`** — stx build cache and the generated route manifest. `config/ui.ts` sets stx's `stateDir` here, so nothing lands in the project root. Gitignored; safe to delete
 - **Reactivity is signal-based** - use callable `state()` and `derived()` signals, not Vue-style `ref()` or `.value`
+- **Client loop conditions** - `@if` chains that read `:for` or `@for` aliases compile into scoped runtime chains; aliases do not leak outside the loop element
 - **Component tag case is semantic** - `<Input v-model:value="query">` is a paired component, while lowercase `<input v-model="query">` is a native void element. Keep component tags PascalCase, including names that collide with native elements
 - **Structural DOM timing** - use `nextTick()` with `useRef()` after opening reactive markup
 - **Crosswind for styling** — use utility classes, not inline styles

package/app/Actions/Auth/LoginAction.ts

@@ -1,5 +1,5 @@
 import { Action } from '@stacksjs/actions'
-import { Auth, createTwoFactorChallenge, getTwoFactorState } from '@stacksjs/auth'
+import { Auth, authCookie, createTwoFactorChallenge, getTwoFactorState } from '@stacksjs/auth'
 import { User } from '@stacksjs/orm'
 import { response } from '@stacksjs/router'
 import { schema } from '@stacksjs/validation'
@@ -66,6 +66,15 @@ export default new Action({
     // The legacy `token` field is kept for backward compatibility
     // with clients that haven't been updated yet — it shadows
     // `access_token` and will be removed in a future major.
+    //
+    // The same token also goes out as an httpOnly cookie, matching
+    // SocialCallbackAction. Without it, how a browser ends up signed in
+    // depended on which way it signed in: OAuth left a cookie, email+password
+    // left only JSON, and a server-rendered page cannot read JSON — it posts a
+    // form, follows a redirect, and comes back carrying nothing but cookies.
+    // So the first authenticated document render had no way to identify the
+    // user (#2306). The body is unchanged, so an API client that ignores the
+    // cookie behaves exactly as before.
     return response.json({
       access_token: result.token,
       refresh_token: result.refreshToken,
@@ -77,6 +86,6 @@ export default new Action({
         email: user?.email,
         name: user?.name,
       },
-    })
+    }, { headers: { 'Set-Cookie': authCookie(result.token) } })
   },
 })

package/app/Actions/Auth/RefreshTokenAction.ts

@@ -1,5 +1,5 @@
 import { Action } from '@stacksjs/actions'
-import { refreshToken } from '@stacksjs/auth'
+import { authCookie, refreshToken } from '@stacksjs/auth'
 import { response } from '@stacksjs/router'
 import { schema } from '@stacksjs/validation'
 
@@ -25,12 +25,16 @@ export default new Action({
         refreshExpiresInDays: 30, // 30 day refresh token
       })
 
+      // Rotation invalidates the token the cookie was carrying, so a cookie
+      // left untouched here would go stale at the exact moment the session was
+      // meant to be extended: the browser keeps presenting a revoked token
+      // while the JSON body holds a live one it cannot read (#2306).
       return response.json({
         access_token: result.plainTextToken,
         refresh_token: result.refreshToken,
         token_type: 'Bearer',
         expires_in: result.expiresIn,
-      })
+      }, { headers: { 'Set-Cookie': authCookie(result.plainTextToken) } })
     }
     catch (error: any) {
       return response.unauthorized(error.message || 'Invalid or expired refresh token')

package/app/Actions/Auth/RegisterAction.ts

@@ -1,5 +1,5 @@
 import { Action } from '@stacksjs/actions'
-import { Auth, register } from '@stacksjs/auth'
+import { Auth, authCookie, register } from '@stacksjs/auth'
 import { dispatch } from '@stacksjs/events'
 import { response } from '@stacksjs/router'
 import { schema } from '@stacksjs/validation'
@@ -53,6 +53,10 @@ export default new Action({
       // were signed out an hour into their first session while every other
       // user refreshed normally (stacksjs/stacks#2212). The legacy `token`
       // alias stays for backward compatibility.
+      // Registering signs the account in, so it is a session-issuing path like
+      // the other three and carries the cookie for the same reason: the very
+      // next thing a server-rendered app does is redirect to an authenticated
+      // page (#2306).
       return response.json({
         access_token: result.token,
         refresh_token: result.refreshToken,
@@ -64,7 +68,7 @@ export default new Action({
           email: user?.email,
           name: user?.name,
         },
-      })
+      }, { headers: { 'Set-Cookie': authCookie(result.token) } })
     }
 
     return response.error('Registration failed')

package/app/Actions/Auth/VerifyTwoFactorLoginAction.ts

@@ -1,5 +1,5 @@
 import { Action } from '@stacksjs/actions'
-import { Auth, consumeTwoFactorChallenge, verifyTwoFactorLoginCode } from '@stacksjs/auth'
+import { Auth, authCookie, consumeTwoFactorChallenge, verifyTwoFactorLoginCode } from '@stacksjs/auth'
 import { response } from '@stacksjs/router'
 import { schema } from '@stacksjs/validation'
 
@@ -41,6 +41,10 @@ export default new Action({
 
     const user = result.user
 
+    // This is where a 2FA account's session actually begins — LoginAction
+    // deliberately mints nothing for these users until the code is verified —
+    // so the cookie belongs here too. Setting it only on LoginAction would
+    // have left every 2FA account exactly where it started (#2306).
     return response.json({
       access_token: result.token,
       refresh_token: result.refreshToken,
@@ -52,6 +56,6 @@ export default new Action({
         email: user?.email,
         name: user?.name,
       },
-    })
+    }, { headers: { 'Set-Cookie': authCookie(result.token) } })
   },
 })

package/app/Actions/Dashboard/Deployments/CreateDeployment.ts

@@ -5,7 +5,8 @@ import process from 'node:process'
 import { Deployment } from '@stacksjs/orm'
 import { response } from '@stacksjs/router'
 import { dashboardOperationalError, dashboardOperationalIssue } from '../dashboard-response'
-import { booleanValue, deploymentCommandArgs } from './deployment-input'
+import { booleanValue, deploymentCommandArgs, deploymentPreviewCommandArgs } from './deployment-input'
+import { runDeploymentPreview } from './deployment-preview'
 
 function gitValue(args: string[]): string {
   const result = Bun.spawnSync(['git', ...args], {
@@ -26,8 +27,35 @@ export default new Action({
 
   async handle(request: RequestInstance) {
     const dryRun = booleanValue(request.get('dryRun') || request.get('dry_run'))
+    if (dryRun) {
+      let previewArgs: string[]
+      try {
+        previewArgs = deploymentPreviewCommandArgs({
+          environment: request.get('environment') || request.get('env'),
+          domain: request.get('domain'),
+        })
+      }
+      catch (error) {
+        return response.json({
+          success: false,
+          message: error instanceof Error ? error.message : 'Deployment preview input is invalid.',
+        }, { status: 422 })
+      }
+
+      try {
+        return {
+          success: true,
+          plan: await runDeploymentPreview(previewArgs),
+          message: 'Deployment preview generated.',
+        }
+      }
+      catch (error) {
+        return dashboardOperationalError(error, 'Deployment preview could not be generated.', 'CreateDeployment.preview', 500)
+      }
+    }
+
     const confirmed = booleanValue(request.get('confirmed'))
-    if (!dryRun && !confirmed) {
+    if (!confirmed) {
       return response.json({
         success: false,
         confirmationRequired: true,
@@ -40,7 +68,6 @@ export default new Action({
       args = deploymentCommandArgs({
         environment: request.get('environment') || request.get('env'),
         domain: request.get('domain'),
-        dryRun,
       })
     }
     catch (error) {
@@ -50,22 +77,20 @@ export default new Action({
       }, { status: 422 })
     }
 
-    let deployment: Awaited<ReturnType<typeof Deployment.create>> | null = null
+    let deployment: Awaited<ReturnType<typeof Deployment.create>>
     const startedAt = Date.now()
-    if (!dryRun) {
-      try {
-        deployment = await Deployment.create({
-          commitHash: gitValue(['rev-parse', '--short=12', 'HEAD']),
-          commitMessage: gitValue(['log', '-1', '--pretty=%s']),
-          branch: gitValue(['branch', '--show-current']),
-          status: 'running',
-          environment: args[2],
-          author: gitValue(['log', '-1', '--pretty=%an <%ae>']),
-        })
-      }
-      catch (error) {
-        return dashboardOperationalError(error, 'Deployment record could not be created.', 'CreateDeployment.record', 500)
-      }
+    try {
+      deployment = await Deployment.create({
+        commitHash: gitValue(['rev-parse', '--short=12', 'HEAD']),
+        commitMessage: gitValue(['log', '-1', '--pretty=%s']),
+        branch: gitValue(['branch', '--show-current']),
+        status: 'running',
+        environment: args[2],
+        author: gitValue(['log', '-1', '--pretty=%an <%ae>']),
+      })
+    }
+    catch (error) {
+      return dashboardOperationalError(error, 'Deployment record could not be created.', 'CreateDeployment.record', 500)
     }
 
     let child: ReturnType<typeof Bun.spawn>
@@ -78,42 +103,37 @@ export default new Action({
       child.unref()
     }
     catch (error) {
-      if (deployment) {
-        try {
-          await deployment.update({
-            status: 'failed',
-            duration: 0,
-            errorLog: 'Deployment process could not be started.',
-          })
-        }
-        catch (updateError) {
-          dashboardOperationalIssue(updateError, 'Deployment failure status could not be recorded.', 'CreateDeployment.failureRecord')
-        }
+      try {
+        await deployment.update({
+          status: 'failed',
+          duration: 0,
+          errorLog: 'Deployment process could not be started.',
+        })
+      }
+      catch (updateError) {
+        dashboardOperationalIssue(updateError, 'Deployment failure status could not be recorded.', 'CreateDeployment.failureRecord')
       }
       return dashboardOperationalError(error, 'Deployment process could not be started.', 'CreateDeployment.process', 500)
     }
 
-    if (deployment) {
-      const record = deployment
-      void child.exited
-        .then(async (exitCode) => {
-          await record.update({
-            status: exitCode === 0 ? 'success' : 'failed',
-            duration: Math.max(0, Math.round((Date.now() - startedAt) / 1000)),
-            errorLog: exitCode === 0 ? '' : `buddy deploy exited with code ${exitCode}`,
-          })
-        })
-        .catch((error) => {
-          dashboardOperationalIssue(error, 'Deployment completion could not be recorded.', 'CreateDeployment.completionRecord')
+    void child.exited
+      .then(async (exitCode) => {
+        await deployment.update({
+          status: exitCode === 0 ? 'success' : 'failed',
+          duration: Math.max(0, Math.round((Date.now() - startedAt) / 1000)),
+          errorLog: exitCode === 0 ? '' : `buddy deploy exited with code ${exitCode}`,
         })
-    }
+      })
+      .catch((error) => {
+        dashboardOperationalIssue(error, 'Deployment completion could not be recorded.', 'CreateDeployment.completionRecord')
+      })
 
     return {
       success: true,
       pid: child.pid,
       command: ['./buddy', ...args],
-      deployment: deployment?.toJSON() || null,
-      message: dryRun ? 'Deployment preview started.' : 'Deployment started.',
+      deployment: deployment.toJSON(),
+      message: 'Deployment started.',
     }
   },
 })

package/app/Actions/Dashboard/Deployments/CreateDeploymentRollback.ts

@@ -0,0 +1,26 @@
+import type { RequestInstance } from '@stacksjs/types'
+import { Action } from '@stacksjs/actions'
+import { response } from '@stacksjs/router'
+import { trackOperatorOperation } from '../Operations/control-plane'
+import { stringValue } from '../Operations/recovery-input'
+import { deploymentRollbackInput, DeploymentRollbackError, executeDeploymentRollback } from './deployment-rollback'
+
+export default new Action({
+  name: 'CreateDeploymentRollback',
+  description: 'Executes a previously reviewed deployment rollback and records the operator action.',
+  method: 'POST',
+  apiResponse: true,
+  async handle(request: RequestInstance) {
+    const body = request.all() as Record<string, unknown>
+    try {
+      const input = deploymentRollbackInput(body)
+      const tracked = await trackOperatorOperation(request, 'dashboard.deployments.rollback', input, () => executeDeploymentRollback(input, stringValue(body.revision), stringValue(body.confirmation)))
+      return { success: true, ...tracked.result, operation: tracked.operation }
+    }
+    catch (error) {
+      if (error instanceof DeploymentRollbackError)
+        return response.json({ message: error.message }, 409)
+      throw error
+    }
+  },
+})

package/app/Actions/Dashboard/Deployments/PreviewDeployment.ts

@@ -0,0 +1,39 @@
+import type { RequestInstance } from '@stacksjs/types'
+import { Action } from '@stacksjs/actions'
+import { response } from '@stacksjs/router'
+import { dashboardOperationalError } from '../dashboard-response'
+import { deploymentPreviewCommandArgs } from './deployment-input'
+import { runDeploymentPreview } from './deployment-preview'
+
+export default new Action({
+  name: 'PreviewDeployment',
+  description: 'Builds a non-mutating deployment plan from the native Buddy deploy pipeline.',
+  method: 'POST',
+  apiResponse: true,
+
+  async handle(request: RequestInstance) {
+    let args: string[]
+    try {
+      args = deploymentPreviewCommandArgs({
+        environment: request.get('environment') || request.get('env'),
+        domain: request.get('domain'),
+      })
+    }
+    catch (error) {
+      return response.json({
+        success: false,
+        message: error instanceof Error ? error.message : 'Deployment preview input is invalid.',
+      }, { status: 422 })
+    }
+
+    try {
+      return {
+        success: true,
+        plan: await runDeploymentPreview(args),
+      }
+    }
+    catch (error) {
+      return dashboardOperationalError(error, 'Deployment preview could not be generated.', 'PreviewDeployment', 500)
+    }
+  },
+})

package/app/Actions/Dashboard/Deployments/PreviewDeploymentRollback.ts

@@ -0,0 +1,22 @@
+import type { RequestInstance } from '@stacksjs/types'
+import { Action } from '@stacksjs/actions'
+import { response } from '@stacksjs/router'
+import { dashboardOperationalError } from '../dashboard-response'
+import { deploymentRollbackInput, DeploymentRollbackError, previewDeploymentRollback } from './deployment-rollback'
+
+export default new Action({
+  name: 'PreviewDeploymentRollback',
+  description: 'Builds and validates a native deployment rollback plan without changing the active release.',
+  method: 'POST',
+  apiResponse: true,
+  async handle(request: RequestInstance) {
+    try {
+      return { success: true, plan: await previewDeploymentRollback(deploymentRollbackInput(request.all() as Record<string, unknown>)) }
+    }
+    catch (error) {
+      if (error instanceof DeploymentRollbackError)
+        return response.json({ message: error.message }, 409)
+      return dashboardOperationalError(error, 'Deployment rollback could not be previewed.', 'PreviewDeploymentRollback')
+    }
+  },
+})

package/app/Actions/Dashboard/Deployments/deployment-input.test.ts

@@ -3,6 +3,7 @@ import {
   averageRecordedDuration,
   booleanValue,
   deploymentCommandArgs,
+  deploymentPreviewCommandArgs,
   tailLines,
 } from './deployment-input'
 
@@ -19,7 +20,6 @@ describe('dashboard deployment inputs', () => {
     expect(deploymentCommandArgs({
       environment: 'staging',
       domain: 'app.example.com',
-      dryRun: true,
     })).toEqual([
       'deploy',
       '--env',
@@ -28,7 +28,6 @@ describe('dashboard deployment inputs', () => {
       '--yes',
       '--domain',
       'app.example.com',
-      '--dry-run',
     ])
   })
 
@@ -37,6 +36,17 @@ describe('dashboard deployment inputs', () => {
     expect(() => deploymentCommandArgs({ domain: 'not a domain' })).toThrow()
   })
 
+  it('builds a non-mutating machine-readable preview command', () => {
+    expect(deploymentPreviewCommandArgs({ environment: 'staging' })).toEqual([
+      'deploy',
+      '--env',
+      'staging',
+      '--dry-run',
+      '--json',
+      '--no-interaction',
+    ])
+  })
+
   it('aggregates only recorded durations', () => {
     expect(averageRecordedDuration([record(30), record('90'), record(null), record('bad')])).toBe(60)
     expect(averageRecordedDuration([record('bad')])).toBeNull()

package/app/Actions/Dashboard/Deployments/deployment-input.ts

@@ -1,7 +1,6 @@
 export interface DeploymentCommandInput {
   environment?: unknown
   domain?: unknown
-  dryRun?: unknown
 }
 
 export interface DeploymentRecordLike {
@@ -24,11 +23,14 @@ export function deploymentCommandArgs(input: DeploymentCommandInput): string[] {
       throw new Error('Domain must be a valid DNS name.')
     args.push('--domain', domain)
   }
-  if (booleanValue(input.dryRun))
-    args.push('--dry-run')
   return args
 }
 
+export function deploymentPreviewCommandArgs(input: DeploymentCommandInput): string[] {
+  const args = deploymentCommandArgs(input)
+  return [...args.filter(arg => arg !== '--no-interaction' && arg !== '--yes'), '--dry-run', '--json', '--no-interaction']
+}
+
 export function averageRecordedDuration(records: DeploymentRecordLike[]): number | null {
   const durations = records
     .map(record => record.get('duration'))