@oxy-hq/cli 0.5.0 → 0.6.0

package/README.md

@@ -5,8 +5,10 @@ manages customer workspace repos.
 
 - **API client** — `api`, `routes`, `schema`, `openapi`, `login`, `whoami`, `assume`, `oltp`
 - **Customer workspaces** — `list`, `new`, `import`, `doctor`, `update`, `adopt`, `launch`
-- **Custom apps** — `publish`, `init-ci`, `proxy`
+- **Custom apps** — `publish`, `init-ci`, `proxy`, `apps`
 - **Checks** — `checks run`
+- **Sandboxes** — `env`, `fn call`, `invocations`, `logs`
+- **Workspace previews** — `preview`
 - **Development** — `validate`, `mcp`, `guide`, `skills`
 
 ## Install
@@ -77,7 +79,10 @@ Credentials are stored **per deployment**, and the default is production. A
 oxyc api <path> [flags]
 ```
 
-`<path>` is relative to `/api`; a leading `/` or `api/` is accepted.
+`<path>` is relative to `/api`; a leading `/` or `api/` is accepted. One
+exception: `customer-apps/…` is sent as written, because `/customer-apps/<org>/<app>/…`
+is where an app's bundle is served. The app registry API is `api/customer-apps/…`
+— spell the `api/` out for it (a 404 on the bare form says so).
 
 | Flag | Meaning |
 | --- | --- |
@@ -111,9 +116,10 @@ the server.
 `oxyc login`; `/external/api/**` sends `X-API-Key` from `$OXY_API_KEY`.
 
 **`--paginate` is a heuristic.** Oxy sends `Link: rel="next"` on some endpoints
-and nothing on others; where there is no header, `oxyc` reads
-`pagination.has_next`, then `has_more`, then `page < total_pages`. Nothing
-recognised means one page, and it warns when the server said nothing at all.
+and nothing on others; where there is no header, `oxyc` reads `next_offset`
+(and asks again with `?offset=`), then `pagination.has_next`, then `has_more`,
+then `page < total_pages` (asking again with `?page=`). Nothing recognised
+means one page, and it warns when the server said nothing at all.
 
 ```bash
 oxyc api {org}/workspaces --md
@@ -181,6 +187,8 @@ Staff can see and request an org's transactional Postgres — the store behind
 ```bash
 oxyc oltp status [--org <slug|uuid|url>] [--json]
 oxyc oltp provision --org <slug|uuid|url> --writer app:<slug> [--writer pipeline:<source> …] [--yes] [--json]
+oxyc oltp provision --org <slug|uuid|url> --branch staging [--yes] [--json]
+oxyc oltp reset --org <slug|uuid|url> --branch staging [--yes] [--json]
 ```
 
 `status` lists every org, with a database or without; with `--org` it shows
@@ -194,6 +202,15 @@ derived the way the platform derives `ctx.oltp`'s schema (`app:store-ops` →
 `raw_<source>`. A 404 can be an org outside your staff grant's scope, and an
 active `assume` session closes `/admin`.
 
+`--branch staging` also cuts the org's **staging branch**: one copy of the whole
+database per org, which every app's staging environment writes to. It is made
+only by this flag — never by a publish — and re-running it mints whatever a
+writer added since the cut needs, without resetting anyone's data. `status`
+shows its age and calls it stale past 30 days; nothing resets it on a timer.
+`reset --branch staging` re-copies it from production, discarding every app's
+staging data in the org, so it lists those apps and asks first (`--yes`
+without a terminal).
+
 ## Customer workspaces
 
 A customer **is** a GitHub repo carrying the `oxy-customer` topic. Tagging the
@@ -225,7 +242,7 @@ the current directory while granting access to the customer's repo.
 ## Custom apps
 
 ```bash
-oxyc publish [--env <e>] [--dir <path>] [--promote] [--build-only | --prebuilt] [--json] [--allow-function-lint]
+oxyc publish [--env <e>] [--dir <path>] [--promote] [--build-only | --prebuilt] [--json] [--allow-function-lint] [--app-env <dev-handle>]
 oxyc init-ci [--app <org>/<app>] [--environment <name>] [--force]
 oxyc proxy [--port <n>] [--allow-writes] [--allow-events] [--yes]
 ```
@@ -277,6 +294,104 @@ OIDC. `--promote` makes that publish go live and adds a `checks run` step after
 it, when the manifest declares a check. It prints the `oxyc api …/publishers`
 call that registers the workflow.
 
+**`--app-env <dev-handle>`** moves one sandbox's build pointer instead of the
+draft/live channel — see [Sandboxes](#sandboxes). It needs a staff credential
+(never a publish token or OIDC) and is refused together with `--promote`: a
+sandbox build is never promoted, so the loop is publish to the sandbox,
+iterate, then publish the same tree to staging and promote that.
+
+## Apps
+
+Read-only: every request these make is a GET, against `/api/customer-apps/**`
+(the app-admin role). `<app>` is `<org-slug>/<app-slug>` or an app UUID.
+
+```bash
+oxyc apps list [--org <slug>] [--published | --draft] [--builds] [--json]
+oxyc apps show <app> [--json]
+oxyc apps builds <app> [--json]
+oxyc apps health [<app>] [--needs-attention] [--json]
+oxyc apps usage <app> [--json]
+oxyc apps drift [<app>] [--org <slug>] [--dir <path>] [--refresh] [--json]
+```
+
+- **`list`** — every app you can see, across organizations, walking the paged
+  registry to its end. `STATE` is `live` when the app has a published build and
+  `draft` when it has none. `SOURCE` is the repository the app is *registered*
+  against. `--builds` adds the live build's id, the repository and commit it was
+  built from, who published it and when — one extra request per app, six at a
+  time.
+- **`show`** — one app on one screen: the registry row, the live build, the
+  draft build when it is newer than the live one, deployment integrity,
+  availability, and the 7-day usage summary. `last promote` is when the promote
+  or rollback action was last used; `oxyc publish --promote` does not update it,
+  so it can be older than the live build.
+- **`builds`** — the build history, newest first. `CHANNEL` marks the build each
+  channel points at: `live`, `draft`, or both for one build.
+- **`health`** — with no argument, the fleet table (published apps only):
+  `down`, `degraded`, `not_measured`, `quiet` or `operational` per app, with the
+  totals on stderr. `--needs-attention` keeps the first three. With `<app>`: the
+  deployment-integrity checks, the availability windows, and the browser errors
+  of the last 24 hours.
+- **`usage`** — the 7-day summary, the visitors, and the tracked events by name.
+- **`drift`** — see below.
+
+Times are UTC. `--json` prints one document on stdout; a table goes to stdout and
+the count line to stderr.
+
+**An empty result and a failed request are different answers.** No apps, no
+builds, no errors recorded: the command says so and exits `0`. A request that
+failed exits with the code its status maps to (`4`, `5`, `7`, …). Where a
+command makes several independent requests (`show`, `health <app>`,
+`list --builds`, `drift`), it prints what it did read, marks what it did not as
+`NOT READ` (`"failed": […]` / `live_build_error` in `--json`), and then exits
+non-zero. These commands report state: a failing health check, a `down` app or
+a drifted app is an answer and exits `0` — read it from the output.
+
+The health route answers **503 with its report** when a check fails; `oxyc`
+prints that as a failing report, not as an outage.
+
+### `apps drift`
+
+Compares what is live against source on **this machine**. For each app it takes
+the live build's recorded repository and commit, finds a local checkout of that
+repository (the ones `oxyc repos` and `oxyc path` report, or `--dir`), finds the
+app's directory by the `oxy-app.json` whose `slug` and `orgSlug` match — at
+`<app>/oxy-app.json` or `<app>/public/oxy-app.json`, never by folder name — and
+counts the commits on the checkout's **current branch** that touch that
+directory after the published commit.
+
+| Result | Meaning |
+| --- | --- |
+| `in sync` | no commit on the current branch touches the app directory after the published commit |
+| `N commits ahead` | that many do; they are listed |
+| `unknown — <reason>` | the comparison could not be made |
+
+`unknown` is never reported as `in sync`. Its reasons (`reason` in `--json`):
+
+| `reason` | |
+| --- | --- |
+| `not_published` | nothing is live |
+| `source_unrecorded` | the live build records no repository or no commit |
+| `repo_not_checked_out` | the repository is not on this machine — clone it, or pass `--dir` |
+| `commit_not_in_checkout` | the checkout does not have the published commit — `git fetch` there |
+| `app_dir_not_found` | no tracked `oxy-app.json` declares this `slug` and `orgSlug` |
+| `app_dir_ambiguous` | more than one does |
+| `commit_not_on_branch` | the published commit is not an ancestor of the checked-out branch |
+| `working_tree_dirty` | the app directory has uncommitted or untracked files |
+| `git_failed` | `git log` or `git status` failed in the checkout, so the comparison could not be read |
+| `request_failed` | the builds request failed (the command then exits non-zero) |
+
+It runs read-only git commands and nothing else: it does not fetch, check out,
+or refresh the index. The answer is therefore about the checkout as it is on
+disk — a branch that is behind its remote reports fewer commits than the remote
+has. With no `<app>`, every published app is compared, and `--dir` applies to
+the apps whose source repository is that checkout's `origin`; with `<app>`,
+`--dir` is used whatever its remote is.
+
+An app published to two organizations from one directory (a staging org and a
+production org) matches the manifest for only one of them; the other reports
+`app_dir_not_found` and names the manifest it found with the other `orgSlug`.
+
 ## Checks
 
 ```bash
@@ -331,7 +446,12 @@ it admitted any function.
 the execution alike. So `checks run` after a plain `oxyc publish` verifies the
 *previously promoted* code, not the draft just uploaded. `oxyc init-ci` writes
 the step only with `--promote`, where the build just published is the one the
-check runs, and only when the manifest declares a check.
+check runs, and only when the manifest declares a check. **With `--app-env`**
+it runs against that environment's own build instead — a sandbox's own
+publish, or staging's — and the report gains `environment` and each check's
+`invocationId`; the publish-token and OIDC paths are unchanged and work only
+against production, since every non-production operation needs a staff
+credential (see [Sandboxes](#sandboxes)).
 
 With a publish token, `<app>` must be the **UUID** — resolving a slug means
 listing every app, which such a token may not do. The OIDC path needs no id at
@@ -346,6 +466,119 @@ expired 90-day API key reads this way, not as a missing one); `2` a bad
 the deployment answered the OIDC exchange without an `app_id`, meaning it
 predates trusted checks.
 
+## Sandboxes
+
+```bash
+oxyc env create <app> <name>                 # name is dev-<handle>, 1-12 chars a-z0-9-
+oxyc env list <app>
+oxyc env show <app> <name>
+oxyc env delete <app> <name> [--yes] [--wait [seconds]]
+
+oxyc publish --app-env <name> [--env <e>]    # see "Custom apps" above
+oxyc fn call <app> <function> [--app-env <name>] [--data <json|@file|->]
+oxyc checks run <app> --app-env <name>       # see "Checks" above
+
+oxyc invocations list <app> [--app-env] [--build] [--function] [--limit]
+oxyc invocations held <app> <invocation-id>
+oxyc logs <app> [--app-env] [--invocation] [--request] [--hours] [--limit]
+```
+
+A **sandbox** is a named, short-lived `dev-<handle>` environment of one custom
+app: its own build pointer, storage silo, secrets, Airhouse sibling and — in
+an org with an OLTP staging branch — its own copy of the app's database, with
+reads hitting production and most writes either isolated or *held* (recorded,
+not performed — see `invocations held`). It starts with no build, is deleted
+explicitly or after 7 idle days, and an app has at most 20. Full contract,
+including what is **not** isolated (`ctx.warehouse`) and the other gaps:
+`internal-docs/custom-app-sandboxes.md`.
+
+`ctx.oltp` in a sandbox runs in a schema of its own (`app_<app>__dev_<handle>`)
+inside the org's staging branch. `publish --app-env` queues it: a copy of
+staging's tables (rows up to a size cap), then the build's OLTP migrations.
+`env show` reports it as `oltp_schema` — `status` is `seeding`, `ready`,
+`failed` (with `error`) or `stale` (the branch was reset; publish again), and
+`structure_only` lists the tables copied empty. Until it is `ready` a
+`ctx.oltp` call in the sandbox is refused with a message that says which.
+
+The loop: `env create` → `publish --app-env` → `fn call` / `checks run
+--app-env` → `invocations list` / `held` to read back what ran → iterate from
+`publish` → `env delete --yes --wait` when done. `oxyc guide` has the same six
+lines, meant to sit in an agent's context.
+
+**`--app-env <environment>`** (`production`, `staging` or `dev-<handle>`,
+validated client-side — exit `2` on a malformed name) is a *different axis*
+from `--env`, which is the deployment: both can appear on the same command
+(`oxyc fn call acme/store f --env dev --app-env dev-a1`). It is not a global
+flag — only `publish`, `fn call`, `checks run`, `invocations list` and `logs`
+take it. A publish-token credential is refused before any request for
+`--app-env` other than `production` (exit `2`); `env`, `invocations` and
+`logs` refuse one outright, for any environment, because sandbox management
+is a staff console surface.
+
+**`env delete`** without `--yes` asks on a terminal and exits `8` (refused)
+off one, same as `oltp reset`. `--wait [seconds]` (default 120) polls until
+the teardown finishes and prints `{"name","status":"deleted"}`; past the
+deadline it exits `7` (retryable) rather than hanging.
+
+**`fn call`** POSTs directly to `{target}/customer-apps/{org}/{app}/fn/{name}`
+(no `/api`) — the response is Server-Sent Events, not JSON, so `oxyc` parses
+the `log` / `data` / `done` / `error` frames itself. It exits `0` only when
+the stream ends `done` with a 2xx status; a function that threw, or answered a
+non-2xx, is a function-level failure (exit `1`, `ok: false` in the JSON), kept
+distinct from a non-2xx on the POST itself (exit per the usual status mapping
+— e.g. `EnvironmentHasNoBuild` before the stream starts). The
+`x-oxy-invocation-id` response header becomes `invocationId` in the result.
+
+**`invocations held`** is what the non-production write policy did *not* do —
+production's would-be effect, recorded rather than performed. It is `[]` for a
+production invocation, since nothing is held there.
+
+## Workspace previews
+
+```bash
+oxyc preview create <branch> [--wait [seconds]] [--json]
+oxyc preview list [--json]
+oxyc preview show <branch> [--json]
+oxyc preview delete <branch> [--yes] [--json]
+oxyc preview checks <branch> [--json]
+
+oxyc preview run <branch> <kind> <ref> [--variables <json|@file|->] [--read-live-only]
+                  [--window-from <iso>] [--window-to <iso>] [--resource <name>...]
+                  [--wait [seconds]] [--json]
+oxyc preview runs list <branch> [--json]
+oxyc preview runs show <run-id> [--wait [seconds]] [--json]
+```
+
+A **preview** opens a workspace branch on the real product, against real data,
+without the branch being live — staff only. `create` compiles the branch's
+head into a staging revision (or reuses a ready one for that commit) and is
+idempotent; `--wait [seconds]` (default 120) blocks until the compile is
+`ready` or `failed` instead of returning the `compiling` item the request
+itself answers with, and exits `7` (retryable) past the deadline. There is no
+single-preview route: `show` fetches `list` and filters it client-side, so its
+`5` (not found) is synthesized here, not a literal 404.
+
+The loop: `preview create --wait` → `preview checks` → `preview run` →
+`preview runs show --wait` → iterate → `preview delete --yes` when done.
+
+**`<kind>`** is `procedure` or `airway_sample` — the only two `POST
+/previews/runs` accepts (exit `2` client-side on anything else, naming the
+read-back verb). `transform_build` and `compare` runs are queued by the
+server's own Airway change check, never started here; `preview runs list`
+surfaces them alongside the kinds you *can* start, and `preview runs show
+<run-id> --wait` reads any of the four back — a procedure's held steps, a
+transform build's or compare's outcome, or a sample's ask and result.
+`--variables` / `--read-live-only` are `procedure`-only; `--window-from` /
+`--window-to` / `--resource` (repeatable) are `airway_sample`-only.
+
+Every verb needs `{workspace}` resolved — `--workspace <id>`, exactly the way
+`oxyc api {workspace}/...` resolves it; there is no second workspace
+resolver. A deployment with `OXY_PREVIEW_RUNS` off answers every runs route
+`404 preview_runs_disabled`, surfaced the same way any other server refusal
+is: the server's own `code` rides along on the thrown error, and the exit
+class follows the usual HTTP-status mapping (`400`/`409` → `6`, `404` → `5`).
+Full contract: `internal-docs/workspace-previews.md`.
+
 ## Development commands
 
 ```bash
@@ -424,9 +657,22 @@ production target (any host under `oxygen-hq.com`) is refused without `--yes`.
 Each Oxy Function call carries a W3C trace — the SDK's, or one minted here — and
 prints `↳ <status> fn <name>  request_id=…  trace_id=…`.
 
-**`mcp`** serves the API over stdio as four tools — `oxy_routes`, `oxy_schema`,
-`oxy_request`, `oxy_whoami` — rather than one per endpoint, so the tool schemas
-cost ~2 KB per turn and reach endpoints added after this package shipped.
+**`mcp`** serves the API over stdio as four generic tools — `oxy_routes`,
+`oxy_schema`, `oxy_request`, `oxy_whoami` — rather than one per endpoint, so
+those schemas cost ~2 KB per turn and reach endpoints added after this
+package shipped. Two named exceptions trade that minimalism for validation an
+agent needs to drive a loop unsupervised: the **sandbox loop**
+(`oxy_env_create`/`list`/`show`/`delete`, `oxy_publish_sandbox`,
+`oxy_fn_call`, `oxy_checks_run`, `oxy_invocations_list`/`held`, `oxy_logs`)
+and **workspace previews** (`oxy_preview_create`/`list`/`show`/`delete`/
+`checks`/`run`/`runs_list`/`run_show`). Each tool calls its CLI verb's own
+request-building function, so a tool's result is the same JSON document that
+verb's `--json` prints, and a failure carries the server's own error code
+plus the exit-code class (`[exit 5 NOT_FOUND]`) the way `oxyc`'s exit code
+would. `oxy_env_delete` / `oxy_preview_delete` need `confirm: true` (there is
+no terminal to ask on inside an MCP server), and `oxy_publish_sandbox`
+requires a `dev-<handle>` `appEnv` and refuses production, staging or a
+promote client-side — it can never reach the live channel.
 
 ```bash
 claude mcp add oxyc -- npx -y @oxy-hq/cli mcp --env production