Step 8 — crate:install provisioning command + Laravel Cloud deploy guide

[edgrosvenor]

Step 8 — crate:install provisioning command + Laravel Cloud deploy guide

The final build step: a first-run installer that configures a deployed Crate, plus a deploy guide so an operator can fork → deploy → run.

What shipped (vs the plan)

• crate:install (app/Console/Commands/CrateInstallCommand.php) — app-level command using built-for-cloud's WritesInstallEnv trait. Interactive (prompts, defaulting to the current value) and flag/--no-interaction driven (--url, --archive-disk, --satis-path, --credential-api, --force, --path). It writes only the four Crate app keys — CRATE_URL, CRATE_ARCHIVE_DISK, CRATE_SATIS_PATH, BUILT_FOR_CLOUD_CREDENTIAL_API_ENABLED — and never the Cloud-injected resource env (DB_*/QUEUE_*/CACHE_*/FILESYSTEM_DISK). Idempotent (a second identical run reports "already configured; no changes"); never clobbers an existing non-empty value without interactive confirmation or --force.
• docs/deploy.md — a Laravel Cloud deploy guide (linked from the README) covering: resource provisioning with the cardinal rule stated explicitly (never hand-set Cloud-injected DB/QUEUE/CACHE/FILESYSTEM env); the build-command step that installs the isolated Satis tool (composer create-project composer/satis "$CRATE_SATIS_PATH" --no-dev, never composer required in); and the first-run flow (crate:install → migrate --force → token:create ci --abilities=admin → crate:repos:add → crate:build → consumer crate:auth → composer require through the gate). Every command/flag cross-checks against the shipped code.
• 8 install tests / 41 assertions (Testbench, temp .env, no real Cloud).

Deserves attention

• Resource-env safety is the load-bearing property and is proven by tests: crate:install writes only the four keys, and a test asserts a populated .env's DB_CONNECTION/QUEUE_CONNECTION/CACHE_STORE/FILESYSTEM_DISK/APP_KEY are left untouched.

Findings disposition

• Independent quality reviewer: no blocking findings ("Ship it") — it verified the four-keys-only invariant, idempotency, the clobber guard, and every documented command/flag/route against source. Two advisories were applied (commit 5be961d): (1) crate:install's env-value un-escaping now uses a single left-to-right pass, so a backslash-bearing value (e.g. a Windows Satis path) round-trips correctly and stays idempotent instead of tripping the clobber guard on re-run — plus a new env-preservation test and a backslash round-trip test; and (1b) docs/deploy.md now notes that a bare non-interactive crate:install makes no changes (pass the flags for automated deploys). One advisory deferred and flagged for you: the committed IDE-helper metadata (.phpstorm.meta.php) bakes a worktree-absolute path — a pre-existing repo-wide hygiene item affecting every PR, not introduced by step 8; worth gitignoring the regenerated IDE helpers in a separate cleanup.
• Independent acceptance judge: ACCEPT — all criteria pass on self-observed runs.

Gate evidence (verified by the coordinator on committed SHA 0d2134b; the later change 5be961d adds only the round-trip fix + tests + a deploy.md note)

• composer ready → exit 0 (pint passed, phpstan errors:0, pest 43/130, composer audit: no advisories); tree clean.
• composer packages:check → exit 0; all packages green.

Risk / next

• Completes the planned build (steps 1–8). Crate is now fork-and-deployable: gated Satis registry, credential API + issuer SDK/consumer helper, provisioning installer, and accurate docs.
• Left for you (unchanged hard stop): no v* release tag was pushed — tagging + the kibble split to the mirror repos is Ed-authorized. The IDE-helper-hygiene cleanup above is optional.

🤖 Generated with Claude Code