Dual-runtime deploy workflow

Summary

The deploy helper now supports --runtime docker and --runtime native, keeps Docker as the default, and adds --web-only, --api-only, --services-only, and --no-build. Documentation now clearly separates fast local development from VPS rollout options.

Changes Made

• Refactored scripts/deploy.ts into shared git/publish logic plus runtime-specific precheck, rollout, and verification paths.
• Fixed the repo-root deploy wrapper to forward flags such as --runtime native through Bun correctly.
• Removed Docker verification’s dependence on hardcoded container names and switched to docker compose exec.
• Added native deployment support that assumes Bun plus systemd-managed units on the VPS.
• Added a new operator guide at deployment/native/README.md.
• Updated README.md to emphasize the preferred fast local loop: Docker infra only, native Bun services, native web dev.
• Updated deployment/docker/README.md to document Docker as the default runtime and show new partial rollout examples.

Context

The repo already separated local infra from application processes: the root docker-compose.yml is infra-only, while services and the web app run through Bun scripts. The old deploy helper still assumed every server rollout was Docker-only. This change makes the deploy workflow match the new operating model: fast native iteration locally, Docker still available in production, and a native VPS path available during transition.

Important Implementation Details

• Docker remains the default runtime, so ./deploy main still works without extra flags.
• Native rollouts are invoked with ./deploy main --runtime native or ./deploy current-branch --runtime native.
• Partial scopes are mutually exclusive and intentionally simple:

./deploy main --runtime docker --web-only
./deploy main --runtime native --api-only
./deploy current-branch --runtime docker --services-only
./deploy main --runtime native --web-only --no-build

• Docker workspace snapshot validation now runs only when a Docker rollout will build images.
• Native rollouts assume systemd unit names like islandflow-web and islandflow-api, but those names can be overridden with environment variables such as DEPLOY_NATIVE_WEB_UNIT.
• The native path also allows overriding the systemctl wrapper via DEPLOY_NATIVE_SYSTEMCTL_PREFIX, which is useful for systemctl --user setups.

Validation

• Passed: ./deploy --help
• Passed: bun run scripts/deploy.ts --help
• Passed: bun run check:docker-workspace
• Passed: invalid-flag guard for --runtime native --force-recreate
• Passed: conflicting-scope guard for --web-only --api-only

bun run scripts/deploy.ts --help
bun run check:docker-workspace
bun run scripts/deploy.ts main --runtime native --force-recreate
bun run scripts/deploy.ts main --web-only --api-only

Issues, Limitations, and Mitigations

• Native deploys assume server-side systemd units already exist. Mitigation: added deployment/native/README.md documenting expected unit names and override variables.
• Rollback is still manual. Mitigation: both Docker and native docs now frame runtime selection as a transition path, with Docker preserved as a fallback.
• No native service unit files were added in this change. This keeps the scope focused on the deploy workflow itself.
• Public verification still centers on the hosted app URL. API verification remains local-to-runtime unless DEPLOY_PUBLIC_API_HEALTH_URL is configured.

Follow-up Work

• Implementation tracked in islandflow-qh7 is complete for the deploy helper itself.
• Open follow-up: islandflow-38p, add checked-in native deployment unit templates and rollback helpers.