diff options
Diffstat (limited to 'SHIP_V2.md')
| -rw-r--r-- | SHIP_V2.md | 240 |
1 files changed, 0 insertions, 240 deletions
diff --git a/SHIP_V2.md b/SHIP_V2.md deleted file mode 100644 index 7b607cb..0000000 --- a/SHIP_V2.md +++ /dev/null | |||
| @@ -1,240 +0,0 @@ | |||
| 1 | # Ship v2 | ||
| 2 | |||
| 3 | **Ship is a deployment tool built for AI agents.** | ||
| 4 | |||
| 5 | Agents write code. Ship puts it on the internet. That's it. | ||
| 6 | |||
| 7 | ## The Problem | ||
| 8 | |||
| 9 | AI agents can write code, but deploying it is a mess: | ||
| 10 | - Vercel/Railway/Fly require accounts, API tokens, platform-specific config | ||
| 11 | - Docker/K8s are overkill for "make this code accessible via URL" | ||
| 12 | - Most tools assume a human is reading the output | ||
| 13 | |||
| 14 | Agents need: code → URL. Nothing else. | ||
| 15 | |||
| 16 | ## Ship's Approach | ||
| 17 | |||
| 18 | ```bash | ||
| 19 | ship ./myproject | ||
| 20 | # {"status":"ok","url":"https://abc123.example.com","took_ms":4200} | ||
| 21 | ``` | ||
| 22 | |||
| 23 | **That's the entire interface.** Point ship at code, get a URL back as JSON. | ||
| 24 | |||
| 25 | ### Core Principles | ||
| 26 | |||
| 27 | 1. **JSON in, JSON out** — No human-formatted output. No spinners. No emoji. Agents parse JSON. | ||
| 28 | |||
| 29 | 2. **One command** — No workflows. No "init then configure then deploy." One command does everything. | ||
| 30 | |||
| 31 | 3. **Verify or fail** — Every deploy is health-checked. If the app isn't responding, ship returns an error. No silent failures. | ||
| 32 | |||
| 33 | 4. **Self-cleaning** — Deploys can auto-expire. Agents create lots of previews; they shouldn't pile up forever. | ||
| 34 | |||
| 35 | 5. **Zero config** — Point at a directory. Ship figures out if it's static, Docker, or a binary. No config files required. | ||
| 36 | |||
| 37 | 6. **SSH-only** — No accounts. No API tokens. No vendor lock-in. Just SSH access to a VPS. | ||
| 38 | |||
| 39 | ## Interface | ||
| 40 | |||
| 41 | ### Deploy | ||
| 42 | |||
| 43 | ```bash | ||
| 44 | ship ./myproject | ||
| 45 | ship ./myproject --name myapp | ||
| 46 | ship ./myproject --name preview --ttl 24h | ||
| 47 | ship ./site --static | ||
| 48 | ship ./api --health /healthz | ||
| 49 | ``` | ||
| 50 | |||
| 51 | Output: | ||
| 52 | ```json | ||
| 53 | { | ||
| 54 | "status": "ok", | ||
| 55 | "name": "myapp", | ||
| 56 | "url": "https://myapp.example.com", | ||
| 57 | "type": "docker", | ||
| 58 | "took_ms": 4200, | ||
| 59 | "health": {"status": 200, "latency_ms": 45} | ||
| 60 | } | ||
| 61 | ``` | ||
| 62 | |||
| 63 | ### Error | ||
| 64 | |||
| 65 | ```json | ||
| 66 | { | ||
| 67 | "status": "error", | ||
| 68 | "code": "HEALTH_CHECK_FAILED", | ||
| 69 | "message": "GET /healthz returned 503 after 30s", | ||
| 70 | "name": "myapp", | ||
| 71 | "url": "https://myapp.example.com" | ||
| 72 | } | ||
| 73 | ``` | ||
| 74 | |||
| 75 | ### List | ||
| 76 | |||
| 77 | ```bash | ||
| 78 | ship list | ||
| 79 | ``` | ||
| 80 | |||
| 81 | ```json | ||
| 82 | { | ||
| 83 | "status": "ok", | ||
| 84 | "deploys": [ | ||
| 85 | {"name": "api", "url": "https://api.example.com", "type": "docker", "running": true}, | ||
| 86 | {"name": "preview-x7k", "url": "https://preview-x7k.example.com", "type": "static", "expires": "2024-02-16T18:00:00Z"} | ||
| 87 | ] | ||
| 88 | } | ||
| 89 | ``` | ||
| 90 | |||
| 91 | ### Status / Logs / Remove | ||
| 92 | |||
| 93 | ```bash | ||
| 94 | ship status myapp | ||
| 95 | ship logs myapp | ||
| 96 | ship logs myapp --lines 100 | ||
| 97 | ship remove myapp | ||
| 98 | ``` | ||
| 99 | |||
| 100 | All return JSON with `{"status": "ok", ...}` or `{"status": "error", "code": "...", ...}`. | ||
| 101 | |||
| 102 | ## Error Codes | ||
| 103 | |||
| 104 | Machine-readable. No guessing. | ||
| 105 | |||
| 106 | | Code | Meaning | | ||
| 107 | |------|---------| | ||
| 108 | | `SSH_FAILED` | Can't connect to VPS | | ||
| 109 | | `UPLOAD_FAILED` | File transfer failed | | ||
| 110 | | `BUILD_FAILED` | Docker build or compile failed | | ||
| 111 | | `DEPLOY_FAILED` | systemd/Caddy setup failed | | ||
| 112 | | `HEALTH_CHECK_FAILED` | App not responding | | ||
| 113 | | `NOT_FOUND` | App doesn't exist | | ||
| 114 | | `CONFLICT` | Name already taken | | ||
| 115 | |||
| 116 | ## Auto-Detection | ||
| 117 | |||
| 118 | Ship looks at the directory and figures out what to do: | ||
| 119 | |||
| 120 | | Directory contains | Deploy type | | ||
| 121 | |-------------------|-------------| | ||
| 122 | | `Dockerfile` | Docker build → systemd service | | ||
| 123 | | `index.html` | Static site → Caddy file_server | | ||
| 124 | | Single executable | Binary → systemd service | | ||
| 125 | | `go.mod` | Go build → systemd service | | ||
| 126 | | `package.json` + no Dockerfile | Error: "Add a Dockerfile" | | ||
| 127 | |||
| 128 | No config files. No `ship.json`. No `ship init`. | ||
| 129 | |||
| 130 | ## TTL (Time-To-Live) | ||
| 131 | |||
| 132 | Agents create previews. Previews should auto-delete. | ||
| 133 | |||
| 134 | ```bash | ||
| 135 | ship ./site --name pr-123 --ttl 1h | ||
| 136 | ship ./site --name pr-123 --ttl 7d | ||
| 137 | ``` | ||
| 138 | |||
| 139 | After TTL expires, the deploy is removed automatically. The `expires` field in JSON tells you when. | ||
| 140 | |||
| 141 | ## Health Checks | ||
| 142 | |||
| 143 | Every deploy is verified. Ship waits for the app to respond before returning success. | ||
| 144 | |||
| 145 | - Static sites: `GET /` returns 2xx | ||
| 146 | - Apps: `GET /` by default, or specify `--health /healthz` | ||
| 147 | - Timeout: 30s | ||
| 148 | - If health check fails: `{"status": "error", "code": "HEALTH_CHECK_FAILED", ...}` | ||
| 149 | |||
| 150 | ## Name Generation | ||
| 151 | |||
| 152 | No name? Ship generates one. | ||
| 153 | |||
| 154 | ```bash | ||
| 155 | ship ./site | ||
| 156 | # {"name": "ship-a1b2c3", "url": "https://ship-a1b2c3.example.com", ...} | ||
| 157 | ``` | ||
| 158 | |||
| 159 | Provide a name to get a stable URL: | ||
| 160 | |||
| 161 | ```bash | ||
| 162 | ship ./site --name docs | ||
| 163 | # {"name": "docs", "url": "https://docs.example.com", ...} | ||
| 164 | ``` | ||
| 165 | |||
| 166 | ## Host Setup | ||
| 167 | |||
| 168 | One-time setup for a VPS: | ||
| 169 | |||
| 170 | ```bash | ||
| 171 | ship host init user@my-vps.com --domain example.com | ||
| 172 | ``` | ||
| 173 | |||
| 174 | ```json | ||
| 175 | { | ||
| 176 | "status": "ok", | ||
| 177 | "host": "my-vps.com", | ||
| 178 | "domain": "example.com", | ||
| 179 | "installed": ["caddy", "docker", "systemd"] | ||
| 180 | } | ||
| 181 | ``` | ||
| 182 | |||
| 183 | After this, the host is ready. Ship remembers it. | ||
| 184 | |||
| 185 | ## Human Output | ||
| 186 | |||
| 187 | Humans are an afterthought, but they can use ship too: | ||
| 188 | |||
| 189 | ```bash | ||
| 190 | ship ./site --pretty | ||
| 191 | ``` | ||
| 192 | |||
| 193 | ``` | ||
| 194 | ✓ Deployed to https://ship-a1b2c3.example.com (4.2s) | ||
| 195 | ``` | ||
| 196 | |||
| 197 | Or set globally: | ||
| 198 | ```bash | ||
| 199 | export SHIP_PRETTY=1 | ||
| 200 | ``` | ||
| 201 | |||
| 202 | ## Implementation Phases | ||
| 203 | |||
| 204 | ### Phase 1: JSON Everything | ||
| 205 | - [ ] JSON output on all commands | ||
| 206 | - [ ] Structured error codes | ||
| 207 | - [ ] Exit codes match error states | ||
| 208 | |||
| 209 | ### Phase 2: Smart Deploys | ||
| 210 | - [ ] Auto-detect project type | ||
| 211 | - [ ] Health checks on every deploy | ||
| 212 | - [ ] `--ttl` with server-side cleanup | ||
| 213 | |||
| 214 | ### Phase 3: Zero Friction | ||
| 215 | - [ ] `ship ./dir` with no flags (auto name, auto detect) | ||
| 216 | - [ ] `ship host init` fully automated | ||
| 217 | - [ ] One binary, zero dependencies on client | ||
| 218 | |||
| 219 | ## Non-Goals | ||
| 220 | |||
| 221 | - **Pretty output** — That's what `--pretty` is for | ||
| 222 | - **Interactive prompts** — Never. Agents can't answer prompts. | ||
| 223 | - **Config files** — Zero config. Detect everything. | ||
| 224 | - **Plugin system** — Keep it simple. | ||
| 225 | - **Multi-cloud orchestration** — One VPS at a time. | ||
| 226 | |||
| 227 | ## Success Criteria | ||
| 228 | |||
| 229 | Ship is done when an agent can: | ||
| 230 | |||
| 231 | 1. Build code | ||
| 232 | 2. Run `ship ./code` | ||
| 233 | 3. Parse the JSON response | ||
| 234 | 4. Use the URL | ||
| 235 | |||
| 236 | No docs. No setup. No tokens. No accounts. Just `ship ./code`. | ||
| 237 | |||
| 238 | --- | ||
| 239 | |||
| 240 | *Built for agents. Tolerated by humans.* | ||
