bravenlab 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,249 @@
-# Temporary Holding Version
+# bravenlab
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The `braven` command: **sign in once per machine** and let the CLI and the
+Python SDK use the same identity.
+
+This package owns no credential convention. The config file's path, its
+version-1 schema and the OS keychain naming belong to
+[`braven-identity`](../identity/README.md) (`packages/identity`), the contract
+every surface mirrors — so a `braven login` here is the same login
+`braven.login()` sees. The TypeScript implementation lives in
+[`@braven/identity-store`](../identity-store/README.md), which this CLI and
+`braven-agent` share; the Python package stays the reference.
+
+Nothing in this package ever prints, logs or writes a secret: secrets live in
+the OS keychain and are handed only to the store.
+
+## Install
+
+```bash
+npx bravenlab --help
+npx bravenlab agent --folder ./my-data-folder --project-id <id>
+```
+
+The package installs two names for one bin: `npx bravenlab` (the package name)
+and `braven` once it is installed globally. The old package name
+`braven-cli@0.1.0` is superseded by `bravenlab`; the OAuth client id stays
+`braven-cli` on the wire.
+
+`braven` and `braven-agent` publish together from a `v*` tag
+(`.github/workflows/release-npm.yml`); the tag must equal both manifests
+(`scripts/check-release-tag.ts`), and the release drops the `workspace:` ranges
+npm cannot resolve (`scripts/prune-workspace-deps.ts`) because the build inlines
+those packages.
+
+The workflow **stages** the release (`npm stage publish`) rather than publishing
+it: a maintainer approves the staged version with 2FA — `npm stage approve
+<stage-id>`, or the **Staged Packages** tab on npmjs.com — and only then does
+`0.1.0` become installable. A brand-new name gets a public `0.0.0-stage`
+placeholder while its real version waits.
+
+The published artifact is a bundle, not the source tree: `braven` is
+`dist/bin.js`, a plain ESM file with `#!/usr/bin/env node`, its third-party
+dependencies external and declared in `dependencies`. `files` ships `dist/` and
+this README only; source maps embed their sources, so a stack trace still points
+into the TypeScript without publishing `src/`.
+
+```bash
+nub run --filter bravenlab build  # esbuild → dist/bin.js + dist/{cli,auth}.js
+node dist/bin.js --help            # exactly what an install runs
+npm pack --dry-run                 # dist/ + README.md
+nub exec -F braven braven --help   # the workspace bin, after a build
+nub run --filter bravenlab test   # builds in `pretest`, then the suite
+```
+
+`src/bin.test.ts` spawns `dist/bin.js` with an empty home directory, so a bundle
+that drifts from the source (or loses its shebang or a runtime dependency) fails
+the suite rather than a user. Development still runs the source directly — Node
+24 strips its types — but `braven agent` resolves the `braven-agent` package, so
+build the agent once first:
+
+```bash
+nub run --filter braven-agent build
+node --experimental-strip-types src/bin.ts --help
+```
+
+## Commands
+
+| Command | What it does |
+| --- | --- |
+| `braven login [--origin URL] [--web-origin URL]` | Opens the browser, waits for the signed-in session token on a loopback listener, proves it with `GET {origin}/api/auth/get-session`, stores it in the keychain as `kind="session"`, makes the account current, then prints whoami. **This is the whole sign-in: no password is typed into the terminal.** |
+| `braven login --watcher` | Uses the sign-in the Braven app already made on this machine: the app (and the agent it runs) and the CLI share one store, so this only adopts the account and makes it current — no browser, no keychain prompt. Refuses when the app never signed in to the resolved server. |
+| `braven login --api [--key bvn_api_…] [--email EMAIL]` | Stores a long-lived API key as `kind="apiKey"`; the key comes from `--key` or `$BRAVEN_API_KEY`. For CI, scripts and machines that cannot open a browser. |
+| `braven login --device [--client-id ID]` | Better-auth's device authorization grant: prints a user code and verification URL, opens it, polls `/api/auth/device/token` on the server's interval, then proves and stores the session token exactly as the loopback flow does. For headless machines and machines without a reliable loopback callback. |
+| `braven push <file> [--override] [--path PATH] [--project-id ID]` | Uploads one local file through `POST {origin}/files/ingest` with `X-Project-Id` and the stored credential as a bearer. `--path` defaults to the file's basename; `--override` reuses that path's Experiment/File instead of deduping or adding a sibling. |
+| `braven key add [--origin URL] [--email EMAIL] [--label LABEL] <bvn_api_...>` | Stores a long-lived API key as `kind="apiKey"`. The owner comes from `--email`, or from `GET {origin}/api/auth/get-session` with the key as a bearer. |
+| `braven whoami` | The effective identity: origin, email, kind, label. **Never the secret.** Honours `BRAVEN_SESSION_TOKEN` / `BRAVEN_API_KEY` and says "signed in from the environment" when one is in play. |
+| `braven config` / `braven config show` | The stored accounts, which one is `current`, and the resolved `company` / `project` defaults. |
+| `braven config set company\|project <value>` | Writes one default. |
+| `braven config use <email>` | Switches `current`, wherever that account's origin is. |
+| `braven logout [--email EMAIL]` | Forgets that account — keychain secret included (default: the current one), rotating `current` to a survivor. A stored session is revoked server-side; a stored API key is only forgotten. |
+| `braven agent [agent flags]` | Runs the headless watch daemon (`braven-agent`) with the arguments handed over verbatim. Same program, same flags — `braven agent --help` prints the daemon's usage. |
+
+`--origin` beats `$BRAVEN_API_URL`, which beats the hosted
+`https://api.bravenlab.com`. A trailing slash is normalised away, so origins
+never produce a doubled path. `--web-origin` beats `$BRAVEN_WEB_URL`, which
+beats `https://bravenlab.com`.
+
+## Three ways in
+
+`braven login` picks the flow with a flag: `--watcher` (the running app's
+sign-in), nothing/`--browser` (the loopback handoff), or `--api` (a stored key).
+All three end in the same identity store, so `whoami`, `push`, `agent` and the
+Python SDK see the same account.
+
+## How `login` works
+
+1. Bind an `http.Server` on `127.0.0.1` with **port 0**, and read the real
+   ephemeral port from `HttpServer.address` (narrowed to an inet address).
+2. `GET /?token=<session token>` resolves an Effect `Deferred` and answers
+   `<h1>Authenticated. You can close this window.</h1>`; every other request is
+   `400`. The listener is loopback-only and lives in the command's scope, so it
+   closes on success, on the timeout, and on Ctrl-C.
+3. Open `{webOrigin}/cli-login?port=<port>` with the `open` package. The web app
+   redirects the better-auth session token to the loopback URL.
+4. Wait five minutes (`Effect.timeoutOrElse`). On timeout the listener closes
+   and the CLI fails with one actionable line.
+5. With the token, call `GET {origin}/api/auth/get-session` with
+   `Authorization: Bearer <token>`. Only a `200` whose body has `user.email`
+   becomes an account; any other answer fails loudly and stores nothing.
+
+## How `login --device` works
+
+The same identity, without the token-in-a-URL handoff. It needs better-auth's
+`deviceAuthorization()` plugin on the API — this repo configures it, along with
+the `deviceCode` table and the `/device` approval page.
+
+1. `POST {origin}/api/auth/device/code` with `{client_id, scope}`. The client
+   id is `--client-id`, `$BRAVEN_CLIENT_ID`, or `braven-cli`; the scope is
+   `openid profile email`.
+2. Print the `user_code` and open
+   `verification_uri_complete ?? verification_uri` through the same `Browser`
+   seam.
+3. Poll `POST {origin}/api/auth/device/token` with the RFC 8628 grant
+   (`grant_type`, `device_code`, `client_id`) on a `Schedule` seeded from the
+   server's `interval`. `authorization_pending` keeps polling; `slow_down` adds
+   five seconds to every subsequent interval. `expired_token`,
+   `access_denied` and `invalid_grant` stop with one actionable line.
+4. The whole wait is bounded by `expires_in` (30 minutes when omitted) through
+   `Effect.timeoutOrElse`.
+5. On success `access_token` is a better-auth session token: prove it with
+   `GET /api/auth/get-session`, store `{origin, kind: "session", secret, email}`
+   and print whoami. Nothing is stored on expiry, denial or failure.
+
+## How `push` works
+
+`files.ingest` is plan 015's one ingest wire. It is mounted as a plain
+multipart route so scripts share one write path with the oRPC procedure the
+webapp uses:
+
+```
+POST {origin}/files/ingest
+Authorization: Bearer <session token or API key>
+X-Project-Id: <project>
+Content-Type: multipart/form-data
+```
+
+The body carries `path`, `override` (`"true"` / `"false"`) and the bytes as
+`file`. `path` defaults to the file's basename; the server takes its basename
+as the `filename` that keys the Experiment and File. Both doors end at
+`saveUpload`, so hashing, dedup, versioning and `--override` have one
+implementation (`apps/api/src/workerRoutes.ts`). Re-pushing the same bytes never
+makes a second File in that Experiment; `--override` reuses the path's existing
+Experiment instead of creating a sibling.
+
+The project comes from `--project-id`, `$BRAVEN_PROJECT_ID`, or the store's
+`defaults.project` resolved to an id through `GET /projects` (narrowed by
+`defaults.company` when both are set). An unknown or ambiguous project name
+fails with exit 2 instead of guessing; a server refusal is one line and exit 1.
+
+## How `logout` works
+
+The stored secret is read **before** the account is removed, so the command can
+revoke it. Only a stored `session` is revoked — `POST
+{origin}/api/auth/sign-out` with the token as a bearer; a `200` or a `401` both
+mean it is dead. A `kind="apiKey"` account is only forgotten locally and stays
+valid until it is revoked under **Settings → API keys**.
+
+The keychain secret and config row then go, and `current` rotates to a survivor
+(or none). Because the local account is already gone when revocation runs, an
+unreachable API is a warning — "the session stays valid until it expires" — not
+a failure; there is nothing left to retry. With no stored account the command
+exits 3.
+
+## Identity store
+
+Config (never a secret), at the OS convention:
+
+| OS | Path |
+| --- | --- |
+| macOS | `~/Library/Application Support/braven/config.json` |
+| Linux | `${XDG_CONFIG_HOME:-~/.config}/braven/config.json` |
+| Windows | `%APPDATA%\braven\config.json` |
+
+```json
+{
+  "version": 1,
+  "current": "https://api.bravenlab.com|me@example.com",
+  "accounts": [
+    { "origin": "https://api.bravenlab.com", "email": "me@example.com", "kind": "session" }
+  ],
+  "defaults": { "company": "Gelion" },
+  "watcher": {}
+}
+```
+
+Writes are atomic (`config.json.tmp` + rename) and preserve `watcher` and the
+other defaults. Secret, in the OS keychain via `@napi-rs/keyring` (macOS
+Keychain, Windows Credential Manager, libsecret): service `braven`, account
+`{origin}|{email}`. **No plaintext fallback**; a refused keychain surfaces as
+one line and nothing is written.
+
+Precedence for the secret is `env var > store`: `BRAVEN_SESSION_TOKEN` or
+`BRAVEN_API_KEY` (with `BRAVEN_API_URL`) win and touch neither file nor
+keychain. The origin is `flag > $BRAVEN_API_URL > hosted`; `--email` selects a
+stored account.
+
+## Exit codes
+
+| Code | Meaning |
+| --- | --- |
+| `0` | It worked. Help and `--version` too. |
+| `1` | The command failed: a rejected session, an unreachable API, a keychain that refused, a corrupt config file. |
+| `2` | The arguments cannot work: an unknown flag, a missing one, a key without the `bvn_api_` prefix, a key whose owner the probe could not prove. |
+| `3` | Not signed in, or no stored account for the email asked about — so a script can `braven login` and retry. |
+
+Failures print exactly one `braven: <what to do>` line on stderr.
+
+## Layout
+
+```
+src/
+  bin.ts          # entry point: `agent` dispatch, then Node services + runMain
+  cli.ts          # the effect/cli command tree and the exit-code boundary
+  commands.ts     # login (browser handoff), whoami, config, logout, key add
+  auth.ts         # loopback listener, device grant, session lookup + revoke
+  files.ts        # files.ingest multipart wire + project resolution
+  testing.ts      # browser/sessions/HTTP doubles (the store's doubles come from
+                  # @braven/identity-store/testing)
+```
+
+The config file, its schema, the keychain (`Keychain`, `StoreConfig`,
+`Environment`) and the `CliFailure` vocabulary live in
+[`@braven/identity-store`](../identity-store/README.md), so the CLI and
+`braven-agent` read one store instead of depending on each other. The seams the
+CLI adds are `Browser`, `Sessions` and `HttpClient`. Tests replace all of them,
+so the suite touches no real keychain, no real browser and no network except
+the loopback listener the sign-in test deliberately starts.
+
+`braven agent` is not an `effect/cli` command: `bin.ts` checks `argv[0]` first
+and hands the remaining arguments to `runAgent` from `braven-agent`, so the
+daemon's flags never have to be modelled twice.
+
+## Development
+
+```bash
+nub run --filter bravenlab check-types
+nub run --filter bravenlab test
+nub run lint && nub run fmt
+```