pylot-cli 0.1.0

package/README.md

@@ -0,0 +1,133 @@
+# pylot — the Pylot gateway CLI
+
+First-class CLI for the Pylot gateway API (epic #1802). Replaces every curl
+workflow — dispatching missions, tailing logs, crew/admin/secrets management —
+for both AI operators (`claude -p` sessions, subagents) and humans.
+
+```
+pylot dispatch "fix the flaky gateway-cache test" --agent infra.lead --repo fellowship-dev/pylot --wait
+pylot ps
+pylot missions logs <job-id> --follow
+pylot deploy --wait --env staging
+```
+
+## Install
+
+```bash
+npm install -g pylot-cli
+```
+
+Published on npm as [`pylot-cli`](https://www.npmjs.com/package/pylot-cli)
+(Node 20+). The package ships a single self-contained bundle and **no
+credentials**: it only talks to the gateway URL you configure, and every
+request is authorized by a token your own gateway deployment mints. There is
+no hosted signup or OAuth flow — if you don't hold a token for a gateway, the
+CLI can't do anything ("closed by default"). Self-hosters: see
+[SELF-HOSTING.md](../../SELF-HOSTING.md) for deploying a gateway and minting
+the dispatch token.
+
+Inside Pylot's own containers no install is needed — the operator image bakes
+the bundle in at `/usr/local/bin/pylot`.
+
+## Design contract
+
+- **JSON on non-TTY stdout** (or `--json`): exactly one JSON document per
+  command — the *verbatim* gateway response body — newline-terminated. All
+  progress notes, hints, and errors go to stderr. `pylot missions list | jq .`
+  always works. While following logs, entries stream as NDJSON.
+- **Tables on TTY** for list commands; pretty-printed JSON otherwise.
+- **Exit codes**: `0` success, `1` API/runtime error, `2` usage error.
+  `missions wait` / `dispatch --wait` exit `0` only when the mission ends `done`.
+- **Destructive commands** (`kill`, `cancel`, `delete`, `revoke`, …) require
+  `--force` and send nothing without it.
+- Single-file bundle (`dist/index.mjs`, esbuild) — no runtime `node_modules`.
+  Runtime deps are `commander` + `conf` only; no interactive/prompt libraries.
+
+## Configuration
+
+Everything resolves from flags, then environment, then the config file
+(`pylot config set …`, stored via `conf`; env vars always win).
+
+| | resolution order |
+|---|---|
+| URL | `--url` → `PYLOT_DISPATCH_URL`¹ → `PYLOT_API_URL` → `PYLOT_GATEWAY_URL` → `PYLOT_API` → config file |
+| Token | `--token` → `PYLOT_API_TOKEN` → `PYLOT_SESSION_JWT` → `PYLOT_BROKER_TOKEN` → `PYLOT_DISPATCH_TOKEN` → config file |
+
+¹ historically holds the full `…/dispatch` endpoint URL — the CLI strips the
+suffix automatically.
+
+`--env staging` switches to `PYLOT_STAGING_URL` + `PYLOT_STAGING_DISPATCH_TOKEN`
+(config keys `staging-url` / `staging-token`).
+
+Inside Pylot containers the right credential is already injected (token plane
+#1884): chat sessions get a session JWT (`PYLOT_API_TOKEN`), mission workers a
+broker JWT (`PYLOT_BROKER_TOKEN`, scoped to git-token + heartbeat — it cannot
+dispatch), operators the master token. `pylot auth status` shows which source
+won and what the gateway thinks of it. On a `403 insufficient_scope` the CLI
+tells you which scope is missing and how to get it.
+
+## Command groups
+
+Run `pylot --help` (or `pylot <group> --help`) for the full tree.
+
+| Group | Covers |
+|---|---|
+| `health` `stats` `events` | liveness, metrics, event ledger |
+| `dispatch` | POST /dispatch with `--wait` / `--follow` |
+| `missions` (`ps`) | list/view/wait/logs/session/deps/audit/report/complete/heartbeat/wake/update/cancel/kill |
+| `costs` `executor` `audits` `pricing` `logs` | cost reporting, executor sweeps, audit corpus, model pricing, infra logs |
+| `workers` `devboxes` | devbox workers and standalone devboxes |
+| `conversations` (`convo`) | full conversation surface: messages, wakes, subscriptions, resources, devboxes, analytics |
+| `crew` `route` | team config, operator instructions, role skills, crons, ledger, playbooks, goals |
+| `admin` | config, audit, org caps, migrations |
+| `deploy` | POST /admin/deploy + CodeBuild polling (`--wait`), image builds |
+| `secrets` | path-based ASM bundle/key operations |
+| `skills` `automations` `providers` `orgs` `assets` | skills catalog/sync, automation rules, provider chains, repo enablement, asset presign/publish |
+| `auth` `config` `login` | identity (`auth status`), scoped tokens, git tokens, local config |
+
+Notes on log streaming: SSE endpoints return 501 on the deployed (Lambda)
+gateway, so `missions logs --follow` polls
+`GET /missions/:id/logs/cloudwatch?since_time=<cursor>` — including 206
+partial-fetch draining — and stops when the mission goes terminal. Identical
+boundary timestamps can rarely duplicate a line (CloudWatch ms resolution).
+
+Deliberately not covered (internal plumbing): `POST /webhook`, `/internal/*`,
+`POST /admin/skills/commit`, `POST /cost-report`, worker-daemon turn routes
+(`workers/poll|heartbeat|report`), `/admin/worker-keys`, `/admin/test/*`.
+
+## Development
+
+```bash
+cd modules/cli
+npm ci
+npm run typecheck   # tsc --noEmit (strict)
+npm run build       # esbuild → dist/index.mjs (executable)
+node dist/index.mjs --help
+```
+
+Integration tests live at the repo root (`tests/gateway-cli-*.test.mts`) and
+run in the corpus gate (`./scripts/test.sh corpus`): they spawn a real hermetic
+gateway (PGlite) and execute the **built** CLI against it — no mocked fetch.
+`scripts/test.sh` builds the bundle before the test pass.
+
+The operator image bakes the bundle in as `/usr/local/bin/pylot`
+(see `Dockerfile.operator`); rebuild via `/image-builder operator`.
+
+## Publishing to npm (maintainers)
+
+The package is public on npm as `pylot-cli`. To cut a release:
+
+1. Bump `version` in `modules/cli/package.json` (semver — the bundle embeds it
+   via `__CLI_VERSION__`, so `pylot --version` reports whatever you publish).
+2. From `modules/cli/`: `npm publish --access public`. The `prepublishOnly`
+   hook runs the typecheck and a fresh build, and the `files` allowlist keeps
+   the tarball to `dist/index.mjs` + README only — no source, no lockfile.
+3. Publishing requires an npm token with publish rights on `pylot-cli` — use
+   an **Automation** token (or a granular token with 2FA bypass) in CI;
+   interactive publishes prompt for the account OTP.
+4. Verify: `npm view pylot-cli version` and
+   `npx -y pylot-cli@latest --version`.
+
+Version discipline: any change to gateway routes that the CLI wraps should
+land with a CLI bump in the same PR train, so the published CLI never lags
+the deployed API surface.