@oxy-hq/cli 0.7.0 → 0.9.0

package/README.md

@@ -3,7 +3,7 @@
 `oxyc` — a `gh api`-shaped client for the Oxy HTTP API, plus the tooling that
 manages customer workspace repos.
 
-- **API client** — `api`, `routes`, `schema`, `openapi`, `login`, `whoami`, `token`, `tokens`, `assume`, `oltp`
+- **API client** — `api`, `routes`, `schema`, `openapi`, `login`, `whoami`, `token`, `login-link`, `tokens`, `assume`, `oltp`
 - **Customer workspaces** — `list`, `new`, `import`, `doctor`, `update`, `adopt`, `launch`
 - **Custom apps** — `publish`, `init-ci`, `proxy`, `apps`
 - **Checks** — `checks run`
@@ -152,14 +152,30 @@ route's surface and fleet role.
 oxyc login [--env <e>] [--login-env <e...>] [--assume <org> -r <why>]
 oxyc whoami [--json]        # who the credential is, and what it can reach
 oxyc token                  # print the bearer, for a raw curl
+oxyc login-link [--next <path>] [--json] [--open]   # a one-time URL that signs a browser in
 oxyc logout                 # revoke the cached token, then forget it
 oxyc tokens list [--json]   # your personal access tokens
 oxyc tokens revoke <id>
 oxyc tokens revoke --current   # end the token in OXY_TOKEN
 oxyc tokens create          # opens Account → Personal access tokens
 oxyc tokens create --sandbox-agent --app <org>/<app> [--app …] [--hours 8] [--name …]
+oxyc tokens create --agent [--standing] [--hours 8] [--name …]
 ```
 
+**An agent runs on its own token, never on the person's `oxyc login`.** Which
+one depends on the task:
+
+| The agent is… | It mints | Which reaches |
+| --- | --- | --- |
+| building a custom app in a sandbox | `tokens create --sandbox-agent --app …` (`oxy_sbx_…`) | the sandboxes of the apps it names, and nothing else |
+| doing anything else: reading data with `oxyc api`, reproducing a bug against live data | `tokens create --agent` (`oxy_pat_…`) | everything its approver can, for hours |
+
+Both are approved once in the browser by the person the agent works for, both
+are printed once as `export OXY_TOKEN=…` and never stored, and both end with
+`tokens revoke --current`. After a mint, pass `--token-env OXY_TOKEN` to every
+command: a named variable is the only source, so a command that lost the
+variable exits `4` instead of quietly running on the person's cached login.
+
 **Every command resolves its credential the same way, first match wins:**
 
 1. **`OXY_TOKEN`** (or the variable `--token-env` names). It holds any
@@ -167,7 +183,8 @@ oxyc tokens create --sandbox-agent --app <org>/<app> [--app …] [--hours 8] [--
    token (`oxy_pat_…`), a service account token (`oxy_sat_…`), a CI token
    (`oxy_ci_…`) or a sandbox agent token (`oxy_sbx_…`) — a legacy API key
    (`oxy_…`), a publish token, or a session token. A blank value counts as
-   unset.
+   unset. An agent token is a personal access token by its prefix: only its
+   own description tells it from a login (`oxyc whoami`).
 2. **The login cache** — what `oxyc login` stored for this deployment.
 3. **GitHub OIDC**, in a GitHub Actions job granted `id-token: write`: the job's
    OIDC token is exchanged, once per process, for a fifteen-minute token acting
@@ -195,7 +212,7 @@ Settings → Workspace → Legacy API keys. Use an API token for anything new.
 
 **`login`** runs a browser loopback flow. Against a current deployment it
 receives a one-time code and exchanges it (PKCE) for a **personal access
-token** named `oxyc on <hostname>`: revocable, ninety days, and replacing that
+token** named `oxyc on <hostname>`: revocable, a year, and replacing that
 machine's previous one. No credential travels in a URL. Against a deployment
 that predates the exchange it stores the session token the page hands back,
 exactly as before, and says so — nothing needs upgrading first, in either
@@ -211,7 +228,10 @@ rather than reading as fine from the cache. For a token it also prints what the
 token is and what it can reach — `all access`, or one line per grant with the
 role it is capped at, and any organization whose policy blocks it. For a legacy
 API key it prints `Legacy API key`, and that it reaches everything its owner
-can.
+can. For an agent token it says `agent token`, who approved it, whether it
+carries their staff or partner access, and when it expires. When a token in
+`OXY_TOKEN` is refused (exit `4`), the advice is never to log in — a login
+cannot replace what is in the variable. An agent stops and reports.
 
 **`token`** prints the bearer on stdout and nothing else. Inside a GitHub
 Actions job with nothing stored it prints the token the job's OIDC identity
@@ -275,6 +295,35 @@ A refusal from the server carries a hint an agent can act on — never "try
 `oxyc login` again". Exit `4` under this token means it expired, was revoked,
 or its minter lost access: stop and report.
 
+**`tokens create --agent`** mints an **agent token** for everything that is not
+a sandbox: a personal access token (`oxy_pat_…`) that reaches what its approver
+reaches through their organization memberships, for 8 hours by default
+(`--hours`, 1 to 168). It cannot be extended, edited or regenerated, and it
+cannot create, extend or revoke tokens; it can open a browser session as itself
+(`login-link`).
+
+```bash
+eval "$(oxyc tokens create --agent --env dev)"
+```
+
+The same browser loopback again, with the same guarantees: stdout is the single
+line `export OXY_TOKEN=oxy_pat_…`, printed once, everything else is on stderr,
+it holds no credential while it runs, never writes the credentials file and
+revokes no other token. Arguments are checked before the browser opens (exit
+`2`); `--agent` and `--sandbox-agent` together are a usage error.
+
+`--standing` asks for the approver's staff or partner access as well. The
+approver decides on the page, where it starts **off**: a token that comes back
+without it is accepted, and stderr says so in one line. Without `--standing`, a
+token that carries either is refused.
+
+What comes back is checked before anything is printed: it must be a whole
+`oxy_pat_`; it must describe itself (`GET /api/auth/token`) as `personal` with
+`source` `oxyc_agent`; it must expire no later than the hours asked for; and it
+must carry no standing that was not asked for. A deployment that predates agent
+tokens would otherwise hand back an ordinary ninety-day login. On any mismatch
+the command prints nothing, revokes what was minted, and exits `8`.
+
 Credentials live in the OS config directory under **`oxy`** — the same file the
 Rust `oxy login` wrote before it was removed, so an existing login still works:
 
@@ -285,6 +334,46 @@ An entry may now also carry `token_id` and `expires_at`; both are optional, and
 a file written before they existed loads unchanged. `OXY_CREDENTIALS_PATH`
 overrides the path. Caches are separate, under `oxyc` (`~/.cache/oxyc`).
 
+### A signed-in browser for an agent
+
+Sign-in is passwordless — Google or GitHub OAuth, or a magic link — and an
+automation agent can finish neither. **`login-link`** prints a one-time URL
+that signs a browser in with the credential `oxyc` is running on, so the whole
+sign-in is one navigation:
+
+```bash
+browser_navigate("$(oxyc login-link --env dev --next /ide)")     # Playwright MCP
+```
+
+```ts
+// a Playwright script
+const link = execFileSync("oxyc", ["login-link", "--env", "dev", "--next", "/ide"], { encoding: "utf8" });
+await page.goto(link.trim());
+```
+
+Stdout is the URL and nothing else; what the link is goes to stderr.
+
+- **The link works once and expires in minutes** (five, at the time of
+  writing — the server's `expires_at`). The bearer is never in it: `oxyc`
+  trades the token for a single-use ticket (`POST /api/auth/browser-ticket`),
+  and the ticket and `--next` ride the URL's fragment, which is not sent to a
+  server and so reaches no access log.
+- **The session is bounded by the token.** It reaches what the token reaches
+  and nothing more, lasts at most the `session_seconds` the server answers
+  (stderr states it in hours), ends sooner if the token is revoked or expires,
+  and cannot manage tokens.
+- **It needs a personal access token** (`oxy_pat_…`) — what `oxyc login`
+  stores. Any other credential is exit `4` with the next step: a session token
+  from an older login, a service account, CI or publish token, a legacy API
+  key. A sandbox agent token is exit `2`, before any request. A deployment that
+  predates sign-in links is exit `5`.
+- **`--next <path>`** is where the browser lands: a path on the deployment
+  starting with a single `/`. A URL, `//host` or a backslash is exit `2`, and
+  no ticket is spent on it.
+- **`--json`** prints `{ "url", "expires_at", "session_seconds" }` instead.
+  **`--open`** also opens the link in your default browser — which uses it, so
+  the printed URL will not work a second time.
+
 ### CI without a stored secret
 
 In a GitHub Actions job granted `id-token: write`, with no `OXY_TOKEN` set,
@@ -507,7 +596,15 @@ lets it publish.
 *The workflow* is `.github/workflows/oxy-publish.yml` at the repo root: a
 `build` job (no id-token) that runs `publish --build-only`, and a `publish` job
 bound to a GitHub `environment:` (`--environment`, default `oxy-publish`) whose
-only work is `publish --prebuilt`. That job uses no third-party action: each
+only work is `publish --prebuilt`. `build` installs pnpm with
+`pnpm/action-setup@v6` — the pnpm the repo root's package.json pins
+(`packageManager` or `devEngines.packageManager`), with no `version:` of its
+own, since the action refuses a second, different one; pnpm 11 when nothing
+pins it — and both jobs run the Node in `.nvmrc`, else 26 (pnpm 11 needs
+Node 22.13 or later). It warns when nothing pins pnpm, and when
+`pnpm-workspace.yaml` approves build scripts only with `onlyBuiltDependencies`,
+which pnpm 11 ignores (the build's install would fail with
+`ERR_PNPM_IGNORED_BUILDS`; move the entries to `allowBuilds`). The publish job uses no third-party action: each
 step runs `npx @oxy-hq/cli@<this version>` and `oxyc` exchanges the job's OIDC
 token for itself, acting as the service account `--service-account <org>/<name>`
 names — by default `<app's org>/deployer`. **Here, and only here, the account is
@@ -664,6 +761,26 @@ object to stdout instead:
 { "app": "acme/dashboards", "appId": "…", "checks": [{ "name": "canary", "runId": "…", "status": "done", "passed": true, "durationMs": 4123 }] }
 ```
 
+**`--browser`** also loads the app's page in headless Chromium and proves it
+mounted: the platform runtime's `oxy-app-ready` beacon fires, nothing on the
+page throws, and `--expect-selector <css>` (optional) becomes visible. With
+`--app-env` the page must also report that environment and the build it serves
+(`oxyc env show`'s `build_uuid`) in `window.__OXY_APP__`. The credential and
+`X-Oxy-App-Env` ride only on requests under the app's own base path
+(`/customer-apps/<org>/<app>/`: the document, assets, beacon and `/fn` calls).
+The rest of the deployment's API is on the same origin, and the code under test
+is often a build someone else published, so its `/api/…` calls go without the
+credential, as an anonymous visitor's would. The result is one more entry in `checks[]`, with `"kind": "browser"` and
+the `/fn` calls the page made. Playwright is not a dependency: it is resolved
+from the working directory (`playwright`, `playwright-core` or
+`@playwright/test`), so run it where one is installed. The page loads as a
+user, so a publish, service-account, CI or sandbox agent token is refused
+before any request.
+
+```bash
+oxyc checks run acme/store --app-env dev-a1 --browser --expect-selector 'main'
+```
+
 **Auth** follows the same rule as `oxyc api`'s bearer surface, with one
 difference: `checks run` talks to `/api/admin/**`, which is not the
 `/external/api/*` surface, so a configured API key is sent explicitly as
@@ -980,9 +1097,12 @@ them, and a tool that can only fail still costs its schema every turn. A dead
 token ends the server at startup with exit `4`.
 
 **`guide`** prints a page to paste into `AGENTS.md` / `CLAUDE.md`.
-**`skills install`** symlinks the six bundled Claude skills into
+**`skills install`** symlinks the bundled Oxy platform skills into
 `~/.claude/skills`; it refuses to run from an `npx` cache, whose symlinks dangle
-once npm reclaims it.
+once npm reclaims it. The same skills are published to
+[`oxy-hq/skills`](https://github.com/oxy-hq/skills) for every other agent —
+`npx skills add oxy-hq/skills`, or the Claude Code plugin `oxy@oxy-hq`. They are
+written in `skills/` here; see `internal-docs/platform-skills.md`.
 
 ## Exit codes
 
@@ -998,7 +1118,10 @@ once npm reclaims it.
 9  a check ran and failed or timed out (`oxyc checks run`)
 ```
 
-`4` almost always means the wrong `--env`. `7` is worth retrying; `6` never is.
+`4` almost always means the wrong `--env`. A person logs in again. An agent on
+its own token (`tokens create --agent` or `--sandbox-agent`) does not: there,
+`4` means the token expired or was revoked, and the agent stops and reports.
+`7` is worth retrying; `6` never is.
 
 ## Environment variables