@hyze-cloud/cli 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hyze Cloud
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,575 @@
+# Hyze Cloud CLI
+
+`hyze` is the command-line client for the Hyze Cloud public API. It covers the
+deploy loop end to end: log in, list projects, deploy, watch the build, read the
+logs and check what is running — without leaving the terminal.
+
+- **Seven commands, no API mirror.** Each one answers a question a person or a
+  script actually asks.
+- **An interactive screen for the bare `hyze`**: the project list, one project's
+  facts and the actions you run on it — deploy, restart, start/stop with a
+  confirmation, open in the browser — plus a deploy's live progress and the
+  project's logs, with the keys taught on screen. `hyze --help` still prints help.
+- Three runtime dependencies: `commander`, plus `ink` and `react` for that
+  screen; runs on **Node 18+** and **Bun**
+- **Machine-readable output**: `--json` pipes the API response untouched, and a
+  pipe (no TTY) defaults to JSON, so `hyze projects --json | jq` is safe
+- **Human errors**: one line, the fix, and a stable exit code — never a stack trace
+- ZIP builds from a directory, honoring `.hyzeignore`, `git ls-files` or built-in ignores
+
+## Install
+
+```bash
+npm install -g @hyze-cloud/cli    # or: bun add -g @hyze-cloud/cli
+hyze --version
+```
+
+Standalone binary (no Node needed; on macOS the script ad-hoc signs the output):
+
+```bash
+bun run build:compile             # produces dist/hyze
+sudo mv dist/hyze /usr/local/bin/hyze
+```
+
+## Quickstart
+
+```bash
+hyze login                        # paste a key created in the dashboard (Settings → Developer)
+hyze projects                     # what exists in this workspace
+hyze deploy . --name my-api --runtime bun --port 3000 --subdomain my-api.hyzecloud.app
+hyze status my-api                # is it up? unknown when the platform cannot see the container
+hyze deployments my-api           # build history: queue place, waiting reason, cause of death
+hyze logs my-api                  # container output; `hyze logs my-api <deploymentId>` for the build log
+```
+
+## Commands
+
+| Command | Talks to | What it does |
+| --- | --- | --- |
+| `login [--key <key>] [--no-verify]` | `GET /apps/`, `GET /plans/current` | store an API key, after checking it against the API |
+| `logout` | — | remove the stored key of the active profile |
+| `projects [--query] [--page] [--limit]` | `GET /apps/` | list the workspace's projects |
+| `deploy [path] [--name] [--app] [--repo] …` | `GET /platform/config`, `POST /apps/inspect-env`, `POST /apps/deploy`, `GET /apps/:appId/deployments/:id` | zip (or send a `.zip`), upload, follow the build |
+| `deployments [appId] [deploymentId]` | `GET /apps/:appId/deployments[/:id]` | build history, or one deployment with its stage timeline |
+| `logs [appId] [deploymentId]` | `GET /apps/:appId/logs`, `GET /apps/:appId/deployments/:id` | container output, or the persisted build log |
+| `status [appId]` | `GET /apps/:appId` | the project's current state |
+
+`appId` is optional wherever a project is the subject: `.hyzerc.json` binds one
+to the directory, so inside a project `hyze status`, `hyze logs` and
+`hyze deploy .` need no arguments.
+
+```json
+// .hyzerc.json — nearest ancestor wins
+{ "appId": "app_abc123", "workspaceId": "org_abc", "apiUrl": "https://api.hyzecloud.com/api" }
+```
+
+## Interactive screen
+
+In a terminal, `hyze` with no arguments opens a small screen instead of printing
+help (`hyze --help` still prints help). It reads the same API through the same
+client as the commands above:
+
+```
+Projects                                                       4 projects
+
+> ● Running    shop-api                shop-api.hyzecloud.app
+  ○ Stopped    docs                    docs.hyzecloud.app
+  ◐ Deploying  worker                  worker.hyzecloud.app
+  ✕ Error      billing                 billing.hyzecloud.app
+
+↑↓ Navigate · Enter Open · / Search · ? Help · q Quit
+```
+
+`Enter` opens the highlighted project — its state, its URL when it last shipped,
+the hostnames it answers on, the variables it runs with — and everything you do
+to it from here: deploy it, restart it, start or stop it, open it in the browser,
+read its builds, set a variable, add a domain:
+
+```
+Projects › shop-api
+
+● Running
+
+URL           https://shop-api.hyzecloud.app
+Last deploy   Success · 3h ago
+
+Domains
+  shop.example.com  Active · certificate active
+CNAME         apps.hyzecloud.app
+
+Environment
+  API_KEY     hyze_abcd…wxyz
+  DATABASE_URL  postgre…hop
+
+d Deploy · r Restart · s Stop · b Builds · o Open in the browser · l Logs
+e Set a variable · a Add a domain · v Show the values · Esc Back · ? Help · q Quit
+```
+
+The variables are masked — recognisable, not usable — and `v` shows them in
+full and hides them again; a variable with no value keeps its name and gets no
+value. `e` sets one, spelled `KEY=value` the way `-e` is spelled everywhere
+else, and it asks before it writes because the app restarts to apply it:
+
+```
+Set KEY=value: LOG_LEVEL=debug
+
+╭───────────────────────────────────────────────────╮
+│ Set LOG_LEVEL?                                    │
+│ Saves it and restarts the app to apply it.        │
+╰───────────────────────────────────────────────────╯
+
+y/Enter Save · n/Esc Cancel
+```
+
+`a` adds a hostname, and the line it lands with is the one that finishes the
+job — where to point DNS, taken from the API, with the certificate's own state
+beside each hostname on the list above:
+
+```
+● Added api.example.com — point a CNAME at apps.hyzecloud.app
+```
+
+`r` restarts the app and says where it got to — `◐ Restarting…`, then
+`● Restarted` — and the project's state on the line above is re-read, so the
+screen shows what the API sees. `s` means the verb that changes something: `Stop`
+while the app is up, `Start` when it is not. Stopping takes the app off the air,
+so it asks first, and nothing goes out until you answer:
+
+```
+Projects › shop-api
+
+● Running
+
+URL         https://shop-api.hyzecloud.app
+Last deploy Success · 3h ago
+
+╭──────────────────────────────────────────────────────────╮
+│ Stop shop-api?                                           │
+│ The app stops serving until it is started again.         │
+╰──────────────────────────────────────────────────────────╯
+
+y/Enter Stop · n/Esc Cancel
+```
+
+`o` hands the URL to the browser this machine has; on a box without one it
+prints the URL instead of failing:
+
+```
+● No browser here — open it yourself: https://shop-api.hyzecloud.app
+```
+
+An action that fails reads as a sentence with the next step under it, and `r`
+runs it again — a stop that failed asks again, the way the first one did:
+
+```
+Restart failed
+DOCKER_NOT_AVAILABLE · Docker daemon connection refused
+→ Press r to ask again.
+
+d Deploy · r Retry · s Stop · o Open in the browser · l Logs · Esc Back · ? Help · q Quit
+```
+
+From there, `d` deploys the directory you are standing in to that project — one
+keystroke that uploads whatever folder the CLI was opened in, so it asks first,
+and the question names the folder in full. A wrong directory is obvious before
+anything is sent, and nothing goes out until you answer:
+
+```
+Projects › shop-api
+
+● Running
+
+URL         https://shop-api.hyzecloud.app
+Last deploy Success · 3h ago
+
+╭──────────────────────────────────────────────────────────╮
+│ Deploy to shop-api?                                      │
+│ /Users/me/projects/checkout-api                          │
+│ This folder is uploaded and becomes a real deployment.   │
+╰──────────────────────────────────────────────────────────╯
+
+y/Enter Deploy · n/Esc Cancel
+```
+
+`b` opens the project's build history — what is serving production, what is
+building now, and the cause of the row you are looking at, when the API
+reported one. Each control is taught only for the row that can take it: `x`
+cancels a queued build, `t` redeploys a failed one, `v` reverts to the selected
+one — which is the flow for 3am, when production is broken and the build that
+broke it has to go:
+
+```
+Projects › shop-api › Builds                                  7 builds
+
+  Queued       7h ago     9f9f9f9f
+  Queued       8h ago     1a2b3c4d
+  Building     9h ago     2b3c4d5e  in flight
+> Success      1d ago     3c4d5e6f  production
+  Failed       2d ago     4d5e6f70
+  Cancelled    3d ago     5e6f7081
+
+Cause     BUILD_FAILED · The build ran out of time.
+
+↑↓ Navigate · t Redeploy · v Revert · Esc Back · ? Help · q Quit
+```
+
+Reverting and cancelling ask first, the way stopping does, and neither claims
+more than it did — a revert is queued, not live:
+
+```
+╭──────────────────────────────────────────────────────╮
+│ Revert to 4d5e6f70?                                  │
+│ That source is rebuilt and goes live when it succeeds.│
+╰──────────────────────────────────────────────────────╯
+
+y/Enter Revert · n/Esc Cancel
+```
+
+`d` on the deploy screen is the same path the command line walks: the stages are
+the ones the platform reports; the bar beside them is decoration, and it is the
+first thing to yield when the line is tight:
+Queue       #2 (1st on this machine) in queue · waiting for capacity: memory
+Source      /Users/me/projects/shop-api
+
+Esc Back · ? Help · q Quit
+```
+
+When the build ends, the screen says where it is serving, or why it died —
+`stopped by the platform (exit 137)` is Hyze stopping the container, not a
+crash, and a deployment whose worker reported no cause gets no cause line:
+
+```
+Projects › shop-api › Deploy
+
+✓ Preparing · ✓ Uploading · ✓ Queued · ✓ Source · ✓ Installing · ✕ Building
+Source      /Users/me/projects/shop-api
+Cause       stopped by the platform (exit 137)
+Error       The build ran out of time.
+Build log: hyze logs app_1 dep_9f3
+```
+
+`l` follows the project's logs: the live console over the API's WebSocket when
+the runtime can open one, and the persisted logs the API serves when it cannot
+— either way the screen says which one you are reading:
+
+```
+Projects › shop-api › Logs                                128 lines · following
+
+● Live · WebSocket
+[shop-api] listening on 3000
+[shop-api] GET /health 200
+
+↑↓ Scroll · PgUp/PgDn Page · / Search · f Follow · r Reconnect · Esc Back · ? Help · q Quit
+```
+
+| Key | What it does |
+| --- | --- |
+| `↑` `↓` | move the selection, or scroll the logs |
+| `PgUp` `PgDn` | page through the logs |
+| `Enter` | open the highlighted project, or answer the question on screen |
+| `d` | deploy the current directory to that project — the question names the folder first |
+| `r` | restart the app — or retry the load, deploy or action that failed |
+| `s` | start or stop the app: whichever changes its state (`s` twice is not a stop — the stop is confirmed) |
+| `b` | the project's build history, where a build is redeployed, reverted or cancelled |
+| `e` | set an environment variable, typed as `KEY=value` (it asks: the app restarts to apply it) |
+| `a` | add a custom domain — the DNS target to point at is on the screen |
+| `v` | show or hide the variable values; in the build history, revert to the selected build |
+| `t` | in the build history, redeploy the failed build that is selected |
+| `x` | in the build history, cancel the queued build that is selected |
+| `o` | open the app's URL in the browser |
+| `l` | open that project's logs |
+| `Esc` | back one screen (on the list it quits, in a question it cancels) |
+| `/` | search by name, id or domain — in the logs, filter lines (`Enter` keeps the filter, `Esc` clears) |
+| `f` | in the logs, follow or pause the incoming lines |
+| `?` | the shortcut map |
+| `q` `Ctrl+C` | quit |
+
+- **The state is a word, not a colour.** `● Running` reads the same over SSH, in
+  a 16-colour terminal or with `NO_COLOR` set; colour only reinforces it.
+- **It fits the terminal it is in.** Columns shrink with the window (the
+  subdomain is the first thing to drop) and rows are windowed around the
+  selection, so 60 columns over SSH behaves like 200 locally. It also stops
+  growing at 100 columns, so a very wide terminal keeps its labels next to their
+  values instead of a metre apart. The footer wraps a whole shortcut at a time.
+- **What the API did not say, the screen does not say.** A variable with no
+  value keeps its name, a domain with no certificate gets no certificate line,
+  and a build that reported no cause gets no cause line. Secrets are masked by
+  default and `v` is the deliberate exception.
+- **Failures stay human.** A rejected key says so and points at `hyze login`, a
+  dead connection says the API is unreachable — one line and the next step,
+  never a stack trace. `r` retries without leaving the screen. A live socket
+  that drops says so, reconnects on its own, and falls back to the persisted
+  logs; it never takes the screen down with it.
+- **No terminal, no screen.** Over a pipe or in CI the bare `hyze` prints one
+  line saying the screen needs a TTY and exits `2`; every command above keeps
+  working with no TTY at all.
+
+## Authentication and configuration
+
+`hyze login` verifies the key against the API before storing it. In a terminal the
+input is masked per keystroke (`*`), so a paste is visible without exposing the
+secret; piped stdin and `--key <hyze_...>` skip the prompt entirely — which is
+how CI feeds it:
+
+```bash
+printf '%s' "$HYZE_API_KEY" | hyze login --no-verify
+```
+
+```
+$ hyze login
+Paste your Hyze API key (hyze_...) and press Enter:
+Input is hidden: each character shows as * (backspace works, Ctrl-C cancels).
+> ****************************
+Checking the key against https://api.hyzecloud.com/api…
+✔ Logged in as hyze_fBGv…DJhq (profile "default")
+  Config written to /Users/you/.config/hyze/config.json
+  Workspace: iHZsZubLpZOAHnKebXpW7MibIB12Y2UV
+  Apps visible to this key: 4
+  Plan: Enterprise
+```
+
+| Location | Purpose |
+| --- | --- |
+| `~/.config/hyze/config.json` | profiles, active profile, default output (mode `0600`) |
+| `.hyzerc.json` (nearest ancestor) | per-project defaults: `appId`, `apiUrl`, `workspaceId`, `profile` |
+
+Precedence, highest first: **CLI flag → environment variable → `.hyzerc.json` → active profile → default**.
+An empty variable counts as absent: `HYZE_API_KEY=""` does not shadow the profile.
+
+| Variable | Effect |
+| --- | --- |
+| `HYZE_API_KEY` | API key |
+| `HYZE_API_URL` / `HYZE_API_BASE_URL` | API base (a bare host gets `/api` appended) |
+| `HYZE_WORKSPACE_ID` | workspace to scope requests to |
+| `HYZE_PROFILE` | profile name |
+| `HYZE_OUTPUT` | `table` \| `json` \| `ndjson` \| `text` |
+| `HYZE_CONFIG` / `HYZE_CONFIG_DIR` | config file / config directory |
+| `NO_COLOR` | disable colors |
+
+## Global options
+
+```
+--profile <name>      config profile to use
+--api-key <key>       API key (overrides env and the stored profile)
+--api-url <url>       API base URL
+--workspace <id>      workspace to scope requests to
+--config <path>       config file path
+--timeout <seconds>   per-request timeout (default 60)
+-o, --output <format> table | json | ndjson | text
+--json                shorthand for -o json (the API response, untouched)
+--no-color            disable colors
+-q, --quiet           suppress informational output (stdout stays clean)
+--verbose             log every HTTP request and extra detail
+```
+
+`table` is the default when stdout is a terminal, `json` otherwise — piping always
+yields JSON without asking. Payloads go to **stdout**, progress and messages to
+**stderr**, so `hyze deployments app_1 --json | jq '.deployments[0].status'` is safe.
+
+### What `--json` prints
+
+The API response, untouched — no re-shaped "CLI format" to keep in sync:
+
+| Command | Payload |
+| --- | --- |
+| `projects` | `GET /apps/`: `{ success, apps, meta }` |
+| `deployments <appId>` | `GET /apps/:appId/deployments`: `{ success, deployments, currentDeploymentId, activeDeploymentId, meta }` |
+| `deployments <appId> <id>` | `GET /apps/:appId/deployments/:id`: `{ success, deployment, timeline }` |
+| `logs <appId>` | `GET /apps/:appId/logs`: `{ success, logs }` |
+| `logs <appId> <id>` | `GET /apps/:appId/deployments/:id`: `{ success, deployment, timeline }` |
+| `deploy` | waiting: the settled `{ success, deployment, timeline }`; `--no-wait`: the `POST /apps/deploy` response |
+| `status <appId>` | the state the CLI resolved (below), one shape with or without a container |
+
+`status` is the one command that resolves instead of forwarding: the API cannot
+always see the container, and a made-up `stopped` would read as "the app is down".
+
+```json
+{ "success": true, "appId": "app_abc", "name": "api", "status": "running",
+  "runtime": "bun", "url": "https://api.hyzecloud.app", "memoryMB": 512,
+  "uptimeSeconds": 3661, "reason": null }
+```
+
+## Reading a deployment
+
+`hyze deployments <appId>` prints one row per attempt, with the two facts the API
+exposes about a build that is not simply running or done:
+
+```
+created              status   deployment   queue                     waiting       cause                               branch  commit    title
+───────────────────  ───────  ───────────  ────────────────────────  ────────────  ──────────────────────────────────  ──────  ────────  ──────
+2026-09-16 09:12:04  queued   dep_queued   #3 (2nd on this machine)  machine-full                                      —                 deploy  in flight
+2026-09-16 09:01:55  failed   dep_stopped                                          stopped by the platform (exit 137)  main    a1b2c3d4  deploy  —
+2026-09-16 08:44:10  success  dep_done                                                                                 main    d4e5f6a7  deploy  production
+```
+
+- **Queue**: `#3 in the queue (2nd on this machine)` is the API's 1-based place,
+  global and per machine. `null` means "not queued", and the column stays empty.
+- **Cause of death**: `exitCode`/`oomKilled` come from the worker. `null` means it
+  was never reported — the CLI draws **no cause line** rather than guessing.
+  `137`/`143` are our own drain/deploy stop, so they read as *stopped by the
+  platform*, not as a crash; an OOM kill says so.
+- **Production / in flight** markers come from `currentDeploymentId` and
+  `activeDeploymentId` in the same response.
+
+## Deploy details
+
+Key flags: `--name`, `--app <appId>` (redeploy, defaults to the project in
+`.hyzerc.json`), `--runtime node|bun|python`, `--memory <mb>`, `--port`/`--subdomain`
+(must be passed together), `--env KEY=VALUE` (repeatable), `--env-file`,
+`--root-dir`, `--start-command`, `--install-command`, `--build-command`,
+`--app-type`, `--machine`, `--exclude`/`--include`/`--include-ignored`,
+`--no-wait`, and `--repo <owner/name> [--branch] [--auto-deploy]` for GitHub.
+
+When `--runtime` is omitted the CLI asks the API to inspect the upload and uses the
+detected runtime. With waiting enabled (default) it follows the deployment stage
+timeline on stderr and prints the settled deployment on stdout; a failed deployment
+exits `1` with the API error and a pointer to `hyze logs <appId> <deploymentId>`.
+
+**The wait is a block, not a spinner.** On a terminal the CLI redraws it in place, from
+facts the API sent: the row's own clock, every stage the platform stamped with its own
+duration (a stage still running reads the time since `startedAt`), the phase the worker
+wrote for *this* build (`GET /apps/:appId/deployments/:id/build-progress`, drawn only when
+the worker scopes it to this deployment) and, while the queue holds it, the place and the
+reason — which the detail route does not carry, so they are read from the deployment's row
+in the list. A fact the API did not send is a line that is not drawn; there is no
+percentage, because the contract has none.
+
+```
+shop-api · building · 14s
+  ✔ queue    4s
+  ✔ install  5s
+  ● build    4s
+  worker · building · updated 2s ago
+```
+
+The block belongs to a terminal: in a pipe it writes nothing — no `\r`, no ANSI, no spinner
+— and `--json` / `-o json` / `ndjson` keep their exact payload. What ended the wait is
+printed as a block of its own, and every line of it is a field the API sent:
+
+```
+✔ shop-api is now running
+  project     shop-api
+  deployment  dep_7f3a
+  status      success
+  url         https://shop-api.hyzecloud.app
+  duration    16s
+  created     2026-09-17T10:09:57.719Z
+  source      zip
+```
+
+```
+  project     shop-api
+  deployment  dep_7f3b
+  status      failed
+  stage       install
+  cause       exited with code 1
+  error       npm install failed (exit 1)
+  code        INSTALL_FAILED
+  logs        hyze logs app_9c1 dep_7f3b
+```
+
+`stage` is the stage the timeline records as failed, `cause` is what the worker reported
+about the process (`exitCode`/`oomKilled` — a deployment whose worker reported neither gets
+no cause line) and `duration` is the newest stage end minus the row's `createdAt`.
+
+**The upload limit is data, not a constant.** Before zipping, the CLI reads
+`GET /platform/config` (`maxZipUploadMb`) and refuses an oversized archive itself,
+naming the platform's own number:
+
+```
+✖ ZIP is too large: 812.4 MB (the platform limit is 256 MB)
+  Remove build artifacts (node_modules, .next, dist) from the archive and try again.
+```
+
+**What gets uploaded** — in this order: `--include`/`--exclude` patterns, `.hyzeignore`
+(gitignore-style: `*`, `**`, `dir/`, `!keep`), `git ls-files --cached --others
+--exclude-standard` inside a work tree, otherwise a walk with built-in ignores
+(`.git`, `node_modules`, dist caches, `*.log`, …). `.git` and `node_modules` are never uploaded.
+
+## Logs
+
+`hyze logs <appId>` prints the container output (`--tail 1-1000`, `--timestamps`).
+`hyze logs <appId> <deploymentId>` prints the install/build log the API persisted
+for that attempt. `--follow` polls and prints only what is new — for a deployment
+it stops when the build settles, for a container it runs until interrupted:
+
+```bash
+hyze logs my-api --follow -o text      # --follow writes plain lines, so it needs text output
+```
+
+The live socket (streaming without polling) is not implemented yet.
+
+## Errors and exit codes
+
+Every failure is one line plus the fix, on stderr, with no stack trace (add
+`--verbose` when you want one):
+
+```
+$ hyze deploy . --name api
+✖ PAYLOAD_TOO_LARGE · ZIP is too large: the limit is 256MB.
+  The platform accepts up to 256 MB. Remove build artifacts (node_modules, .next, dist) from the archive and try again.
+
+$ hyze projects
+✖ UNAUTHORIZED · Unauthorized
+  The key is missing, expired or revoked. Run `hyze login` to store a new one (Settings → Developer).
+```
+
+| Code | Meaning |
+| --- | --- |
+| 0 | success |
+| 1 | operation failed (including a failed deployment) |
+| 2 | usage error: bad flags, missing key, no project selected, the screen without a TTY |
+| 3 | unauthenticated / forbidden (including plan limits) |
+| 4 | not found |
+| 5 | rate limited (including the workspace build slot) |
+| 6 | validation error (400/409/413/422) |
+| 7 | server error (5xx) |
+| 8 | network error or timeout |
+| 130 | interrupted (Ctrl-C) |
+
+Codes the CLI translates into advice: `PLAN_LIMIT` (plan memory), `PLAN_BUILD_LIMIT`
+/ `TOO_MANY_DEPLOYS` (workspace build slot), `PAYLOAD_TOO_LARGE` (the limit comes
+from `details.maxZipUploadMb`), `UNAUTHORIZED` (expired session), `APP_NOT_DEPLOYED`
+(no container yet), `ZIP_ENCRYPTED`.
+
+### Status and the "unknown" state
+
+`hyze status <appId>` prints what the platform reports: `running`, `stopped`,
+`paused`, `restarting`, `deploying`, `error`, `exited`, `created` — or `unknown`
+when it cannot see the container at all (`APP_NOT_DEPLOYED`: no worker binding,
+or `SERVICE_UNAVAILABLE`: the worker is down). `unknown` exits `0`: the question
+was answered, the answer is that the platform does not know. A read that fails
+(auth, 5xx, network) keeps its mapped exit code instead.
+
+## Development
+
+```bash
+bun install
+bun run dev -- --help      # run from source
+bun run typecheck
+bun run lint
+bun run test               # unit + end-to-end tests (stub HTTP server, real binary)
+bun run build              # dist/index.js for npm
+```
+
+Layout: `src/core` (config, HTTP client, output, errors, progress, the deploy
+path and the log helpers), `src/commands` (one module per command, each exporting
+a `register*` function), `src/tui` (the interactive screen: `app.tsx` holds the
+state, `keys.ts` declares every key of every screen — the footer is derived from
+the same tables — `action.ts` is the vocabulary an action reports in,
+`use-action.ts` runs the lifecycle calls and `browser.ts` opens a URL,
+`stages.ts` and `format.ts` do the text and column maths, `screens/` renders),
+`src/tests` (unit tests plus `cli.e2e.test.ts`, which drives the real binary
+against a stub server — every spawn piped, every run with its own config
+directory, so the suite is also the no-TTY path). The screen is covered three
+times: `tui.render.test.tsx` renders it into fake streams at 60/80/120 columns
+and presses keys, `tui.deploy.test.tsx`, `tui.logs.test.tsx` and
+`tui.actions.test.tsx` do the same for a deploy's stages, its queue line and its
+failures, a stubbed console socket, and the restart, the stop dialog, the
+browser and an action that failed — and `tui.e2e.test.ts` runs the real binary
+inside a PTY to check what the terminal ends up showing, including the lifecycle
+calls it really sent and the cursor being handed back on exit.
+
+## License
+
+MIT