@pressgang-wp/shakedown 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Benedict
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,151 @@
+# 🚢 Shakedown
+
+**Shakedown** is end-to-end browser testing for **PressGang WordPress themes** — with **zero tests to write**.
+
+A shakedown cruise is the sea trial of a new vessel: take her out, push every system, find what rattles before the passengers board. Shakedown does the same for your theme. Because PressGang themes declare their post types, taxonomies, templates and menus in `config/`, Shakedown can **derive the whole test suite from the site itself** — enumerate every route, then check each one in a real browser.
+
+Point it at a running site and in under a minute you'll know: does every page render, error-free, with nothing broken aboard? ⛵
+
+---
+
+## ⚡ Quick start
+
+You need Node 20+, WP-CLI, and a PressGang site running locally (any server — Herd, Valet, DDEV, MAMP… it's just a URL). From inside your theme:
+
+```bash
+npm i -D github:pressgang-wp/pressgang-shakedown
+npx playwright install chromium   # once per machine
+npx shakedown                     # ⚓ derive the matrix, run every pass
+```
+
+That's it. Shakedown walks up from your theme to find `wp-config.php`, asks WP-CLI for the site URL, enumerates every route, and checks them all — **no config, no specs written**.
+
+Other commands:
+
+```bash
+npx shakedown matrix          # 🗺️ just enumerate and print the routes
+npx shakedown test            # 🧪 run passes against the existing matrix
+npx shakedown ui              # Playwright's watch/UI mode
+npx playwright show-report    # browse the last run
+```
+
+Optional `shakedown.config.json` in the theme, for overrides only:
+
+```json
+{
+  "baseUrl": "https://mysite.test",
+  "samplesPerType": 2,
+  "searchTerm": "bikes",
+  "sandbox": {
+    "seed": 42,
+    "epoch": "2026-01-01T09:00:00+00:00"
+  }
+}
+```
+
+Authored journeys (form submissions, checkout flows) live in your theme's `tests/e2e/` — when present they run alongside the derived passes as the `journeys` project.
+
+Sandbox fixture randomness and time are separate deterministic inputs. `seed`
+controls generated values; `epoch` fixes relative dates used by Muster,
+including ACF date fields and the fixture posts themselves. It must be a
+timezone-qualified ISO 8601 datetime.
+
+**Introspection:** when [Capstan](https://github.com/pressgang-wp/pressgang-capstan) is installed (`wp package install pressgang-wp/pressgang-capstan`), the matrix comes from `wp capstan matrix --resolve` — including each route's expected template and controller. Without it, a bundled fallback derives the same routes minus the oracle data.
+
+**Central mode** (many sites from one clone): a `shakedown.config.json` with a `targets` map lets one checkout drive any registered site — `npx shakedown --target=mysite`.
+
+---
+
+## 🗺️ What gets tested
+
+`npm run matrix` asks the **running site** (via WP-CLI) for everything it serves:
+
+| Derived from | Routes |
+| --- | --- |
+| Front page | `/` |
+| Every public post type | its archive + sample singles |
+| Every public taxonomy | sample term pages |
+| Page templates | every published page using one |
+| Menus | every internal menu target |
+| Search | `/?s=…` |
+| Unknown URLs | a 404 probe |
+
+Add a post type to your theme's `config/custom-post-types.php` and the next run covers it automatically. The matrix is the map; the passes are the inspection. 🔦
+
+## 🧪 The passes
+
+| Pass | Speed | Checks |
+| --- | --- | --- |
+| **00 · Availability** | ~seconds (HTTP only) | Every route returns its intended status · no PHP/Twig error signatures in the body · a `<title>` is present. The 404 probe accepts a 404 *or* a redirect-away (Redirection-plugin catch-alls are fine). |
+| **01 · Integrity** | ~seconds–minutes (real Chromium) | No JS exceptions · no console errors · no failed same-origin requests · no broken images. |
+
+Useful variations:
+
+```bash
+npm test -- tests/00-availability.spec.ts   # just the fast pass
+npm run test:ui                             # Playwright's watch/UI mode
+npm run matrix -- othersite                 # derive for a named target
+npx playwright show-report                  # browse the last run's HTML report
+```
+
+When something fails you get the exact URL, what was expected, and a Playwright **trace** you can replay step-by-step. 🔍
+
+---
+
+## 💡 Good to know
+
+- **Read-only by design.** The passes only ever GET pages — safe to run against any environment you can reach.
+- **Testing a live shared server?** Runs are parallel; a single retry is built in to absorb load transients on one PHP-FPM.
+- **Self-signed `.test` certificates** are already handled (`ignoreHTTPSErrors`).
+- **True story:** on its very first run, Shakedown found a real bug — category archives returning `200` with an empty body. Zero tests written. That's the pitch. 🐛
+
+---
+
+## 🤖 CI
+
+A reusable GitHub Actions workflow runs the full sandbox suite on every push — no MySQL, no Docker, no site bundle. The theme repo is the only input: WordPress core is downloaded bare, your `composer.json`'s installer-paths provision the parent theme and plugins, and the sandbox brings its own SQLite database and ACF state fixtures.
+
+In your theme repo, `.github/workflows/shakedown.yml`:
+
+```yaml
+name: Shakedown
+on: [push, pull_request]
+jobs:
+  shakedown:
+    uses: pressgang-wp/pressgang-shakedown/.github/workflows/shakedown.yml@main
+    secrets:
+      COMPOSER_AUTH: ${{ secrets.COMPOSER_AUTH }}   # ACF Pro credentials, if composer-managed
+```
+
+Inputs (all optional): `theme` (defaults to the repo name), `php-version`,
+`wp-version`, `node-version`, and `muster-ref`. The workflow pins `muster-ref` to
+the exact fixture engine revision it was verified against; override it only as
+an intentional compatibility test. The Playwright HTML report and route matrix
+upload as artifacts on every run. Suits theme-shaped repos; site-shaped repos
+work too once their theme path is passed as `theme`. 🧪
+
+## ⚓ The PressGang fleet
+
+Shakedown is part of the [PressGang](https://pressgang.dev) ecosystem and is designed to compose with its shipmates:
+
+| Package | Role |
+| --- | --- |
+| [pressgang](https://github.com/pressgang-wp/pressgang) | The parent theme framework (Timber + Twig, config-driven) |
+| [capstan](https://github.com/pressgang-wp/pressgang-capstan) | WP-CLI scaffolding & introspection — future source of the route matrix and per-URL controller/template oracle |
+| [muster](https://github.com/pressgang-wp/pressgang-muster) | Seeds deterministic populated/minimal ACF states in the disposable sandbox |
+| [bosun](https://github.com/pressgang-wp/pressgang-bosun) | AI-agent guidelines & skills — future distribution channel for Shakedown's QA skills |
+
+## 🛠️ Roadmap
+
+- `wp capstan matrix --format=json` + **oracle assertions** — assert each URL rendered via its *intended* controller and Twig template, catching silent fallbacks to `index.php`
+- **Observer mu-plugin** — PHP notice capture and render telemetry (template/snippet coverage)
+- More passes: **accessibility** (axe-core), **visual snapshots**
+- **Trial Report** — a client-readable HTML report with screenshots and coverage
+- Engines: self-booting **WordPress Playground**, per-PR **InstaWP** CI sites, **wp-env** fidelity lane
+- Published as `@pressgang-wp/shakedown` on npm
+
+## 📋 Requirements
+
+- Node 20+
+- WP-CLI on your PATH
+- A locally reachable PressGang (or any WordPress) site — the derived passes are actually framework-agnostic; PressGang is where the deeper introspection is headed

package/bin/derive-matrix.mjs

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+/**
+ * Thin wrapper kept for `npm run matrix` in this repo.
+ * The real logic lives in lib/target.mjs and lib/derive.mjs;
+ * the `shakedown` CLI (bin/shakedown.mjs) is the primary entry point.
+ *
+ * Usage: node bin/derive-matrix.mjs [target]
+ */
+import { resolveTarget } from '../lib/target.mjs';
+import { deriveMatrix } from '../lib/derive.mjs';
+
+const target = resolveTarget(process.cwd(), { target: process.argv[2] });
+const { matrix, source, path } = deriveMatrix(target, process.cwd());
+
+console.log(`Matrix for "${target.name}": ${matrix.routes.length} routes (via ${source}) → ${path}`);
+for (const r of matrix.routes) {
+  console.log(`  [${r.expect}] ${r.kind.padEnd(28)} ${r.url}`);
+}

package/bin/matrix.php

@@ -0,0 +1,166 @@
+<?php
+/**
+ * Emits the shakedown route matrix for the current site as JSON.
+ *
+ * Runs inside WordPress via `wp eval-file bin/matrix.php <samplesPerType> <searchTerm>`
+ * (invoked by bin/derive-matrix.mjs, which supplies the args from shakedown.config.json).
+ *
+ * Route shape: `['url' => string, 'kind' => string, 'expect' => int]` where
+ * `kind` is a `family:detail` label (`archive:event`, `template:contact-page.php`, …)
+ * and `expect` is the intended HTTP status.
+ *
+ * Functions are prefixed `shakedown_` because eval-file executes in global scope.
+ */
+
+/**
+ * Append a route unless the URL is empty or a WP_Error.
+ *
+ * @param array<int, array<string, mixed>> $routes
+ * @param string|\WP_Error|false           $url
+ * @param string                           $kind
+ * @param int                              $expect
+ * @return void
+ */
+function shakedown_add( array &$routes, $url, string $kind, int $expect = 200 ): void {
+	if ( $url && ! is_wp_error( $url ) ) {
+		$routes[] = [ 'url' => $url, 'kind' => $kind, 'expect' => $expect ];
+	}
+}
+
+/**
+ * Archive link plus sample singles for every public post type.
+ *
+ * @param int $samples Published singles to include per type.
+ * @return array<int, array<string, mixed>>
+ */
+function shakedown_post_type_routes( int $samples ): array {
+	$routes = [];
+
+	foreach ( get_post_types( [ 'public' => true ], 'objects' ) as $pt ) {
+		if ( $pt->has_archive ) {
+			shakedown_add( $routes, get_post_type_archive_link( $pt->name ), "archive:{$pt->name}" );
+		}
+
+		$posts = get_posts( [ 'post_type' => $pt->name, 'numberposts' => $samples, 'post_status' => 'publish' ] );
+		foreach ( $posts as $p ) {
+			shakedown_add( $routes, get_permalink( $p ), "single:{$pt->name}" );
+		}
+	}
+
+	return $routes;
+}
+
+/**
+ * Sample term pages for every public taxonomy (non-empty terms only).
+ *
+ * @return array<int, array<string, mixed>>
+ */
+function shakedown_taxonomy_routes(): array {
+	$routes = [];
+
+	foreach ( get_taxonomies( [ 'public' => true ], 'names' ) as $tax ) {
+		$terms = get_terms( [ 'taxonomy' => $tax, 'number' => 3, 'hide_empty' => true ] );
+		if ( is_wp_error( $terms ) ) {
+			continue;
+		}
+		foreach ( $terms as $t ) {
+			shakedown_add( $routes, get_term_link( $t ), "term:{$tax}" );
+		}
+	}
+
+	return $routes;
+}
+
+/**
+ * Every published page assigned a non-default page template.
+ *
+ * These exercise the theme's registered templates end-to-end, keyed by
+ * template slug so failures name the template, not just the page.
+ *
+ * @return array<int, array<string, mixed>>
+ */
+function shakedown_template_routes(): array {
+	$routes = [];
+
+	$pages = get_posts( [
+		'post_type'      => 'page',
+		'numberposts'    => -1,
+		'post_status'    => 'publish',
+		'meta_key'       => '_wp_page_template',
+	] );
+
+	foreach ( $pages as $p ) {
+		$tpl = get_page_template_slug( $p );
+		if ( $tpl && 'default' !== $tpl ) {
+			shakedown_add( $routes, get_permalink( $p ), "template:{$tpl}" );
+		}
+	}
+
+	return $routes;
+}
+
+/**
+ * Internal targets of every registered nav menu (external links are skipped —
+ * shakedown only tests the site under trial).
+ *
+ * @return array<int, array<string, mixed>>
+ */
+function shakedown_menu_routes(): array {
+	$routes = [];
+
+	foreach ( wp_get_nav_menus() as $menu ) {
+		$items = wp_get_nav_menu_items( $menu ) ?: [];
+		foreach ( $items as $item ) {
+			if ( 0 === strpos( (string) $item->url, home_url() ) ) {
+				shakedown_add( $routes, $item->url, "menu:{$menu->slug}" );
+			}
+		}
+	}
+
+	return $routes;
+}
+
+/**
+ * Drop duplicate URLs, keeping the first (most specific) kind label.
+ *
+ * @param array<int, array<string, mixed>> $routes
+ * @return array<int, array<string, mixed>>
+ */
+function shakedown_dedupe( array $routes ): array {
+	$seen = [];
+
+	return array_values( array_filter( $routes, function ( array $r ) use ( &$seen ): bool {
+		if ( isset( $seen[ $r['url'] ] ) ) {
+			return false;
+		}
+		$seen[ $r['url'] ] = true;
+
+		return true;
+	} ) );
+}
+
+$samples     = isset( $args[0] ) ? (int) $args[0] : 2;
+$search_term = isset( $args[1] ) ? (string) $args[1] : 'test';
+
+$routes = [];
+shakedown_add( $routes, home_url( '/' ), 'home' );
+
+$routes = array_merge(
+	$routes,
+	shakedown_post_type_routes( $samples ),
+	shakedown_taxonomy_routes(),
+	shakedown_template_routes(),
+	shakedown_menu_routes(),
+);
+
+shakedown_add( $routes, home_url( '/?s=' . rawurlencode( $search_term ) ), 'search' );
+shakedown_add( $routes, home_url( '/shakedown-404-probe' ), '404', 404 );
+
+echo json_encode(
+	[
+		'generated' => gmdate( 'c' ),
+		'home'      => home_url( '/' ),
+		'routes'    => shakedown_dedupe( $routes ),
+	],
+	JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES
+);

package/bin/seed-states.php

@@ -0,0 +1,116 @@
+<?php
+/**
+ * Seeds ACF state fixtures inside a shakedown SANDBOX (never a real site —
+ * the sandbox isolation witness has already proven this WordPress runs on
+ * throwaway SQLite before this script is invoked).
+ *
+ * For every ACF field group with a seedable location target, creates two
+ * published fixtures via Muster:
+ *   - populated: every generatable field filled (deterministic, seeded)
+ *   - minimal:   required fields only — the sparsest state an editor can
+ *                legally publish, where empty-link/missing-image bugs live
+ *
+ * Run via: wp eval-file bin/seed-states.php <muster-autoload> <acf-json-dir> <seed> <epoch>
+ * Emits JSON: {"routes": [{url, kind, expect}...]} for the matrix.
+ */
+
+if (count($args) < 4) {
+	throw new InvalidArgumentException('seed-states.php requires Muster autoload, ACF JSON directory, seed, and epoch arguments.');
+}
+
+[$autoload, $acfJsonDir, $seed, $epoch] = [$args[0], $args[1], (int) $args[2], (string) $args[3]];
+
+if (! preg_match('/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})$/i', $epoch)) {
+	throw new InvalidArgumentException('Fixture epoch must be a timezone-qualified ISO 8601 datetime.');
+}
+
+require_once $autoload;
+
+use PressGang\Muster\Acf\AcfJson;
+use PressGang\Muster\Acf\AcfValueGenerator;
+use PressGang\Muster\Adapters\LiveAcfAdapter;
+use PressGang\Muster\Builders\AttachmentBuilder;
+use PressGang\Muster\Builders\PostBuilder;
+use PressGang\Muster\Builders\TermBuilder;
+use PressGang\Muster\Clock\FixtureClock;
+use PressGang\Muster\MusterContext;
+use PressGang\Muster\Victuals\VictualsFactory;
+
+$context = new MusterContext(
+	new VictualsFactory(),
+	acf: new LiveAcfAdapter(),
+	seed: $seed,
+	clock: new FixtureClock($epoch),
+);
+$fixtureDate = $context->clock()->epoch()->format('Y-m-d H:i:s');
+
+$generator = new AcfValueGenerator($context->victuals(), [
+	'attachment' => fn (string $name): int => (new AttachmentBuilder($context, 'state-' . sanitize_title($name)))
+		->placeholder(1200, 800)
+		->save()
+		->id(),
+	'post' => function (array $types) use ($context): int {
+		$type = $types[0] ?? 'post';
+
+		return (new PostBuilder($context, $type))
+			->title('State related ' . $type)
+			->slug('state-related-' . sanitize_title($type))
+			->status('publish')
+			->save()
+			->id();
+	},
+	'term' => fn (string $taxonomy): int => (new TermBuilder($context, $taxonomy))
+		->name('State term')
+		->slug('state-term')
+		->save()
+		->termId(),
+	'user' => fn (): int => 1,
+]);
+
+$routes = [];
+
+foreach (AcfJson::groups($acfJsonDir) as $group) {
+	$targets = AcfJson::targets($group);
+
+	if ($targets === []) {
+		continue; // menu items, page_type rules — not seedable (v1)
+	}
+
+	$target = $targets[0];
+
+	// Options-page groups are global state, not a URL: seed the populated
+	// values once so chrome (header/footer) renders fully. The unseeded
+	// fresh install already exercises the empty-options state.
+	if ($target['param'] === 'options_page') {
+		(new LiveAcfAdapter())->updateFields($generator->populated((array) $group['fields']), 'option', 0);
+		continue;
+	}
+	$slugBase = sanitize_title($group['title'] ?? $group['key']);
+
+	foreach (['populated', 'minimal'] as $variant) {
+		$fields = (array) $group['fields'];
+		$values = $variant === 'populated' ? $generator->populated($fields) : $generator->minimal($fields);
+
+		$builder = $target['param'] === 'page_template'
+			? (new PostBuilder($context, 'page'))->template($target['value'])
+			: new PostBuilder($context, $target['value']);
+
+		$ref = $builder
+			->title(($group['title'] ?? $group['key']) . ' — ' . $variant)
+			->slug("state-{$slugBase}-{$variant}")
+			->status('publish')
+			->date($fixtureDate)
+
+			->content('State fixture: ' . $slugBase . ' (' . $variant . ')')
+			->acf($values)
+			->save();
+
+		$url = get_permalink($ref->id());
+
+		if ($url) {
+			$routes[] = [ 'url' => $url, 'kind' => "state:{$slugBase}:{$variant}", 'expect' => 200 ];
+		}
+	}
+}
+
+echo json_encode([ 'routes' => $routes ], JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES);

package/bin/shakedown.mjs

@@ -0,0 +1,166 @@
+#!/usr/bin/env node
+/**
+ * shakedown — sea trials for PressGang themes.
+ *
+ * Run from inside a theme (or anywhere in a WordPress project):
+ *
+ *   shakedown            derive the matrix, then run every pass
+ *   shakedown matrix     derive and print the route matrix only
+ *   shakedown test [...] run passes (extra args pass through to Playwright)
+ *   shakedown ui         Playwright UI mode
+ *
+ * The invocation directory is the workspace: matrix, reports, and traces are
+ * written there, and its tests/e2e/ (if present) runs as the journeys suite.
+ */
+import { spawnSync } from 'node:child_process';
+import { createRequire } from 'node:module';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { existsSync } from 'node:fs';
+import { resolveTarget } from '../lib/target.mjs';
+import { capstanDoctor, deriveMatrix, mergeRoutes } from '../lib/derive.mjs';
+import { bootSandbox, DEFAULT_FIXTURE_EPOCH, seedAcfStates } from '../lib/sandbox.mjs';
+
+const pkgRoot = dirname(dirname(fileURLToPath(import.meta.url)));
+const workspace = process.cwd();
+
+const argv = process.argv.slice(2);
+const targetFlag = (argv.find((a) => a.startsWith('--target=')) || '').split('=')[1];
+const args = argv.filter((a) => !a.startsWith('--target='));
+const command = args[0] ?? 'all';
+
+/**
+ * Locate Muster's autoloader for sandbox seeding: explicit config first,
+ * then the theme's own composer vendor, then a sibling checkout of the
+ * pressgang-muster repo (fleet-dev convenience).
+ *
+ * @param {ReturnType<import('../lib/target.mjs').resolveTarget>} target
+ * @returns {string|null}
+ */
+function findMusterAutoload(target) {
+  const candidates = [
+    process.env.SHAKEDOWN_MUSTER_PATH && join(process.env.SHAKEDOWN_MUSTER_PATH, 'vendor/autoload.php'),
+    process.env.SHAKEDOWN_MUSTER_PATH,
+    target.sandbox?.musterPath && join(target.sandbox.musterPath, 'vendor/autoload.php'),
+    target.sandbox?.musterPath,
+    join(workspace, 'vendor/pressgang-wp/muster/vendor/autoload.php'),
+    existsSync(join(workspace, 'vendor/pressgang-wp/muster')) ? join(workspace, 'vendor/autoload.php') : null,
+    join(pkgRoot, '../pressgang-muster/vendor/autoload.php'),
+  ].filter(Boolean);
+
+  return candidates.find((p) => existsSync(p)) ?? null;
+}
+
+/**
+ * Pre-flight: surface `wp capstan doctor` config health before testing.
+ * A theme with FAILing checks isn't worth driving a browser at — abort with
+ * the failing checks named. Silent no-op when Capstan isn't installed.
+ */
+function preflight(sitePath) {
+  const health = capstanDoctor(sitePath);
+  if (!health) return;
+
+  console.log(`⚓ capstan doctor: ${health.checks.length} checks, ${health.failures} failures, ${health.warnings} warnings`);
+
+  for (const check of health.checks.filter((c) => c.status !== 'OK')) {
+    console.log(`  [${check.status}] ${check.check}: ${check.detail}`);
+  }
+
+  if (health.failures > 0) {
+    throw new Error('capstan doctor reports configuration failures — fix the theme before running trials.');
+  }
+}
+
+/** Derive and persist the matrix, printing a summary. */
+function matrix(target) {
+  const { matrix: m, source } = deriveMatrix(target, workspace);
+  console.log(`⚓ ${m.routes.length} routes for ${target.baseUrl} (via ${source})`);
+
+  return m;
+}
+
+/** Run Playwright with the packaged config against the workspace. */
+function test(extraArgs = []) {
+  // Resolve Playwright's CLI from this package's own dependency tree —
+  // consumers installing via file:/github: symlinks have no `playwright`
+  // binary on their PATH or in their local node_modules/.bin.
+  const playwrightCli = createRequire(import.meta.url).resolve('@playwright/test/cli');
+
+  const result = spawnSync(
+    process.execPath,
+    [playwrightCli, 'test', `--config=${join(pkgRoot, 'playwright.config.mjs')}`, ...extraArgs],
+    {
+      cwd: workspace,
+      stdio: 'inherit',
+      env: { ...process.env, SHAKEDOWN_WORKSPACE: workspace },
+    }
+  );
+
+  process.exitCode = result.status ?? 1;
+}
+
+try {
+  const target = resolveTarget(workspace, { target: targetFlag }, { requireBaseUrl: command !== 'sandbox' });
+
+  switch (command) {
+    case 'matrix':
+      for (const r of matrix(target).routes) {
+        console.log(`  [${r.expect}] ${r.kind.padEnd(28)} ${r.url}`);
+      }
+      break;
+    case 'test':
+      test(args.slice(1));
+      break;
+    case 'ui':
+      test(['--ui']);
+      break;
+    case 'all':
+      preflight(target.sitePath);
+      matrix(target);
+      test(args.slice(1));
+      break;
+    case 'sandbox': {
+      // Throwaway WP: your code, symlinked read-only; its own SQLite DB and
+      // uploads in a temp dir. The real database is never touched — this is
+      // the only engine allowed to seed, because nothing persists.
+      console.log('⚓ assembling sandbox (fresh SQLite, code symlinked read-only)…');
+      const sandbox = await bootSandbox(target);
+      console.log(`⚓ sandbox up at ${sandbox.baseUrl} (isolation verified)`);
+      try {
+        // ACF state fixtures — populated + minimal per field group. Seeding
+        // is sandbox-only by design: the isolation witness has already
+        // proven this database is throwaway.
+        let states = [];
+        const muster = findMusterAutoload(target);
+        if (muster) {
+          states = seedAcfStates(sandbox, muster, {
+            seed: target.sandbox?.seed ?? 42,
+            epoch: target.sandbox?.epoch ?? DEFAULT_FIXTURE_EPOCH,
+          });
+          console.log(`⚓ seeded ${states.length} ACF state fixtures via Muster`);
+        } else {
+          console.log('⚓ Muster not found — skipping ACF state fixtures (set sandbox.musterPath)');
+        }
+
+        preflight(sandbox.root);
+        matrix({ ...target, name: 'sandbox', sitePath: sandbox.root, baseUrl: sandbox.baseUrl });
+
+        if (states.length > 0) {
+          mergeRoutes(workspace, states);
+        }
+
+        test(args.slice(1));
+      } finally {
+        sandbox.stop();
+        console.log('⚓ sandbox destroyed');
+      }
+      break;
+    }
+    default:
+      console.error(`Unknown command "${command}". Usage: shakedown [matrix|test|ui|sandbox] [--target=<name>]`);
+      process.exitCode = 1;
+  }
+} catch (err) {
+  console.error(`shakedown: ${err.message}`);
+  process.exitCode = 1;
+}