@oxy-hq/cli 0.4.0 → 0.5.0

package/README.md

@@ -3,9 +3,10 @@
 `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`, `assume`
+- **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`
+- **Checks** — `checks run`
 - **Development** — `validate`, `mcp`, `guide`, `skills`
 
 ## Install
@@ -172,6 +173,27 @@ it and `end` ends it in both. A staff 403 on a tenant surface is usually no
 active session rather than a role problem; `assume status` answers "none"
 without failing.
 
+## OLTP databases
+
+Staff can see and request an org's transactional Postgres — the store behind
+`ctx.oltp` — without a shell on the server.
+
+```bash
+oxyc oltp status [--org <slug|uuid|url>] [--json]
+oxyc oltp provision --org <slug|uuid|url> --writer app:<slug> [--writer pipeline:<source> …] [--yes] [--json]
+```
+
+`status` lists every org, with a database or without; with `--org` it shows
+that org's store and writers. No credential is ever printed.
+
+`provision` prints what it will create and asks first, because it calls a paid
+provider; without a terminal it refuses unless `--yes`. It is idempotent — an
+existing database or writer is reconciled, not duplicated. `app:<slug>` is
+derived the way the platform derives `ctx.oltp`'s schema (`app:store-ops` →
+`app:store_ops`, schema `app_store_ops`); `pipeline:<source>` names
+`raw_<source>`. A 404 can be an org outside your staff grant's scope, and an
+active `assume` session closes `/admin`.
+
 ## Customer workspaces
 
 A customer **is** a GitHub repo carrying the `oxy-customer` topic. Tagging the
@@ -203,7 +225,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]
+oxyc publish [--env <e>] [--dir <path>] [--promote] [--build-only | --prebuilt] [--json] [--allow-function-lint]
 oxyc init-ci [--app <org>/<app>] [--environment <name>] [--force]
 oxyc proxy [--port <n>] [--allow-writes] [--allow-events] [--yes]
 ```
@@ -236,11 +258,93 @@ channel unless `--promote`. `--env` defaults to **production**; name it.
 - `.env.local`, then `.env`, are read from the directory and its parents without
   overriding the environment. The server's warnings print on stderr; `--json`
   prints its result on stdout.
+- **Function lint**: before the build, each declared function's source (and the
+  relative imports it reaches) is checked for what the host refuses at the first
+  call — a `ctx.*` call whose capability the manifest lacks, a global the isolate
+  does not have, a `ctx.warehouse` / `ctx.tx` write outside `destinations`; before
+  the upload, with the target's database list, an `upsert` or `ctx.tx` on an
+  engine that refuses it and a customer-warehouse write with no
+  `customerWarehouseWrites` reason. The rules are `validate`'s, below. A finding
+  fails the publish with exit `1` and names the file, line, call and fix; if the
+  target will not list the databases, the engine half prints one warning and is
+  skipped. **`--allow-function-lint`** is the way past a false positive: every
+  finding becomes a warning that names its rule — please open an issue with it.
 
 **`init-ci`** writes `.github/workflows/oxy-publish.yml` at the repo root: a
 `build` job (no id-token) that runs `publish --build-only`, and an
 environment-gated `publish` job whose only work is `publish --prebuilt` with
-OIDC. It prints the `oxyc api …/publishers` call that registers the workflow.
+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.
+
+## Checks
+
+```bash
+oxyc checks run <org-slug>/<app-slug>   # or an app UUID
+oxyc checks run acme/dashboards --json --timeout 60
+```
+
+Runs every function the app declared `"check": true` (in `oxy-app.json`), one
+POST per check to start its run, then polls each run to a terminal status —
+`done`, `failed`, `cancelled`, or a client-side `timed_out` past `--timeout`
+seconds (default 300, per check). A check **passes** when its run finishes
+`done` and its answer does not parse to an object with `ok: false`.
+
+Human mode prints one line per check to stderr as it lands (`✓ canary 4.1s` /
+`✗ canary failed: <reason>`), suppressed by `--quiet`. `--json` prints one
+object to stdout instead:
+
+```json
+{ "app": "acme/dashboards", "appId": "…", "checks": [{ "name": "canary", "runId": "…", "status": "done", "passed": true, "durationMs": 4123 }] }
+```
+
+**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
+`X-API-Key` only when **no bearer resolves** — never both. A bearer from
+`oxyc login` (or `--token-env`) always wins when one is present.
+
+**In CI, nothing is stored.** With neither a token nor an API key set, a job
+holding `id-token: write` exchanges its GitHub OIDC token for the same
+short-lived, app-scoped publish credential `oxyc publish` uses, and drives
+`/api/customer-apps/**` instead — the same three handlers, mounted where a
+publish token may reach them. The exchange returns the app id, so no lookup is
+needed, and `<app>` must be `<org-slug>/<app-slug>` in this mode (a UUID names
+an app the exchange cannot verify a publisher for). A publish token set in
+`OXY_TOKEN` takes the same surface without minting.
+
+What that credential may do is deliberately small, and enforced server-side
+rather than by the client. An app-scoped token is **confined to its app**: it
+reaches `/customer-apps/{its own id}/…` and the upload, and answers `404` for
+everything else on that surface — another app's id, the registry listing, and
+the fleet-wide rollups. That is the same answer an out-of-scope App Operator
+gets, so it cannot learn which apps exist. Within its app it may publish, read,
+and run a function **the manifest marks `"check": true`**; a function without
+the flag is `403`. The
+argument for allowing the run at all is narrow: a token that may publish
+arbitrary code to an app can already cause anything that app can, so running
+that app's own declared checks adds nothing. It would stop being true the moment
+it admitted any function.
+
+**A check runs against the app's live build** — the server resolves
+`published_build_id`, else `draft_build_id`, for the pre-flight lookup and for
+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.
+
+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
+all (the exchange returns it) but does need `<org-slug>/<app-slug>`, since the
+exchange is registered by slug.
+
+**Exit codes:** `0` every check passed; `9` (`CHECK_FAILED`) at least one check
+failed or timed out; `1` the app declares no checks; `5` the app was not
+found; `4` no credential resolved, or the API rejected it (401/403 — an
+expired 90-day API key reads this way, not as a missing one); `2` a bad
+`--timeout`, or a slug where the credential needs a UUID; `7` (`UNAVAILABLE`)
+the deployment answered the OIDC exchange without an `app_id`, meaning it
+predates trusted checks.
 
 ## Development commands
 
@@ -267,6 +371,51 @@ generated from the Rust config types. No network, no token.
 Structural checks only. `oxy validate` additionally resolves `databases:` and
 `llm.ref` against the loaded workspace, and wins where the two disagree.
 
+Every **`oxy-app.json`** it finds is checked for data placement — the shape of
+the data picks the store: facts and history in Airhouse (`ctx.airhouse`),
+records in OLTP (`ctx.oltp`), files in `ctx.storage`, customer warehouses
+read-only. These fail the run:
+
+- `customerWarehouseWrites` that is not `{ "<database>": "<reason>" }`, or names
+  a database missing from the function's `destinations`;
+- `"airhouse": { "enabled": true }` in an app whose slug cannot derive a writer
+  (`-` → `_`, 1–56 of `[a-z0-9_]`, starting with a letter; no `_` in the slug);
+- `airhouseMigrations` without a `dir`, with one that does not exist, or with
+  `migrations.dir`'s; and in its `*.sql`, `PRIMARY KEY`, `UNIQUE`,
+  `CREATE INDEX`, `REFERENCES` or `FOREIGN KEY` (DuckLake has none), or a
+  `CREATE`/`ALTER`/`DROP`/`INSERT`/`UPDATE`/`DELETE`/`COMMENT ON` target not
+  written as `app_<writer>.<name>`.
+
+Warnings print on stderr and do not fail: each customer-warehouse exception,
+`CREATE SCHEMA` in a migration, and `ctx.secrets.set` holding state (a
+`JSON.stringify` value, or a state-like key that is not a credential's). The SQL
+checks are lexical; the server's parser is the authority.
+
+Each declared **Oxy Function** is then linted — its entry and every relative
+import it reaches, comments and strings masked — for the mistakes that work
+locally and fail closed in production. These fail the run, each naming the
+file, the line, the call and the fix:
+
+- `capability` — a `ctx.<area>.<op>` call whose manifest capability the function
+  does not declare: `ctx.secrets.set` → `secrets.write`, `ctx.email.send` →
+  `email.send`, `ctx.org.*` → `org.read`, `ctx.storage.*` → `storage.read` /
+  `storage.write` (`copy` needs both), `ctx.oltp.*` → `oltp.enabled`,
+  `ctx.airhouse.*` → `airhouse.enabled`. The map is
+  `src/publish/capabilities.ts`, held to the host's `FunctionCapabilities` by a
+  Rust test.
+- `isolate-global` — a value use of `Buffer`, `TextEncoder`, `TextDecoder`,
+  `Blob`, `File`, `FormData`, `crypto.subtle` or `process.*`: the isolate is bare
+  `deno_core` and each is a `ReferenceError` at runtime. A name the file declares
+  itself (`const Buffer = …`, `import { TextEncoder } from "./polyfill"`) is not
+  one; nor is a `typeof` guard or a type annotation.
+- `destinations` — a `ctx.warehouse.insert` / `exec` / `upsert` or `ctx.tx` in a
+  function with no `destinations`, or naming a database not in them.
+
+The engine half — `upsert` off Postgres / DuckDB, `ctx.tx` off Postgres, a
+customer-warehouse write with no `customerWarehouseWrites` reason, a write to
+the org's OLTP store — needs the database list, which only the server has;
+`validate` says so and `oxyc publish` runs it before the upload.
+
 **`proxy`** forwards a local dev server's Oxy calls to a cloud target with your
 login token attached. Defaults: side-effecting calls are **held**, tracking
 events are **dropped**, auth endpoints reach the backend unauthenticated so
@@ -299,6 +448,7 @@ once npm reclaims it.
 6  the request was malformed (4xx other than 401/403/404)
 7  unavailable — 5xx, a timeout, or the network failed. Retryable.
 8  refused — the operation would have destroyed or overwritten something
+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.