From 49891133c01abdcc7bd42f47c5608867659e7294 Mon Sep 17 00:00:00 2001
From: Rias Van der Veken <rias@pixelandtonic.com>
Date: Wed, 28 Oct 2026 15:25:12 +0000
Subject: [PATCH] Prepare Commerce toolchains and workbench for orbs

---
 .agents/resume     |  5 +++
 .agents/setup      | 77 ++++++++++++++++++++++++++++++++++++++++++++++
 .amp/services.yaml | 11 +++++++
 .gitignore         |  1 +
 .node-version      |  1 +
 README.md          | 14 +++++++++
 6 files changed, 109 insertions(+)
 create mode 100755 .agents/resume
 create mode 100755 .agents/setup
 create mode 100644 .amp/services.yaml
 create mode 100644 .node-version

diff --git a/.agents/resume b/.agents/resume
new file mode 100755
index 0000000000..823c7502e0
--- /dev/null
+++ b/.agents/resume
@@ -0,0 +1,5 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Toolchains, dependencies, built assets, and SQLite survive snapshot restore.
+# Amp's service supervisor restarts the declared workbench; no installs on wake.
diff --git a/.agents/setup b/.agents/setup
new file mode 100755
index 0000000000..e87163c7b9
--- /dev/null
+++ b/.agents/setup
@@ -0,0 +1,77 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+cd "$(dirname "${BASH_SOURCE[0]}")/.."
+export CI=true HUSKY=0 COMPOSER_NO_INTERACTION=1 COMPOSER_ROOT_VERSION=6.x-dev
+TIMEFORMAT='Finished in %3R seconds'
+
+step() {
+    printf '\n==> %s\n' "$1"
+    shift
+    time "$@"
+}
+
+scratch=$(mktemp -d)
+trap 'rm -rf -- "$scratch"' EXIT
+
+# Debian's default PHP is older than Commerce's minimum version.
+if [[ ! -f /usr/share/keyrings/debsuryorg-archive-keyring.gpg ]]; then
+    curl -fsSL https://packages.sury.org/debsuryorg-archive-keyring.deb -o "$scratch/sury.deb"
+    sudo dpkg -i "$scratch/sury.deb"
+fi
+if [[ ! -f /etc/apt/sources.list.d/php.list ]]; then
+    . /etc/os-release
+    echo "deb [signed-by=/usr/share/keyrings/debsuryorg-archive-keyring.gpg] https://packages.sury.org/php/ $VERSION_CODENAME main" |
+        sudo tee /etc/apt/sources.list.d/php.list >/dev/null
+fi
+
+packages=(php8.5-cli php8.5-bcmath php8.5-curl php8.5-gd php8.5-intl
+    php8.5-mbstring php8.5-mysql php8.5-pgsql php8.5-sqlite3 php8.5-xml
+    php8.5-zip php8.5-soap php8.5-imagick libvips42 unzip sqlite3)
+missing=()
+for package in "${packages[@]}"; do
+    if [[ $(dpkg-query -W -f='${Status}' "$package" 2>/dev/null || true) != 'install ok installed' ]]; then
+        missing+=("$package")
+    fi
+done
+if ((${#missing[@]})); then
+    step 'Refresh apt indexes' sudo apt-get update -qq
+    step 'Install PHP and image libraries' sudo env DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends "${missing[@]}"
+fi
+sudo update-alternatives --set php /usr/bin/php8.5
+
+# Install to the standard PATH for Amp and supervised non-interactive shells.
+node_major=$(tr -d '[:space:]' < .node-version)
+if [[ $(node -p 'process.versions.node.split(".")[0]' 2>/dev/null || true) != "$node_major" ]] ||
+    ! npm ls --global --depth=0 >/dev/null 2>&1; then
+    case $(uname -m) in
+        x86_64) node_arch=x64 ;;
+        aarch64) node_arch=arm64 ;;
+        *) echo 'Unsupported Node architecture' >&2; exit 1 ;;
+    esac
+    curl -fsSL "https://nodejs.org/dist/latest-v${node_major}.x/SHASUMS256.txt" -o "$scratch/SHASUMS256.txt"
+    archive=$(awk -v arch="linux-$node_arch.tar.xz" '$2 ~ arch "$" {print $2}' "$scratch/SHASUMS256.txt")
+    curl -fsSL "https://nodejs.org/dist/latest-v${node_major}.x/$archive" -o "$scratch/$archive"
+    (cd "$scratch"; grep " $archive$" SHASUMS256.txt | sha256sum --check)
+    sudo rm -rf /usr/local/lib/node_modules/npm /usr/local/lib/node_modules/corepack
+    sudo tar -xJf "$scratch/$archive" -C /usr/local --strip-components=1
+fi
+pnpm_version=$(node -p 'require("./package.json").packageManager.split("@")[1]')
+if [[ $(pnpm --version 2>/dev/null || true) != "$pnpm_version" ]]; then
+    step 'Install pinned pnpm' sudo npm install --global "pnpm@$pnpm_version"
+fi
+if ! command -v composer >/dev/null; then
+    curl -fsSL https://getcomposer.org/installer -o "$scratch/composer-setup.php"
+    expected=$(curl -fsSL https://composer.github.io/installer.sig)
+    actual=$(php -r 'echo hash_file("sha384", $argv[1]);' "$scratch/composer-setup.php")
+    [[ "$actual" == "$expected" ]] || { echo 'Composer installer checksum mismatch' >&2; exit 1; }
+    php "$scratch/composer-setup.php" --2 --install-dir="$scratch" --filename=composer
+    sudo install -m 755 "$scratch/composer" /usr/local/bin/composer
+fi
+
+step 'Install PHP dependencies' composer install --prefer-dist --no-progress
+step 'Install frontend dependencies' pnpm install --prefer-offline --frozen-lockfile
+step 'Build Commerce assets' pnpm build
+step 'Prepare SQLite workbench' composer workbench:setup
+
+printf '\nOrb toolchain, dependencies, and workbench are ready.\n'
diff --git a/.amp/services.yaml b/.amp/services.yaml
new file mode 100644
index 0000000000..8fb292f3b5
--- /dev/null
+++ b/.amp/services.yaml
@@ -0,0 +1,11 @@
+services:
+  workbench:
+    command: >-
+      php workbench/prepare.php &&
+      php vendor/bin/testbench optimize:clear --no-interaction &&
+      APP_URL="$PUBLIC_URL" ASSET_URL="$PUBLIC_URL"
+      php vendor/bin/testbench serve --host=127.0.0.1 --port="$PORT" --no-interaction
+    health: /
+    portal:
+      title: Commerce workbench
+      description: Opens the Commerce control panel and signs in as the seeded admin.
diff --git a/.gitignore b/.gitignore
index 6a69229fb4..dacf0031ae 100644
--- a/.gitignore
+++ b/.gitignore
@@ -11,6 +11,7 @@ node_modules/
 # Vue 3/Vite pipeline output (matches cms's own convention); legacy/'s webpack dist/ stays committed — no CI build step for it.
 /public/build
 /public/hot
+/.amp/portals/*
 .env
 .phpunit.cache
 *-private.md
diff --git a/.node-version b/.node-version
new file mode 100644
index 0000000000..a45fd52cc5
--- /dev/null
+++ b/.node-version
@@ -0,0 +1 @@
+24
diff --git a/README.md b/README.md
index 611a7b27db..ec4d149f0b 100644
--- a/README.md
+++ b/README.md
@@ -58,6 +58,20 @@ Run `pnpm dev` in a second terminal for Commerce component updates. After rebuil
 
 To reset the local site, stop the server, delete `workbench/database/database.sqlite*` and `workbench/config/craft/project`, then run `composer workbench:setup`.
 
+### Amp orbs
+
+`.agents/setup` installs PHP 8.5 and its extensions, Node 24, the pinned pnpm version, and the locked Composer and pnpm dependencies. It builds Commerce's frontend and prepares the SQLite workbench. Amp snapshots these files so fresh orbs can reuse them. `.agents/resume` does not reinstall dependencies or reset the database.
+
+Start the supervised workbench and open its portal with:
+
+```bash
+amp orb services ensure
+```
+
+Open the Commerce workbench URL printed by the command to sign in automatically as the seeded admin. The service uses Amp's assigned port and public URL for redirects and assets without changing `workbench/.env`. Only expose this development workbench through Amp's authenticated portal.
+
+After changing the service configuration, run `amp orb service restart workbench`. Use `amp orb service logs workbench` to inspect startup errors. Commerce frontend changes still use `pnpm build` followed by `composer workbench:setup` to republish assets.
+
 ## Resources
 
 We highly recommend you check out these resources as you’re getting started with Craft Commerce: