wheels-dev
diff --git a/‎.github/workflows/deploy-ci.yml‎
Lines changed: 110 additions & 0 deletions b/‎.github/workflows/deploy-ci.yml‎
Lines changed: 110 additions & 0 deletions
diff --git a/‎CLAUDE.md‎
Lines changed: 83 additions & 1 deletion b/‎CLAUDE.md‎
Lines changed: 83 additions & 1 deletion
@@ -0,0 +1,110 @@
+# Deploy subsystem CI gate
+#
+# Runs the CLI test suite plus the deploy-specific harness scripts on any
+# PR/push that touches the wheels-deploy subsystem (cli/lucli/services/deploy/**,
+# cli/lucli/lib/deploy/**, fixtures, helpers, or the tooling itself).
+#
+# This is narrower than the broader `pr.yml` fast-test workflow, which runs
+# the core framework test suite on every PR against `develop`. Keeping this
+# one path-scoped means framework-only edits don't re-run the (slower) deploy
+# matrix, and deploy-subsystem edits pick up an extra gate.
+#
+# Prerequisites (already present in this repo's CI):
+#   - LuCLI install recipe mirrors .github/workflows/pr.yml (cybersonic/LuCLI release).
+#   - Java 21 via actions/setup-java@v4.
+#
+# Gating model:
+#   1. cli-tests              - runs `tools/test-cli-local.sh`, must be 365+/0/0.
+#   2. deploy-config-diff     - informational (`continue-on-error: true`).
+#      The script expects Ruby Kamal on PATH *and* a routable `wheels deploy`.
+#      Neither is wired in CI yet, so this step's exit 1 is expected and
+#      non-gating until the `wheels` binary routes to this worktree's Module.cfc.
+#   3. deploy-verb-smoke      - calls `tools/deploy-verb-smoke.sh`, which already
+#      exits 0 with a warning when `wheels deploy` is unreachable. So this step
+#      is a no-op today, and becomes a real gate automatically the moment the
+#      LuCLI/Module.cfc routing lands.
+#
+# See `docs/superpowers/plans/2026-04-21-phase1-retrospective.md` for the
+# full deploy-gap write-up.
+
+name: Deploy Subsystem CI
+
+on:
+  push:
+    branches: [main, develop]
+    paths:
+      - 'cli/lucli/services/deploy/**'
+      - 'cli/lucli/lib/deploy/**'
+      - 'cli/lucli/templates/deploy/**'
+      - 'cli/lucli/tests/_fixtures/deploy/**'
+      - 'cli/lucli/tests/specs/deploy/**'
+      - 'cli/lucli/tests/_helpers/DeployShellHelper.cfc'
+      - 'cli/lucli/Module.cfc'
+      - 'tools/deploy-*.sh'
+      - 'tools/deploy-dry-run-normalize.py'
+      - 'tools/test-cli-local.sh'
+      - '.github/workflows/deploy-ci.yml'
+  pull_request:
+    paths:
+      - 'cli/lucli/services/deploy/**'
+      - 'cli/lucli/lib/deploy/**'
+      - 'cli/lucli/templates/deploy/**'
+      - 'cli/lucli/tests/_fixtures/deploy/**'
+      - 'cli/lucli/tests/specs/deploy/**'
+      - 'cli/lucli/tests/_helpers/DeployShellHelper.cfc'
+      - 'cli/lucli/Module.cfc'
+      - 'tools/deploy-*.sh'
+      - 'tools/deploy-dry-run-normalize.py'
+      - 'tools/test-cli-local.sh'
+      - '.github/workflows/deploy-ci.yml'
+
+permissions:
+  contents: read
+
+jobs:
+  deploy-gate:
+    name: "Deploy CLI tests + verb smoke"
+    runs-on: ubuntu-latest
+    env:
+      FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
+      LUCLI_VERSION: "0.3.3"
+      WHEELS_CI: "true"
+      PORT: "8080"
+    steps:
+      - uses: actions/checkout@v5
+
+      - name: Set up JDK 21
+        uses: actions/setup-java@v4
+        with:
+          distribution: 'temurin'
+          java-version: '21'
+
+      - name: Install LuCLI
+        run: |
+          curl -sL "https://github.com/cybersonic/LuCLI/releases/download/v${LUCLI_VERSION}/lucli-${LUCLI_VERSION}-linux" \
+            -o /usr/local/bin/lucli
+          chmod +x /usr/local/bin/lucli
+          lucli --version
+
+      - name: Create test databases
+        run: |
+          sudo apt-get update -y && sudo apt-get install -y --no-install-recommends sqlite3
+          sqlite3 wheelstestdb.db "SELECT 1;"
+          sqlite3 wheelstestdb_tenant_b.db "SELECT 1;"
+
+      - name: Run CLI test suite
+        run: bash tools/test-cli-local.sh
+
+      - name: Run deploy-config-diff (informational)
+        continue-on-error: true
+        run: |
+          bash tools/deploy-config-diff.sh \
+            || echo "deploy-config-diff: informational, non-gating (expected until 'wheels deploy' routes in CI)"
+
+      - name: Run deploy-verb-smoke (gates when wheels deploy reachable)
+        run: bash tools/deploy-verb-smoke.sh
+
+      - name: Debug server logs
+        if: failure()
+        run: |
+          cat /tmp/wheels-cli-test-server.log 2>/dev/null || true
@@ -739,6 +739,88 @@ wheels jobs monitor                        # live dashboard
 
 The `wheels_jobs` table is auto-created by `Job.cfc::$ensureJobTable()` on first enqueue or processing — no migration needed. (The older `20260221000001_createwheels_jobs_table.cfc` migration is vestigial; Phase 2b drift audit confirmed auto-create is now the path.)
 
+## Deploy Quick Reference
+
+`wheels deploy` ships your Dockerized Wheels app to production Linux servers via SSH. Ported from Basecamp Kamal's developer CLI — same `config/deploy.yml` schema, same on-server conventions (container names, labels, network, lock path), invokes the same `kamal-proxy` Go binary for zero-downtime rollover. No Ruby runtime required.
+
+    wheels deploy init                     # scaffold config/deploy.yml + .kamal/secrets
+    wheels deploy setup                    # one-time server bootstrap + first deploy
+    wheels deploy                          # rolling deploy
+    wheels deploy --dry-run                # print commands without executing
+    wheels deploy rollback v1              # roll back to a previous version
+    wheels deploy config                   # print resolved config as YAML
+    wheels deploy version                  # show Kamal version this port mirrors
+
+### Subcommands
+
+```cfm
+wheels deploy app <verb>         // boot/start/stop/details/containers/images/logs/live/maintenance/remove
+wheels deploy proxy <verb>       // boot/reboot/start/stop/restart/details/logs/remove
+wheels deploy accessory <verb>   // boot/reboot/start/stop/restart/details/logs/remove (sidecars: db/redis/search)
+wheels deploy build <verb>       // deliver/push/pull/create/remove/details/dev
+wheels deploy registry <verb>    // setup/login/logout/remove
+wheels deploy server <verb>      // exec/bootstrap
+wheels deploy prune <verb>       // all/images/containers [--keep=N]
+wheels deploy lock <verb>        // acquire/release/status (manual — normal deploys auto-lock)
+wheels deploy secrets <verb>     // fetch/extract/print (adapters: op/bitwarden/aws/lastpass/doppler)
+wheels deploy audit              // tail /tmp/kamal-audit.log on each server
+wheels deploy details            // aggregate app + proxy + accessory status
+wheels deploy remove --confirm   // teardown all app/proxy/accessory containers
+wheels deploy docs [section]     // in-terminal config reference
+```
+
+### On-server parity contract (byte-compatible with Ruby Kamal)
+
+- Container names: `<service>-<role>-<version>`
+- Labels: `service=`, `role=`, `destination=`, `version=`
+- Docker network: `kamal`
+- Lock file: `/tmp/kamal_deploy_lock_<service>`
+- Proxy config: `/home/<user>/.config/kamal-proxy/`
+- Hook env prefix: `KAMAL_*` (never `WHEELS_*` — user hooks migrate unchanged)
+
+A server managed by Ruby Kamal can be taken over by `wheels deploy` without cleanup.
+
+### Architecture
+
+```
+cli/lucli/services/deploy/
+├── cli/*.cfc             DeployMainCli + Deploy<App|Proxy|Accessory|Build|Registry|Server|Prune|Lock|Secrets>Cli
+├── commands/*.cfc        Base + Docker/App/Proxy/Builder/Registry/Auditor/Lock/Hook/Accessory/PruneCommands
+├── config/*.cfc          Config + Role/Env/Builder/Proxy/Registry/Ssh/Accessory/Validator/ConfigLoader
+├── lib/*.cfc             JarLoader/Mustache/Yaml/SshClient/SshPool/FakeSshPool/Output/SecretResolver
+└── secrets/*.cfc         BaseAdapter + OnePassword/Bitwarden/AwsSecrets/LastPass/Doppler adapters
+
+cli/lucli/lib/deploy/*.jar  jmustache, snakeyaml, sshj + BouncyCastle transitives (URLClassLoader-isolated)
+cli/lucli/templates/deploy/ Mustache templates for `wheels deploy init` output
+```
+
+Commands-are-strings invariant: every `*Commands.cfc` method returns a shell-command string; only `*Cli.cfc` and the orchestrator execute them. That's why `--dry-run` is trivial and unit tests run without network.
+
+### Critical gotchas
+
+1. **Kamal-compatible schema, ONE divergence.** ERB in `deploy.yml` is NOT supported. Use the restricted Mustache context `{{env.FOO}}`, `{{destination}}`, `{{hostname}}` instead. Everything else in `config/deploy.yml` is byte-identical to Kamal 2.4.0.
+2. **Hook env prefix is `KAMAL_`, not `WHEELS_`.** This is deliberate — it means Ruby Kamal users' existing `.kamal/hooks/` scripts work unchanged.
+3. **`app live` / `app maintenance` use a marker file** (`/tmp/kamal-maintenance-<svc>`) rather than kamal-proxy native maintenance mode. Phase 2 simplification; Phase 3 follow-up will align with Kamal's proxy-native semantics.
+4. **`wheels deploy remove` is destructive and requires `--confirm`.** Bare `wheels deploy remove` throws without touching anything.
+5. **Lucee reserved scope names in subagent-authored deploy code.** `client`, `session`, `application` — use `ssh`/`sc`, `sess`, `app` instead. Bit us multiple times during the port.
+6. **No `--dry-run` flag in Ruby Kamal 2.8.2.** The `tools/deploy-config-diff.sh` harness compares config-layer output only. Byte-identical command-string parity is aspirational; see `tools/deploy-dry-run-diff.sh` for the plan.
+
+### Testing
+
+`cli/lucli/tests/specs/deploy/` extends `wheels.wheelstest.system.BaseSpec`. Run with:
+
+    bash tools/test-cli-local.sh
+
+Fixtures at `cli/lucli/tests/_fixtures/deploy/configs/` (`minimal.yml`, `full.yml`, `with-accessories.yml`, `invalid/*.yml`). `FakeSshPool.cfc` records every command for offline assertions; no sshd needed for unit tests. `SshClientSpec` + `SshPoolSpec` exercise real SSH via the fixture at `cli/lucli/tests/_fixtures/deploy/sshd/` (brought up by `tools/deploy-sshd-up.sh`).
+
+### Reference docs
+
+- User guides: `docs/src/working-with-wheels/deployment/` (first-deploy, config-reference, accessories, secrets, hooks, migrating-from-kamal)
+- Per-verb CLI reference: `docs/src/command-line-tools/commands/deploy/`
+- Design spec: `docs/superpowers/specs/2026-04-20-wheels-deploy-kamal-port-design.md`
+- Implementation plan: `docs/superpowers/plans/2026-04-20-wheels-deploy-kamal-port.md`
+- Retrospective: `docs/superpowers/plans/2026-04-21-phase1-retrospective.md`
+
 ## Server-Sent Events (SSE) Quick Reference
 
 ```cfm
@@ -875,7 +957,7 @@ The project name is **Wheels** (not "CFWheels"). The rebrand happened at v3.0. A
 
 Or run `wheels mcp setup` to generate `.mcp.json` + `.opencode.json` automatically.
 
-Tools are auto-discovered from `cli/lucli/Module.cfc` public functions, prefixed with the module name (`wheels_generate`, `wheels_migrate`, `wheels_test`, `wheels_reload`, `wheels_seed`, `wheels_analyze`, `wheels_validate`, `wheels_routes`, `wheels_info`, `wheels_destroy`, `wheels_doctor`, `wheels_stats`, `wheels_notes`, `wheels_db`, `wheels_upgrade`, `wheels_create`). CLI-only tools (`mcp`, `d`, `new`, `console`, `start`, `stop`, `browser`) are hidden from MCP `tools/list` via `mcpHiddenTools()`.
+Tools are auto-discovered from `cli/lucli/Module.cfc` public functions, prefixed with the module name (`wheels_generate`, `wheels_migrate`, `wheels_test`, `wheels_reload`, `wheels_seed`, `wheels_analyze`, `wheels_validate`, `wheels_routes`, `wheels_info`, `wheels_destroy`, `wheels_doctor`, `wheels_stats`, `wheels_notes`, `wheels_db`, `wheels_upgrade`, `wheels_create`, `wheels_deploy`). CLI-only tools (`mcp`, `d`, `new`, `console`, `start`, `stop`, `browser`) are hidden from MCP `tools/list` via `mcpHiddenTools()`.
 
 Workflow orchestration (multi-step planning, feature development) is not a framework concern — use your preferred Claude Code plugin (Superpowers, feature-dev, etc.). The framework ships deterministic Wheels operations via MCP; the model orchestrates.