@stacksjs/defaults 0.75.87 → 0.75.89

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

@@ -20,6 +20,7 @@ environment overrides it. With neither set, the provider is `aws`.
 | `'aws'` (default) | AWS | Generates infrastructure, creates or updates a CloudFormation stack |
 | `'hetzner'` | Hetzner Cloud | Provisions the server through the Hetzner API, then deploys over SSH |
 | `'ssh'` | A host you already own | Adopts and bootstraps the host over SSH, then deploys to it |
+| `'fly'` | Fly.io Machines | Builds `storage/framework/Dockerfile`, pushes it to `registry.fly.io`, rolls the Machines under their leases |
 
 Read the repo's own `config/cloud.ts` before assuming a target. This repo uses `'hetzner'`.
 
@@ -68,6 +69,22 @@ a versioned `STACKS_DEPLOY_PREVIEW_JSON=` line for API and tool consumers.
 2. A key that reaches it, and passwordless sudo when the user is not root
 3. `buddy server:doctor` clean
 
+**Fly.io** (`provider: 'fly'`)
+
+1. `FLY_API_TOKEN` (an org token lets the first deploy create the app)
+2. Docker where the deploy runs, for the image build and push
+3. `fly.*` in `config/cloud.ts`: `regions`, `count`, `vm`, `volume`, `hostnames`. Every `.env.<env>`
+   value becomes a Fly secret. A deploy never destroys Machines; extras are reported.
+
+## Preview deployments (Hetzner and `ssh`)
+
+`buddy deploy:preview pr-123` deploys the app as its own tenant (slug `<slug>-pr-123`, attached to
+the app's box) at `pr-123.<cloud.previews.domain | PREVIEW_DOMAIN>`; `deploy:preview:remove pr-123`
+removes its units, gateway route, cert units, files and DNS records by exact name. Secrets come
+from `.env.preview` only (the deploy refuses without it), and a relative SQLite path gets its own
+data dir. `--base staging` uses the staging box. New apps ship `.github/workflows/preview.yml`
+(same-repo PRs only; needs `DEPLOY_SSH_KEY`, `DOTENV_PRIVATE_KEY_PREVIEW`, `vars.PREVIEW_DOMAIN`).
+
 ## Deployment Flow
 
 **AWS**

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

@@ -12,13 +12,14 @@ Full Stripe integration via the Payment facade. Uses Stripe API version `2026-01
 
 ## Payment Drivers (provider-neutral)
 
-`paymentDriver()` (also `Payment.driver()`) returns the driver `config.payment.driver` selects: `stripe` (default), `adyen` or `paddle`, or one added with `registerPaymentDriver(name, factory)`. Source: `storage/framework/core/payments/src/driver/`.
+`paymentDriver()` (also `Payment.driver()`) returns the driver `config.payment.driver` selects: `stripe` (default), `adyen`, `paddle` or `lemonsqueezy`, 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()`.
 - `checkout` copies `reference` and `metadata` onto the payment / subscription / setup intent it creates (Stripe: `payment_intent_data`, `subscription_data`, `setup_intent_data`), so their webhooks can be attributed. `allowPromotionCodes` and `automaticTax` are Stripe only; Adyen refuses them.
 - Unsupported operations throw `PaymentUnsupportedError` (driver + operation). Adyen has no catalog, subscriptions, invoices, coupons or portal; Paddle has no server-side charge, server-side subscribe, setup checkout, promotion-code or trial option on a checkout, or separate cancel URL.
 - Paddle (`driver: 'paddle'`, Billing API v1, merchant of record): customers found or created by email; every payment is a transaction completed in Paddle.js (`clientConfirmation: { provider: 'paddle', transactionId, successUrl? }`), so `charge` and `subscribe` are unsupported and subscriptions start at `checkout` in `subscription` mode with catalog prices; refunds are adjustments Paddle reviews (`pending`, settled by `adjustment.updated`; a refund's event id is the adjustment's, so a created-and-updated approval counts once); webhooks `Paddle-Signature` = HMAC-SHA256 hex of `<ts>:<raw body>` under the secret, 5 s tolerance. Paddle has no hosted page: `GET /payments/checkout` (mounted while the driver is `paddle`) is the default payment link page, reading `stacks_success_url` from the transaction for Paddle.js. Env: `PADDLE_API_KEY`, `PADDLE_ENVIRONMENT`, `PADDLE_CLIENT_TOKEN`, `PADDLE_WEBHOOK_SECRET`, `PADDLE_TAX_CATEGORY`.
+- Lemon Squeezy (`driver: 'lemonsqueezy'`, API v1, merchant of record): customers found or created by email in the store; `checkout` sells exactly one variant (a `price` line is a variant id; a line priced here sells as `LEMONSQUEEZY_VARIANT_ID` at a custom price in the store's currency); `charge`, `createPayment`, `subscribe` and payment methods are unsupported; refunds are immediate against the order; `cancelSubscription` needs `{ atPeriodEnd: true }`; webhooks `X-Signature` = HMAC-SHA256 hex of the raw body, event id = digest of the bytes, `order_refunded` carries `refundedTotal` (the order's running total), which commerce applies as a difference. Env: `LEMONSQUEEZY_API_KEY`, `LEMONSQUEEZY_STORE_ID`, `LEMONSQUEEZY_WEBHOOK_SECRET`, `LEMONSQUEEZY_VARIANT_ID`, `LEMONSQUEEZY_TEST_MODE`.
 - 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.
 - `PaymentEvent` carries `provider` and `id` (together, the retry key), `reference` (the payment; for a refund, the payment refunded), `amount` (for a refund, that one refund - Stripe's cumulative `amount_refunded` is turned into a delta from `previous_attributes`) and `reason`. Adyen's id is `eventCode:pspReference:success`, since Adyen may resend a pair with the outcome changed.
 - The Stripe driver delegates to the existing billable modules, so idempotency keys and `stripe_id` handling are unchanged.

package/app/Actions/Dashboard/Email/captured-mail.ts

@@ -1,7 +1,6 @@
 import { readdir, readFile, stat } from 'node:fs/promises'
 import { basename, join } from 'node:path'
 import { log as logDriver } from '@stacksjs/email'
-import { logsPath } from '@stacksjs/path'
 
 const { LogEmailDriver } = logDriver
 
@@ -36,8 +35,9 @@ export interface CapturedMailListing {
   problems: CapturedMailProblem[]
 }
 
+// The driver's own answer, so the page reads exactly where captures are written.
 function capturedMailDirectory(): string {
-  return process.env.LOG_MAIL_DIR || logsPath('mail')
+  return LogEmailDriver.directory()
 }
 
 function formatAddress(value: unknown): string {

package/ide/vscode/package.json

@@ -2,7 +2,7 @@
   "publisher": "Stacks",
   "name": "vscode-stacks",
   "displayName": "Stacks",
-  "version": "0.75.87",
+  "version": "0.75.89",
   "description": "Stacks, built into VS Code: stx templates, pickier linting and formatting, encrypted env files, the dev server preview and every buddy command. No other extensions required.",
   "license": "MIT",
   "funding": "https://github.com/sponsors/chrisbbreuer",

package/package.json

@@ -2,7 +2,7 @@
   "name": "@stacksjs/defaults",
   "type": "module",
   "sideEffects": false,
-  "version": "0.75.87",
+  "version": "0.75.89",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/stacksjs/stacks.git",
@@ -55,8 +55,8 @@
   "dependencies": {
     "@iconify-json/f7": "^1.2.2",
     "@iconify-json/hugeicons": "^1.2.35",
-    "@stacksjs/mobile": "^0.75.87",
-    "@stacksjs/sanitizer": "^0.2.384",
+    "@stacksjs/mobile": "^0.75.89",
+    "@stacksjs/sanitizer": "^0.2.395",
     "@xterm/addon-fit": "^0.11.0",
     "@xterm/xterm": "^6.0.0",
     "ts-qr-codes": "^0.1.8"

package/routes/payments.ts

@@ -6,9 +6,10 @@ import { route } from '@stacksjs/router'
  *
  * Point the provider at `POST /webhooks/payments`: Stripe's endpoint with its
  * signing secret in `STRIPE_WEBHOOK_SECRET`, or Adyen's standard webhook with
- * its HMAC key in `ADYEN_HMAC_KEY`, or a Paddle notification destination with
- * its secret key in `PADDLE_WEBHOOK_SECRET`, whichever `config.payment.driver`
- * names.
+ * its HMAC key in `ADYEN_HMAC_KEY`, a Paddle notification destination with its
+ * secret key in `PADDLE_WEBHOOK_SECRET`, or a Lemon Squeezy store webhook with
+ * its signing secret in `LEMONSQUEEZY_WEBHOOK_SECRET`, whichever
+ * `config.payment.driver` names.
  * Payments and refunds then reach their orders without app code; orders used
  * to sit at PENDING whenever the webhook was the only news of a payment.
  *

package/vcs/github/workflows/README.md

@@ -9,7 +9,11 @@ This folder contains the following GitHub Actions:
   - runs on `ubuntu-latest`
 - [Release][Release] — on a `v*` tag, generates the changelog and creates the GitHub release
 - [Labeler][Labeler] — labels pull requests from `.github/labeler.yml`
+- [Deploy][Deploy] — deploys each green push to `main` with `buddy deploy`
+- [Preview][Preview] — deploys every pull request to `pr-<number>.<preview domain>` with `buddy deploy:preview`, comments the URL, and removes it when the pull request closes
 
 [CI]: ./ci.yml
 [Release]: ./release.yml
 [Labeler]: ./labeler.yml
+[Deploy]: ./deploy.yml
+[Preview]: ./preview.yml

package/vcs/github/workflows/preview.yml

@@ -0,0 +1,141 @@
+name: Preview
+
+# A preview deployment for every pull request (stacksjs/stacks#735).
+#
+# Each pull request is deployed as its own tenant on the app's box, at
+# pr-<number>.<preview domain>, with its own database and its own secrets
+# from .env.preview, and removed when the pull request closes. The URL is
+# kept current in one comment on the pull request.
+#
+# Set up once:
+#   - PREVIEW_DOMAIN as a repository variable (or cloud.previews.domain in
+#     config/cloud.ts), with its DNS at a provider whose keys are below
+#   - .env.preview, committed encrypted, holding credentials that are NOT
+#     production's: its own database, mail and API keys
+#   - DOTENV_PRIVATE_KEY_PREVIEW and DEPLOY_SSH_KEY as secrets
+on:
+  pull_request:
+    types: [opened, synchronize, reopened, closed]
+
+# One run per pull request at a time, in order: a removal must not race the
+# deploy it follows, and half a deploy is a release uploaded but not live.
+concurrency:
+  group: preview-${{ github.event.pull_request.number }}
+  cancel-in-progress: false
+
+permissions:
+  contents: read
+  pull-requests: write
+
+jobs:
+  preview:
+    # Only pull requests from this repository. A fork's pull request runs
+    # without secrets, and deploying its code with them would hand the fork
+    # this app's preview credentials and SSH access to the box.
+    if: github.event.pull_request.head.repo.full_name == github.repository
+    runs-on: ubuntu-latest
+    environment: preview
+    env:
+      PREVIEW: pr-${{ github.event.pull_request.number }}
+
+    steps:
+      # A repository that has not set previews up finishes green with a notice,
+      # rather than failing every pull request.
+      - name: Are previews configured?
+        id: check
+        env:
+          DOTENV_PRIVATE_KEY_PREVIEW: ${{ secrets.DOTENV_PRIVATE_KEY_PREVIEW }}
+          DEPLOY_SSH_KEY: ${{ secrets.DEPLOY_SSH_KEY }}
+        run: |
+          if [ -n "$DOTENV_PRIVATE_KEY_PREVIEW" ] && [ -n "$DEPLOY_SSH_KEY" ]; then
+            echo 'configured=true' >> "$GITHUB_OUTPUT"
+          else
+            echo 'configured=false' >> "$GITHUB_OUTPUT"
+            echo '::notice::Previews are not configured, so this run did nothing. Add DEPLOY_SSH_KEY and DOTENV_PRIVATE_KEY_PREVIEW (from .env.keys), and set PREVIEW_DOMAIN.'
+          fi
+
+      - name: Checkout
+        if: steps.check.outputs.configured == 'true'
+        uses: actions/checkout@v6
+        with:
+          # The pull request's head, not the merge commit GitHub builds.
+          ref: ${{ github.event.pull_request.head.sha }}
+
+      - name: Setup Bun
+        if: steps.check.outputs.configured == 'true'
+        uses: oven-sh/setup-bun@v2
+
+      - name: Setup Pantry
+        if: steps.check.outputs.configured == 'true'
+        uses: home-lang/pantry/packages/action@main
+
+      - name: Install dependencies
+        if: steps.check.outputs.configured == 'true'
+        run: bun install --frozen-lockfile
+
+      - name: Load the deploy key
+        if: steps.check.outputs.configured == 'true'
+        env:
+          DEPLOY_SSH_KEY: ${{ secrets.DEPLOY_SSH_KEY }}
+        run: |
+          mkdir -p ~/.ssh
+          chmod 700 ~/.ssh
+          printf '%s\n' "$DEPLOY_SSH_KEY" > ~/.ssh/id_ed25519
+          chmod 600 ~/.ssh/id_ed25519
+          ssh-keygen -y -f ~/.ssh/id_ed25519 > ~/.ssh/id_ed25519.pub
+          chmod 644 ~/.ssh/id_ed25519.pub
+          eval "$(ssh-agent -s)" >/dev/null
+          ssh-add ~/.ssh/id_ed25519
+          echo "SSH_AUTH_SOCK=$SSH_AUTH_SOCK" >> "$GITHUB_ENV"
+
+      - name: Deploy the preview
+        id: deploy
+        if: steps.check.outputs.configured == 'true' && github.event.action != 'closed'
+        run: ./buddy deploy:preview "$PREVIEW"
+        env:
+          DOTENV_PRIVATE_KEY_PREVIEW: ${{ secrets.DOTENV_PRIVATE_KEY_PREVIEW }}
+          PREVIEW_DOMAIN: ${{ vars.PREVIEW_DOMAIN }}
+          HCLOUD_TOKEN: ${{ secrets.HCLOUD_TOKEN }}
+          PORKBUN_API_KEY: ${{ secrets.PORKBUN_API_KEY }}
+          PORKBUN_SECRET_KEY: ${{ secrets.PORKBUN_SECRET_KEY }}
+          CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+          COPYFILE_DISABLE: '1'
+
+      - name: Remove the preview
+        id: remove
+        if: steps.check.outputs.configured == 'true' && github.event.action == 'closed'
+        run: ./buddy deploy:preview:remove "$PREVIEW"
+        env:
+          DOTENV_PRIVATE_KEY_PREVIEW: ${{ secrets.DOTENV_PRIVATE_KEY_PREVIEW }}
+          PREVIEW_DOMAIN: ${{ vars.PREVIEW_DOMAIN }}
+          HCLOUD_TOKEN: ${{ secrets.HCLOUD_TOKEN }}
+          PORKBUN_API_KEY: ${{ secrets.PORKBUN_API_KEY }}
+          PORKBUN_SECRET_KEY: ${{ secrets.PORKBUN_SECRET_KEY }}
+          CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+
+      # One comment per pull request, edited in place rather than added to on
+      # every push, found by the marker on its first line.
+      - name: Say where it is
+        if: always() && steps.check.outputs.configured == 'true' && (steps.deploy.outcome != 'skipped' || steps.remove.outcome != 'skipped')
+        env:
+          GH_TOKEN: ${{ github.token }}
+          NUMBER: ${{ github.event.pull_request.number }}
+          URL: ${{ steps.deploy.outputs.url }}
+          DEPLOYED: ${{ steps.deploy.outcome }}
+          REMOVED: ${{ steps.remove.outcome }}
+          SHA: ${{ github.event.pull_request.head.sha }}
+        run: |
+          marker='<!-- stacks-preview -->'
+          if [ "$REMOVED" = 'success' ]; then
+            body="$marker"$'\n'"Preview removed: the pull request is closed."
+          elif [ "$DEPLOYED" = 'success' ]; then
+            body="$marker"$'\n'"Preview of ${SHA::7}: $URL"
+          else
+            body="$marker"$'\n'"The preview of ${SHA::7} failed to deploy; see the run: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}"
+          fi
+          existing=$(gh api "repos/${{ github.repository }}/issues/$NUMBER/comments" --paginate --jq ".[] | select(.body | startswith(\"$marker\")) | .id" | head -n 1)
+          if [ -n "$existing" ]; then
+            gh api -X PATCH "repos/${{ github.repository }}/issues/comments/$existing" -f body="$body" >/dev/null
+          else
+            gh api "repos/${{ github.repository }}/issues/$NUMBER/comments" -f body="$body" >/dev/null
+          fi