/wbDeploy — Exhaustive Simulation ()
/wbDeploy is the shipper of apps, not packages. Apps are the things end users hit — domain names, build artifacts uploaded to a host, environment variables on a cloud provider. /wbPublish handles npm packages; /wbDeploy handles deployments to Vercel/Cloudflare/AWS/whatever the target is. The two commands stay separate because the failure modes are different.
Read this if you want to know what --prod actually changes vs --target, why --dry-run is the safest default for first-time use, and where deploy ends and release coordination (/wbRelease) begins.
1. Role & target
| Aspect | Behavior |
|---|---|
| Role | The Shipper — pushes apps to hosting environments. |
| Target | An app directory (e.g., apps/wbc-ui.com), comma-separated set, glob, or environment shorthand (staging, production). |
| Cell scope | None directly. Plan rows about deployment exist; /wbDeploy doesn't mutate them. |
| Side effects allowed | Building the app; uploading artifacts; setting environment variables on the cloud provider; updating DNS aliases (with confirmation). |
| Side effects forbidden | Modifying source code; mutating git state (no commits, no tags — that's /wbRelease's job); running migrations against shared databases without explicit confirmation; modifying deploys outside the target list. |
The "no source modifications" rule is the contract with /wbRelease. /wbDeploy ships what's already in the working tree. If the working tree is dirty, the agent warns; if a version bump is needed, that's /wbRelease's job, not /wbDeploy's.
2. Argument resolution matrix
| Form | Example | What /wbDeploy does |
|---|---|---|
| App directory | Command: /wbDeploy apps/wbc-ui.com | Deploys one app. |
| Comma-separated | Command: /wbDeploy apps/wbc-ui.com,apps/admin | Deploys both, parallel where the host supports it. |
| Glob | Command: /wbDeploy "apps/*" | Deploys every app. Slow; warns about scope. |
| Environment shorthand | Command: /wbDeploy production | Refused. Environment must be a flag (--prod/-P), not a target. |
| Free-text | Command: /wbDeploy "the main site" | Refused. |
The "environment as flag, not target" distinction exists because conflating them produces ambiguity: /wbDeploy production could mean "deploy to production" or "deploy the app named production." Forcing the flag form removes the ambiguity.
3. Flag matrix
| Flag | Shortcut | Purpose |
|---|---|---|
--target="<env>" | -t | Names the deployment target environment: preview (default), staging, or any custom env declared in the host config. |
--prod | -P | Shorthand for --target="production" with extra confirmation gates. Capitalized to signal high-stakes. |
--dry-run | -d | Builds the app and validates the deploy steps but does not actually upload. Reports what would happen. |
How --target and --prod interact
| Combination | Behavior |
|---|---|
| no flag | Deploys to preview. Produces a unique preview URL. Safe by default. |
--target="staging" | Deploys to staging. One confirmation. |
--target="production" | Deploys to production. Two confirmations + dry-run encouraged. |
--prod | Equivalent to --target="production" but the flag itself is loud — anyone reading the command sees "production." |
--target="custom-env" | Honors the custom env if declared in host config. Fails honestly if not. |
The confirmation count scales with risk: preview = none, staging = 1, production = 2. Production deploys are the irreversible ones — once traffic routes to a new build, rollback is another deploy, not an undo.
How --dry-run validates
| Step | Live | Dry-run |
|---|---|---|
| Build | Runs build command. | Runs build command. |
| Validate config | Checks env vars, host credentials. | Checks env vars, host credentials. |
| Upload | Actually uploads. | Skipped; logs what would upload (file list, size). |
| Switch traffic | Updates DNS/aliases. | Skipped; logs what would switch. |
| Notify | Sends release notes if configured. | Skipped. |
The build runs on dry-run because build failures are the most common deploy blocker. Catching them in --dry-run is the point.
4. Pipelines (the agent-native scenarios)
/wbDeploy apps/wbc-ui.com> /wbDeploy apps/wbc-ui.com💠 Pipeline The first preview deploy of a new app
💠 Pipeline The production deploy with double-gate
💠 Pipeline The dry-run before production
The recommended pattern for production deploys:
💠 Pipeline Multi-app deploy
5. Edge cases & refusals
| Trigger | What /wbDeploy does |
|---|---|
| No target | Halt. |
| Free-text target | Halt. |
| Working tree dirty (uncommitted changes) | Warn prominently; ask confirmation. The deploy will reflect uncommitted state if proceed. |
--prod on a commit that isn't on main | Refuse. Production deploys must be from a known-good branch. |
| Missing host credentials | Halt with explicit setup instructions. |
--target="<unknown>" | Halt. Lists known environments. |
--prod --dry-run | Permitted; safest combination for "preview the production behavior." |
| Build fails | Halt; no upload. |
| Upload fails partway | Reports clearly which app/env succeeded and which didn't. |
| Multi-app deploy with one build failure | Refuse all uploads. Atomic-by-build. |
| Free-text "rollback" | Refuse — rollback isn't an undo, it's a deploy. Suggests the explicit re-deploy of the previous artifact. |
Post-deploy symptoms (GitHub Pages)
These land after the command reports success, which is why the practical layer insists you open the URL yourself — no gate catches any of them.
| Symptom | Likely cause | Fix |
|---|---|---|
| Page blank, assets 404 | vite base ≠ deploy base-url | Match them, including both slashes |
| Refresh on a deep link → 404 | spa-fallback not set | Set spa-fallback: true, redeploy |
| "Page not found" at the root | gh-pages branch empty | Check Settings → Pages → Source |
| CSS loads but JS doesn't | type="module" served with the wrong MIME | GitHub Pages quirk; usually self-resolves after a rebuild |
| Push succeeded but old content shows | GitHub Pages cache | Wait 5–10 min, then hard refresh |
| CNAME disappears every deploy | generate-cname: false with no manual file | Either auto-generate or commit the CNAME |
The pattern: /wbDeploy is the irreversible operation in the QA chain. Multiple gates, dry-run encouraged, --prod is loud, atomic-by-build for multi-app deploys, and rollback is another deploy (not undo). It refuses to deploy from dirty trees without explicit acknowledgment, refuses to deploy to unknown environments, refuses to partially deploy when builds fail. The boundary with /wbRelease (version bumps, git tags) and /wbPublish (npm) is hard: deploy ships apps; release coordinates versions; publish ships packages.