@stacksjs/defaults 0.75.74 → 0.75.76

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

@@ -1,6 +1,6 @@
 ---
 name: stacks-actions
-description: Use when working with Stacks server actions - creating actions in app/Actions/, auto-generated API actions from the useApi model trait, the 650 default framework actions (auth, dashboard, commerce, content, deployment, jobs), action request/response handling, or action registration. Covers @stacksjs/actions and storage/framework/defaults/app/Actions/.
+description: Use when working with Stacks server actions - creating actions in app/Actions/, auto-generated API actions from the useApi model trait, the 657 default framework actions (auth, dashboard, commerce, content, deployment, jobs), action request/response handling, or action registration. Covers @stacksjs/actions and storage/framework/defaults/app/Actions/.
 license: MIT
 compatibility: Bun >= 1.3.0, TypeScript
 allowed-tools: Read Edit Write Bash Grep Glob

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

@@ -1,6 +1,6 @@
 ---
 name: stacks-dashboard
-description: Use when building or customizing the Stacks admin dashboard, including dashboard pages, model management views, analytics widgets, commerce dashboards, content management, settings panels, deployment monitoring, job/queue management, or the 407 built-in dashboard components. Covers the dashboard system at storage/framework/defaults/.
+description: Use when building or customizing the Stacks admin dashboard, including dashboard pages, model management views, analytics widgets, commerce dashboards, content management, settings panels, deployment monitoring, job/queue management, or the 408 built-in dashboard components. Covers the dashboard system at storage/framework/defaults/.
 license: MIT
 compatibility: Bun >= 1.3.0, TypeScript
 allowed-tools: Read Edit Write Bash Grep Glob
@@ -8,7 +8,7 @@ allowed-tools: Read Edit Write Bash Grep Glob
 
 # Stacks Dashboard
 
-The Stacks admin dashboard provides a full-featured admin panel with 100+ route views, 407 components, and a multi-section layout.
+The Stacks admin dashboard provides a full-featured admin panel with 100+ route views, 408 components, and a multi-section layout.
 
 ## Key Paths
 - Dashboard components: `storage/framework/defaults/resources/components/Dashboard/`
@@ -128,11 +128,10 @@ already followed and a missing derivative is regenerated by reprocessing.
 
 ### Remote commands (stacksjs/stacks#960)
 
-Running a configured operation on a configured host over SSH. Deliberately NOT
-a terminal: the request names a host KEY and a command KEY, both from
-`config/remote.ts`, so there is nothing to escape and no shell to reach. An
-interactive session is tracked separately - `Bun.spawn` has no PTY, and
-`ssh -tt` gives a remote one but cannot propagate a window resize.
+Running a configured operation on a configured host over SSH: the request
+names a host KEY and a command KEY, both from `config/remote.ts`, so there is
+nothing to escape and no shell to reach. The interactive terminal beside it is
+covered below.
 
 Four things make it safe to expose, and each is a rule to keep:
 
@@ -156,6 +155,42 @@ command that hung and the one whose process died with the box. The audit sink
 writes to the application log rather than the dashboard's own database, which is
 the thing an operator with dashboard access could edit.
 
+### Remote terminals (stacksjs/stacks#960)
+
+`/remote` in the dashboard also opens an interactive shell on a host that sets
+`terminal: true`. Every command-runner rule above holds, plus:
+
+- **A host opts in, and a gate decides.** `terminal: true` on the host, and the
+  `open-remote-terminal` gate (receives the host key). No gate, no session.
+- **A session belongs to the user who opened it.** 128-bit id; another user
+  naming it gets the same 404 as a missing id.
+- **It does not outlive its purpose.** 15 minutes without input, 2 hours in all,
+  30 seconds after the last viewer leaves: the remote shell is killed, never
+  left running. At most 4 per user.
+- **What is typed is audited line by line** in the application log, so hosts
+  should take keys and passwordless sudo, not typed passwords.
+
+Transport: a local PTY (`Bun.spawn({ terminal })`, which Bun now has) running
+`ssh -tt` with the pinned host key, so a browser resize reaches the remote side.
+Output reaches the browser as server-sent events, base64 and sequence-numbered
+for replay on reconnect; input and resize are small POSTs that each pass auth,
+CSRF and the session-owner check. Sessions live in the server process.
+
+In the browser it is `<stacks-remote-terminal host="...">` (xterm.js), from
+`functions/remote-terminal-element.ts`. Two rules that module follows:
+
+- **Nothing browser-only at module top level.** `defaults/functions` is also
+  auto-imported on the SERVER; a top-level `class extends HTMLElement` threw
+  there and took every function in the barrel down. xterm and the class load
+  inside `registerRemoteTerminal()`.
+- **Survive being moved.** stx's `:if` detaches and re-inserts the SAME nodes, so
+  the element acts on a removal only if it is still detached a tick later, and
+  starts a fresh session whenever it is attached again.
+
+`remote-terminal.test.ts` runs a real session through a throwaway user-level
+`sshd` on a loopback port when one is installed (macOS and the CI image both
+have one), including a host whose key does not match the pinned one.
+
 **There is no ffmpeg.** #2578 asked whether video was in scope given the
 external binary, its licensing and its provisioning; `@stacksjs/video` is built
 on `ts-videos`, which encodes itself, so that question was already answered.

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

@@ -10,6 +10,17 @@ allowed-tools: Read Edit Write Bash Grep Glob
 
 Full Stripe integration via the Payment facade. Uses Stripe API version `2026-01-28.clover`. The Stripe SDK is initialized from `services.stripe.secretKey` (sourced from `config/payment.ts`).
 
+## Payment Drivers (provider-neutral)
+
+`paymentDriver()` (also `Payment.driver()`) returns the driver `config.payment.driver` selects: `stripe` (default) or `adyen`, or one added with `registerPaymentDriver(name, factory)`. Source: `storage/framework/core/payments/src/driver/`.
+
+- Money is `{ amount, currency }` in minor units; `assertMoney` refuses floats before a request leaves.
+- Methods: `customer`, `charge(payer, money, paymentMethodId)`, `createPayment` (browser completes: `clientConfirmation` is a Stripe client secret or an Adyen session), `refund`, `checkout(payer, { mode, lines, successUrl, ... })`, `paymentMethods`, `removePaymentMethod`, `subscribe`, `cancelSubscription`, `subscriptions`, `verifyWebhook({ payload, headers })` -> `PaymentEvent[]`, `acknowledgeWebhook()`.
+- Unsupported operations throw `PaymentUnsupportedError` (driver + operation). Adyen has no catalog, subscriptions, invoices, coupons or portal.
+- Adyen: Checkout API v72, `X-API-Key`; shopper reference `user-<id>` (no PII); full refunds go to `/reversals`; webhooks verified per item with HMAC-SHA256 over 8 colon-joined fields under the hex key, acknowledged with 202.
+- The Stripe driver delegates to the existing billable modules, so idempotency keys and `stripe_id` handling are unchanged.
+- Everything below this section is Stripe's own API and returns Stripe objects.
+
 ## Key Paths
 - Core package: `storage/framework/core/payments/src/`
 - Payment facade: `storage/framework/core/payments/src/payment.ts`

package/app/Actions/Dashboard/DashboardHomeAction.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, it } from 'bun:test'
-import { orderActivityStatus, serializeHealthCheck, summarizeHttpRequests } from './DashboardHomeAction'
+import { homeStats, orderActivityStatus, serializeHealthCheck, settleEach, summarizeHttpRequests } from './DashboardHomeAction'
 
 describe('dashboard HTTP metrics', () => {
   it('summarizes captured requests without fake values', () => {
@@ -39,3 +39,35 @@ describe('dashboard HTTP metrics', () => {
     expect(orderActivityStatus('preparing')).toBe('success')
   })
 })
+
+describe('dashboard home queries', () => {
+  it('turns a query that throws before returning a promise into a rejected entry', async () => {
+    // What `Product.count()` does with commerce off: the model is not loaded,
+    // `count` is undefined, and calling it throws synchronously. Evaluated as
+    // `Promise.allSettled([Product.count(), ...])` that escaped allSettled and
+    // returned a 500 for the whole page.
+    const unloaded = {} as { count: () => Promise<number> }
+    const [users, products] = await settleEach([async () => 3, () => unloaded.count()] as const)
+
+    expect(users).toEqual({ status: 'fulfilled', value: 3 })
+    expect(products.status).toBe('rejected')
+  })
+
+  it('shows commerce numbers only when commerce is on', () => {
+    const users = { status: 'fulfilled', value: 12 } as const
+    expect(homeStats({ users }, false)).toEqual([{ label: 'Total Users', value: '12', color: 'blue' }])
+
+    const on = homeStats({
+      users,
+      products: { status: 'fulfilled', value: 4 },
+      revenue: { status: 'fulfilled', value: 1250 },
+      orders: { status: 'rejected', reason: new Error('down') },
+    }, true)
+    expect(on.map(stat => [stat.label, stat.value])).toEqual([
+      ['Total Users', '12'],
+      ['Products', '4'],
+      ['Revenue', '$1,250'],
+      ['Orders', 'Unavailable'],
+    ])
+  })
+})

package/app/Actions/Dashboard/DashboardHomeAction.ts

@@ -1,5 +1,6 @@
 import { Action } from '@stacksjs/actions/runtime'
-import { Order, Post, Product, Request, User } from '@stacksjs/orm'
+import { feature } from '@stacksjs/config'
+import { Order, Product, Request, User } from '@stacksjs/orm'
 import { checkApplicationHealth, type ApplicationHealthCheck } from '@stacksjs/router'
 import { formatRelative, safeGet } from '../../../resources/functions/dashboard/data'
 import { dashboardOperationalIssue } from './dashboard-response'
@@ -53,43 +54,71 @@ function issue(source: string, result: PromiseSettledResult<unknown>) {
     : null
 }
 
+/**
+ * Run each query inside the promise, so one that throws before returning one -
+ * `Product.count()` when commerce is off, where the model is not loaded and
+ * `count` is undefined - is a rejected entry rather than a 500 for the page.
+ * `Promise.allSettled([Product.count(), ...])` evaluated every call first.
+ */
+export function settleEach<T extends readonly (() => unknown)[]>(queries: T): Promise<{ [K in keyof T]: PromiseSettledResult<Awaited<ReturnType<T[K]>>> }> {
+  return Promise.allSettled(queries.map(query => Promise.resolve().then(query))) as never
+}
+
+type Settled = PromiseSettledResult<unknown>
+
+/**
+ * The headline numbers. Products, revenue and orders are commerce's, so with
+ * commerce off they are left out rather than shown as "Unavailable" - there is
+ * nothing to be unavailable.
+ */
+export function homeStats(
+  results: { users: Settled, products?: Settled, revenue?: Settled, orders?: Settled },
+  commerce: boolean,
+): Array<{ label: string, value: string, color: string }> {
+  const value = (result: Settled | undefined, format: (raw: unknown) => string) =>
+    result?.status === 'fulfilled' ? format(result.value) : 'Unavailable'
+
+  const stats = [{ label: 'Total Users', value: value(results.users, String), color: 'blue' }]
+  if (commerce) {
+    stats.push(
+      { label: 'Products', value: value(results.products, String), color: 'green' },
+      { label: 'Revenue', value: value(results.revenue, raw => `$${Number(raw || 0).toLocaleString()}`), color: 'orange' },
+      { label: 'Orders', value: value(results.orders, String), color: 'red' },
+    )
+  }
+  return stats
+}
+
 export default new Action({
   name: 'DashboardHomeAction',
   description: 'Returns home dashboard data including stats, quick links, services, and recent activity.',
   method: 'GET',
 
   async handle() {
-    const modelResults = await Promise.allSettled([
-      User.count(),
-      Product.count(),
-      Order.count(),
-      Post.count(),
-      Order.sum('totalAmount'),
-      Order.orderBy('created_at', 'desc').limit(5).get(),
-      User.orderBy('created_at', 'desc').limit(5).get(),
-      Request.count(),
-      Request.orderBy('created_at', 'desc').limit(1000).get(),
-    ])
-    const healthResult = await Promise.allSettled([checkApplicationHealth()])
-
+    const commerce = feature('commerce')
+    const none = async () => null
     const [
       userCount,
       productCount,
       orderCount,
-      postCount,
       totalRevenue,
       recentOrders,
       recentUsers,
       requestCount,
       recentRequests,
-    ] = modelResults
+    ] = await settleEach([
+      () => User.count(),
+      commerce ? () => Product.count() : none,
+      commerce ? () => Order.count() : none,
+      commerce ? () => Order.sum('totalAmount') : none,
+      commerce ? () => Order.orderBy('created_at', 'desc').limit(5).get() : async () => [],
+      () => User.orderBy('created_at', 'desc').limit(5).get(),
+      () => Request.count(),
+      () => Request.orderBy('created_at', 'desc').limit(1000).get(),
+    ] as const)
+    const healthResult = await Promise.allSettled([checkApplicationHealth()])
 
-    const stats = [
-      { label: 'Total Users', value: userCount.status === 'fulfilled' ? String(userCount.value) : 'Unavailable', color: 'blue' },
-      { label: 'Products', value: productCount.status === 'fulfilled' ? String(productCount.value) : 'Unavailable', color: 'green' },
-      { label: 'Revenue', value: totalRevenue.status === 'fulfilled' ? `$${Number(totalRevenue.value || 0).toLocaleString()}` : 'Unavailable', color: 'orange' },
-      { label: 'Orders', value: orderCount.status === 'fulfilled' ? String(orderCount.value) : 'Unavailable', color: 'red' },
-    ]
+    const stats = homeStats({ users: userCount, products: productCount, revenue: totalRevenue, orders: orderCount }, commerce)
 
     const httpMetrics = requestCount.status === 'fulfilled' && recentRequests.status === 'fulfilled'
       ? summarizeHttpRequests(requestCount.value, recentRequests.value.map(request => ({
@@ -140,9 +169,18 @@ export default new Action({
         status: activity.status,
       }))
 
-    const sources = ['Users', 'Products', 'Orders', 'Posts', 'Revenue', 'Recent orders', 'Recent users', 'Request count', 'Recent requests']
-    const issues = modelResults
-      .map((result, index) => issue(sources[index] ?? 'Dashboard', result))
+    const sources: Array<[string, PromiseSettledResult<unknown>]> = [
+      ['Users', userCount],
+      ['Products', productCount],
+      ['Orders', orderCount],
+      ['Revenue', totalRevenue],
+      ['Recent orders', recentOrders],
+      ['Recent users', recentUsers],
+      ['Request count', requestCount],
+      ['Recent requests', recentRequests],
+    ]
+    const issues = sources
+      .map(([source, result]) => issue(source, result))
       .filter((entry): entry is { source: string, message: string } => entry !== null)
     if (health.status === 'rejected') {
       issues.push({

package/app/Actions/Dashboard/Remote/RemoteCommandIndexAction.ts

@@ -17,6 +17,9 @@ export default new Action({
         host: host.host,
         user: host.user,
         port: host.port ?? 22,
+        // Whether the host allows terminal sessions at all. Whether this
+        // user may open one is the `open-remote-terminal` gate's call.
+        terminal: host.terminal === true,
       })),
       commands: commands.map(command => ({
         key: command.key,

package/app/Actions/Dashboard/Remote/RemoteTerminalCloseAction.ts

@@ -0,0 +1,25 @@
+import type { UserModel } from '@stacksjs/orm'
+import type { RequestInstance } from '@stacksjs/types'
+import { Action } from '@stacksjs/actions/runtime'
+import { response } from '@stacksjs/router'
+import { RemoteCommandError } from './remote-commands'
+import { terminalSessions } from './terminal-sessions'
+
+/** End a terminal session and the remote shell with it (stacksjs/stacks#960). */
+export default new Action({
+  name: 'RemoteTerminalCloseAction',
+  description: 'Closes a terminal session.',
+  method: 'DELETE',
+  async handle(request: RequestInstance) {
+    try {
+      const user = (await request.user() ?? null) as UserModel | null
+      await terminalSessions.close(request.getParam('id'), user)
+      return response.json({ ok: true })
+    }
+    catch (error) {
+      if (error instanceof RemoteCommandError)
+        return response.json({ message: error.message }, error.status)
+      throw error
+    }
+  },
+})

package/app/Actions/Dashboard/Remote/RemoteTerminalInputAction.ts

@@ -0,0 +1,25 @@
+import type { UserModel } from '@stacksjs/orm'
+import type { RequestInstance } from '@stacksjs/types'
+import { Action } from '@stacksjs/actions/runtime'
+import { response } from '@stacksjs/router'
+import { RemoteCommandError } from './remote-commands'
+import { terminalSessions } from './terminal-sessions'
+
+/** Type into a terminal session (stacksjs/stacks#960). */
+export default new Action({
+  name: 'RemoteTerminalInputAction',
+  description: 'Sends input to a terminal session.',
+  method: 'POST',
+  async handle(request: RequestInstance) {
+    try {
+      const user = (await request.user() ?? null) as UserModel | null
+      await terminalSessions.input(request.getParam('id'), user, request.get('data'))
+      return response.json({ ok: true })
+    }
+    catch (error) {
+      if (error instanceof RemoteCommandError)
+        return response.json({ message: error.message }, error.status)
+      throw error
+    }
+  },
+})

package/app/Actions/Dashboard/Remote/RemoteTerminalOpenAction.ts

@@ -0,0 +1,39 @@
+import type { UserModel } from '@stacksjs/orm'
+import type { RequestInstance } from '@stacksjs/types'
+import { Action } from '@stacksjs/actions/runtime'
+import { hosts } from '~/config/remote'
+import { response } from '@stacksjs/router'
+import { RemoteCommandError } from './remote-commands'
+import { terminalAuthorizer, terminalSessions } from './terminal-sessions'
+
+/**
+ * Open a terminal session on a configured host (stacksjs/stacks#960).
+ *
+ * Routed without `guard()`, like the command runner: that helper drops auth
+ * entirely when `APP_ENV` is local or test, which here would be an
+ * unauthenticated shell. See `routes/dashboard-api.ts`.
+ */
+export default new Action({
+  name: 'RemoteTerminalOpenAction',
+  description: 'Opens an interactive terminal session on a configured host.',
+  method: 'POST',
+  async handle(request: RequestInstance) {
+    try {
+      const user = (await request.user() ?? null) as UserModel | null
+      const session = await terminalSessions.open({
+        user,
+        hosts,
+        hostKey: request.get('host'),
+        authorizer: terminalAuthorizer(),
+        cols: request.get('cols'),
+        rows: request.get('rows'),
+      })
+      return response.json(session, 201)
+    }
+    catch (error) {
+      if (error instanceof RemoteCommandError)
+        return response.json({ message: error.message }, error.status)
+      throw error
+    }
+  },
+})

package/app/Actions/Dashboard/Remote/RemoteTerminalResizeAction.ts

@@ -0,0 +1,25 @@
+import type { UserModel } from '@stacksjs/orm'
+import type { RequestInstance } from '@stacksjs/types'
+import { Action } from '@stacksjs/actions/runtime'
+import { response } from '@stacksjs/router'
+import { RemoteCommandError } from './remote-commands'
+import { terminalSessions } from './terminal-sessions'
+
+/** Resize a terminal session's window (stacksjs/stacks#960). */
+export default new Action({
+  name: 'RemoteTerminalResizeAction',
+  description: 'Resizes a terminal session.',
+  method: 'POST',
+  async handle(request: RequestInstance) {
+    try {
+      const user = (await request.user() ?? null) as UserModel | null
+      terminalSessions.resize(request.getParam('id'), user, request.get('cols'), request.get('rows'))
+      return response.json({ ok: true })
+    }
+    catch (error) {
+      if (error instanceof RemoteCommandError)
+        return response.json({ message: error.message }, error.status)
+      throw error
+    }
+  },
+})

package/app/Actions/Dashboard/Remote/RemoteTerminalStreamAction.ts

@@ -0,0 +1,36 @@
+import type { UserModel } from '@stacksjs/orm'
+import type { RequestInstance } from '@stacksjs/types'
+import { Action } from '@stacksjs/actions/runtime'
+import { response, stream } from '@stacksjs/router'
+import { RemoteCommandError } from './remote-commands'
+import { terminalEventStream, terminalSessions } from './terminal-sessions'
+
+/**
+ * A terminal session's output as server-sent events (stacksjs/stacks#960).
+ *
+ * `after` (or `Last-Event-ID`) resumes after the last sequence number the
+ * viewer saw, from the session's replay buffer.
+ */
+export default new Action({
+  name: 'RemoteTerminalStreamAction',
+  description: 'Streams a terminal session\'s output.',
+  method: 'GET',
+  async handle(request: RequestInstance) {
+    try {
+      const user = (await request.user() ?? null) as UserModel | null
+      const resumeFrom = request.get('after') ?? request.headers.get('last-event-id') ?? 0
+      const after = Number(resumeFrom)
+      const events = terminalSessions.watch(request.getParam('id'), user, Number.isInteger(after) && after > 0 ? after : 0)
+      return stream(terminalEventStream(events), {
+        type: 'sse',
+        // Proxies that buffer would hold keystroke echoes until a buffer fills.
+        headers: { 'X-Accel-Buffering': 'no' },
+      })
+    }
+    catch (error) {
+      if (error instanceof RemoteCommandError)
+        return response.json({ message: error.message }, error.status)
+      throw error
+    }
+  },
+})

package/app/Actions/Dashboard/Remote/remote-commands.ts

@@ -62,6 +62,15 @@ export interface RemoteHost {
    * the host can declare its fingerprint at the same time.
    */
   knownHosts: string
+  /**
+   * Allow interactive terminal sessions into this host from the dashboard.
+   *
+   * Off unless set. A host declared for named commands is not thereby a host
+   * anyone may open a shell on: a terminal is every command at once, so it is
+   * a separate decision, and authorized by its own gate,
+   * `open-remote-terminal`.
+   */
+  terminal?: boolean
 }
 
 /** An operation that may be run, as config declares it. */
@@ -144,6 +153,26 @@ const DEFAULT_MAX_OUTPUT = 64 * 1024
  *   interpreted by a local shell.
  */
 export function sshArgv(host: RemoteHost, command: RemoteCommand, knownHostsPath: string): string[] {
+  return [...sshConnectionArgv(host, knownHostsPath), '--', ...command.argv]
+}
+
+/**
+ * The `ssh` argv for an interactive session: the same pinned-key options and
+ * no remote command, so the host starts the user's login shell.
+ *
+ * `-tt` forces a remote PTY. ssh would allocate one anyway when its own stdin
+ * is a terminal, which it is - the session runs under a local PTY so a window
+ * resize reaches the remote side - but forcing it keeps the remote behaviour
+ * independent of how the local side happens to be wired.
+ */
+export function sshTerminalArgv(host: RemoteHost, knownHostsPath: string): string[] {
+  const argv = sshConnectionArgv(host, knownHostsPath)
+  // Before the destination: options after it would be read as the command.
+  argv.splice(argv.length - 1, 0, '-tt', '-o', 'ServerAliveInterval=30')
+  return argv
+}
+
+function sshConnectionArgv(host: RemoteHost, knownHostsPath: string): string[] {
   const argv = [
     'ssh',
     '-o', 'StrictHostKeyChecking=yes',
@@ -157,7 +186,7 @@ export function sshArgv(host: RemoteHost, command: RemoteCommand, knownHostsPath
   if (host.identityFile)
     argv.push('-i', host.identityFile, '-o', 'IdentitiesOnly=yes')
 
-  argv.push(`${host.user}@${host.host}`, '--', ...command.argv)
+  argv.push(`${host.user}@${host.host}`)
   return argv
 }
 

package/app/Actions/Dashboard/Remote/remote-routes.test.ts

@@ -27,10 +27,10 @@ const remoteRoutes = routes
   .filter(line => line.includes('Actions/Dashboard/Remote/'))
 
 describe('remote-command routes', () => {
-  it('registers both endpoints', () => {
-    expect(remoteRoutes).toHaveLength(2)
-    expect(remoteRoutes.join('\n')).toContain('RemoteCommandIndexAction')
-    expect(remoteRoutes.join('\n')).toContain('RemoteCommandRunAction')
+  it('registers the command and terminal endpoints', () => {
+    expect(remoteRoutes).toHaveLength(7)
+    for (const action of ['RemoteCommandIndexAction', 'RemoteCommandRunAction', 'RemoteTerminalOpenAction', 'RemoteTerminalStreamAction', 'RemoteTerminalInputAction', 'RemoteTerminalResizeAction', 'RemoteTerminalCloseAction'])
+      expect(remoteRoutes.join('\n')).toContain(action)
   })
 
   it('never uses the guard that drops auth in local environments', () => {