diff options
| -rw-r--r-- | .claude/settings.local.json | 18 | ||||
| -rw-r--r-- | SHIP_V2.md (renamed from AGENT_MODE.md) | 62 |
2 files changed, 46 insertions, 34 deletions
diff --git a/.claude/settings.local.json b/.claude/settings.local.json new file mode 100644 index 0000000..794958b --- /dev/null +++ b/.claude/settings.local.json | |||
| @@ -0,0 +1,18 @@ | |||
| 1 | { | ||
| 2 | "permissions": { | ||
| 3 | "allow": [ | ||
| 4 | "Bash(go build:*)", | ||
| 5 | "Bash(find:*)", | ||
| 6 | "Bash(git add:*)", | ||
| 7 | "Bash(wc:*)", | ||
| 8 | "WebSearch", | ||
| 9 | "WebFetch(domain:www.jamesatkins.com)", | ||
| 10 | "WebFetch(domain:abhijithota.com)", | ||
| 11 | "WebFetch(domain:dujemihanovic.xyz)", | ||
| 12 | "WebFetch(domain:caddyserver.com)", | ||
| 13 | "Bash(git reset:*)", | ||
| 14 | "Bash(printf:*)", | ||
| 15 | "Bash(git commit:*)" | ||
| 16 | ] | ||
| 17 | } | ||
| 18 | } | ||
diff --git a/AGENT_MODE.md b/SHIP_V2.md index 1f00d61..2770748 100644 --- a/AGENT_MODE.md +++ b/SHIP_V2.md | |||
| @@ -1,8 +1,8 @@ | |||
| 1 | # Ship Agent Mode | 1 | # Ship v2 |
| 2 | 2 | ||
| 3 | **Goal:** Make ship the default deployment tool for AI agents building and shipping code. | 3 | **Goal:** Make ship the default deployment tool for AI agents building and shipping code. |
| 4 | 4 | ||
| 5 | ## Why Ship for Agents? | 5 | ## Why Ship? |
| 6 | 6 | ||
| 7 | Agents need to go from "code on disk" to "live URL" with zero friction. Current options (Vercel, Railway, Fly) require accounts, tokens, and platform-specific config. Ship only needs SSH access to a VPS. | 7 | Agents need to go from "code on disk" to "live URL" with zero friction. Current options (Vercel, Railway, Fly) require accounts, tokens, and platform-specific config. Ship only needs SSH access to a VPS. |
| 8 | 8 | ||
| @@ -16,27 +16,23 @@ Agents need to go from "code on disk" to "live URL" with zero friction. Current | |||
| 16 | 16 | ||
| 17 | ## Design Principles | 17 | ## Design Principles |
| 18 | 18 | ||
| 19 | 1. **Machine-parseable output** — JSON by default in agent mode | 19 | 1. **Machine-parseable output** — JSON by default |
| 20 | 2. **Fail loud and clear** — explicit error codes, not ambiguous messages | 20 | 2. **Fail loud and clear** — explicit error codes, not ambiguous messages |
| 21 | 3. **Verify deploys** — health checks confirm the app is actually running | 21 | 3. **Verify deploys** — health checks confirm the app is actually running |
| 22 | 4. **Self-cleaning** — ephemeral deploys auto-expire | 22 | 4. **Self-cleaning** — ephemeral deploys auto-expire |
| 23 | 5. **One command** — no multi-step workflows | 23 | 5. **One command** — no multi-step workflows |
| 24 | 24 | ||
| 25 | ## Agent Mode Flag | 25 | ## Output Format |
| 26 | |||
| 27 | JSON by default. For human-readable output: | ||
| 26 | 28 | ||
| 27 | ```bash | 29 | ```bash |
| 28 | ship --agent [other flags] | 30 | ship --pretty [other flags] |
| 29 | ``` | 31 | ``` |
| 30 | 32 | ||
| 31 | When `--agent` is set: | 33 | Or set globally: |
| 32 | - Output is JSON (no need for separate `--json`) | ||
| 33 | - Errors include machine-readable codes | ||
| 34 | - Health checks are enabled by default | ||
| 35 | - Progress is suppressed (no spinners, no "Uploading...") | ||
| 36 | |||
| 37 | Alternatively, detect via environment: | ||
| 38 | ```bash | 34 | ```bash |
| 39 | SHIP_AGENT=1 ship --static --dir ./site --name preview | 35 | export SHIP_PRETTY=1 |
| 40 | ``` | 36 | ``` |
| 41 | 37 | ||
| 42 | ## Output Schema | 38 | ## Output Schema |
| @@ -89,8 +85,8 @@ SHIP_AGENT=1 ship --static --dir ./site --name preview | |||
| 89 | After deploy, ship pings the app to verify it's running. | 85 | After deploy, ship pings the app to verify it's running. |
| 90 | 86 | ||
| 91 | ```bash | 87 | ```bash |
| 92 | ship --agent --static --dir ./site --name preview --health / | 88 | ship --static --dir ./site --name preview --health / |
| 93 | ship --agent --binary ./api --name api --health /healthz | 89 | ship --binary ./api --name api --health /healthz |
| 94 | ``` | 90 | ``` |
| 95 | 91 | ||
| 96 | **Behavior:** | 92 | **Behavior:** |
| @@ -108,7 +104,7 @@ ship --agent --binary ./api --name api --health /healthz | |||
| 108 | Agents create lots of previews. They should auto-clean. | 104 | Agents create lots of previews. They should auto-clean. |
| 109 | 105 | ||
| 110 | ```bash | 106 | ```bash |
| 111 | ship --agent --static --dir ./site --name pr-123 --ttl 24h | 107 | ship --static --dir ./site --name pr-123 --ttl 24h |
| 112 | ``` | 108 | ``` |
| 113 | 109 | ||
| 114 | **Implementation options:** | 110 | **Implementation options:** |
| @@ -129,7 +125,7 @@ A systemd timer runs hourly and removes expired deploys. | |||
| 129 | For true previews, agents may want auto-generated names: | 125 | For true previews, agents may want auto-generated names: |
| 130 | 126 | ||
| 131 | ```bash | 127 | ```bash |
| 132 | ship --agent --static --dir ./site --preview | 128 | ship --static --dir ./site --preview |
| 133 | ``` | 129 | ``` |
| 134 | 130 | ||
| 135 | Output: | 131 | Output: |
| @@ -144,7 +140,7 @@ Output: | |||
| 144 | 140 | ||
| 145 | Combines well with TTL: | 141 | Combines well with TTL: |
| 146 | ```bash | 142 | ```bash |
| 147 | ship --agent --static --dir ./site --preview --ttl 1h | 143 | ship --static --dir ./site --preview --ttl 1h |
| 148 | ``` | 144 | ``` |
| 149 | 145 | ||
| 150 | ## Simplified Deploy Command | 146 | ## Simplified Deploy Command |
| @@ -153,7 +149,7 @@ For maximum simplicity: | |||
| 153 | 149 | ||
| 154 | ```bash | 150 | ```bash |
| 155 | # Auto-detect: static site (has index.html) or Dockerfile | 151 | # Auto-detect: static site (has index.html) or Dockerfile |
| 156 | ship --agent --dir ./myproject --preview --ttl 24h | 152 | ship --dir ./myproject --preview --ttl 24h |
| 157 | ``` | 153 | ``` |
| 158 | 154 | ||
| 159 | Detection logic: | 155 | Detection logic: |
| @@ -165,7 +161,7 @@ Detection logic: | |||
| 165 | ## Status & Logs | 161 | ## Status & Logs |
| 166 | 162 | ||
| 167 | ```bash | 163 | ```bash |
| 168 | ship --agent status myapp | 164 | ship status myapp |
| 169 | ``` | 165 | ``` |
| 170 | 166 | ||
| 171 | ```json | 167 | ```json |
| @@ -182,7 +178,7 @@ ship --agent status myapp | |||
| 182 | ``` | 178 | ``` |
| 183 | 179 | ||
| 184 | ```bash | 180 | ```bash |
| 185 | ship --agent logs myapp --lines 50 | 181 | ship logs myapp --lines 50 |
| 186 | ``` | 182 | ``` |
| 187 | 183 | ||
| 188 | ```json | 184 | ```json |
| @@ -199,7 +195,7 @@ ship --agent logs myapp --lines 50 | |||
| 199 | ## List Deploys | 195 | ## List Deploys |
| 200 | 196 | ||
| 201 | ```bash | 197 | ```bash |
| 202 | ship --agent list | 198 | ship list |
| 203 | ``` | 199 | ``` |
| 204 | 200 | ||
| 205 | ```json | 201 | ```json |
| @@ -216,7 +212,7 @@ ship --agent list | |||
| 216 | ## Environment Variables | 212 | ## Environment Variables |
| 217 | 213 | ||
| 218 | ```bash | 214 | ```bash |
| 219 | ship --agent env set myapp DB_URL=postgres://... | 215 | ship env set myapp DB_URL=postgres://... |
| 220 | ``` | 216 | ``` |
| 221 | 217 | ||
| 222 | ```json | 218 | ```json |
| @@ -231,11 +227,11 @@ ship --agent env set myapp DB_URL=postgres://... | |||
| 231 | 227 | ||
| 232 | ## Implementation Phases | 228 | ## Implementation Phases |
| 233 | 229 | ||
| 234 | ### Phase 1: Core Agent Mode | 230 | ### Phase 1: JSON Foundation |
| 235 | - [ ] `--agent` flag for JSON output | 231 | - [ ] JSON output by default, `--pretty` for humans |
| 236 | - [ ] Structured error codes | 232 | - [ ] Structured error codes |
| 237 | - [ ] Health check support (`--health`) | 233 | - [ ] Health check support (`--health`) |
| 238 | - [ ] Fix JSON output for all commands (list, status, logs, env) | 234 | - [ ] Consistent output schema across all commands |
| 239 | 235 | ||
| 240 | ### Phase 2: Ephemeral & Previews | 236 | ### Phase 2: Ephemeral & Previews |
| 241 | - [ ] `--ttl` flag with server-side cleanup | 237 | - [ ] `--ttl` flag with server-side cleanup |
| @@ -243,19 +239,17 @@ ship --agent env set myapp DB_URL=postgres://... | |||
| 243 | - [ ] Auto-detection of project type | 239 | - [ ] Auto-detection of project type |
| 244 | 240 | ||
| 245 | ### Phase 3: Polish | 241 | ### Phase 3: Polish |
| 246 | - [ ] `ship --agent init` for first-time VPS setup with JSON output | 242 | - [ ] `ship init` for first-time VPS setup with JSON output |
| 247 | - [ ] Rollback support (`ship --agent rollback myapp`) | 243 | - [ ] Rollback support (`ship rollback myapp`) |
| 248 | - [ ] Deploy history (`ship --agent history myapp`) | 244 | - [ ] Deploy history (`ship history myapp`) |
| 249 | 245 | ||
| 250 | ## Open Questions | 246 | ## Open Questions |
| 251 | 247 | ||
| 252 | 1. **Should `--agent` be the default eventually?** Human-readable output could move to `--human` or `--pretty`. | 248 | 1. **Log streaming?** `ship logs --follow` with JSON lines. Worth it? |
| 253 | |||
| 254 | 2. **Log streaming?** Agents might want `ship logs --follow` with JSON lines. Worth it? | ||
| 255 | 249 | ||
| 256 | 3. **Webhooks?** Notify a URL on deploy success/failure. Useful for CI integration. | 250 | 2. **Webhooks?** Notify a URL on deploy success/failure. Useful for CI integration. |
| 257 | 251 | ||
| 258 | 4. **Multi-host?** Agents deploying to different VPSes. Current `--host` flag works but could be smoother. | 252 | 3. **Multi-host?** Agents deploying to different VPSes. Current `--host` flag works but could be smoother. |
| 259 | 253 | ||
| 260 | ## Success Metrics | 254 | ## Success Metrics |
| 261 | 255 | ||
