Repository navigation
Conversation
|
/ai-review |
There was a problem hiding this comment.
Superseded by a newer AI review
🤖 AI Review
Verified all 8 Claude and 5 Codex findings against the PR code and trusted conventions, merging two duplicate pairs into 11 confirmed findings. The main issues concern machine-error rendering, error classification, sensitive previews, overlapping result schemas, and generator/runtime mismatches. Generator and sensitive-field gaps are latent for the current warehouse entries. Newline handling, telemetry documentation, and E2E delay are polish concerns. The unlinked-project message still contains the link guidance, correcting an overstatement in Claude's finding.
Findings
| Severity | Location | Category | Sources | Claim |
|---|---|---|---|---|
| 🟠 MAJOR | apps/cli/src/shared/cli/run.ts:861 |
error-handling |
codex | Standard failures ignore agent-selected machine output. A TTY invocation with --agent=yes can resolve to JSON output but receive a human-text failure instead of the standard error document. |
| 🟡 MINOR | apps/cli/src/shared/cli/standard-errors.ts:174 |
error-handling |
claude | The standard error mapper misclassifies target-resolution failures as internal_error with exit 1 and hint:null. Project-not-linked and invalid-link-state errors bypass the InvalidInput-only usage mapping; wrapped branch network/status errors also bypass the HTTP mappings. |
| 🟡 MINOR | apps/cli/src/command-internal/command-surface/command-surface.ts:213 |
schema-contract |
codex | The result schema's oneOf rejects valid warehouse documents that satisfy both the accepted-response and waited-response schemas. |
| 🟡 MINOR | apps/cli/src/commands/api/api-command-request.ts:226 |
redaction |
claude+codex | For a generated body field marked sensitive, supplying its value solely through --body or --file bypasses dry-run masking. |
| 🟡 MINOR | apps/cli/scripts/api-command-derive.ts:458 |
correctness |
claude | The generator accepts operations without a ref path parameter even though the runtime always supplies ref. A generated operation whose input schema has no ref field then fails strict input decoding. |
| 🟡 MINOR | apps/cli/src/commands/api/runtime.ts:245 |
command-generation |
claude+codex | The generator accepts nested noun paths that the runtime silently omits when constructing command groups. |
| 🟡 MINOR | apps/cli/src/commands/api/api-command.errors.ts:40 |
telemetry |
claude | Operation failures and wait timeouts are classified as invalid user input in telemetry even though they arise after a valid request has been sent. |
| ⚪ NIT | apps/cli/scripts/api-command-derive.ts:350 |
correctness |
claude | Wait-schema lookup rejects +json response media types that the generator otherwise supports as JSON. |
| ⚪ NIT | apps/cli/src/commands/api/api-command-execute.ts:155 |
output |
claude | JSON response passthrough emits no trailing newline when the API body lacks one, leaving terminal output and line-oriented consumers with an unterminated final line. |
| ⚪ NIT | apps/cli/src/commands/api/warehouse/enable/SIDE_EFFECTS.md:70 |
docs |
claude | The telemetry documentation incorrectly says only target and runtime flag names appear in flags. Generated flags, body, and file also appear as redacted entries, and timeout's value is redacted. |
| ⚪ NIT | apps/cli/src/commands/api/api-commands.e2e.test.ts:162 |
test-quality |
codex | The subprocess wait test incurs a real one-second polling delay for a transition already covered by controlled-clock tests. |
Stats
Claude findings: 8 · Codex findings: 5 · Confirmed: 11 · Refuted: 0 · Uncertain: 0
Models: claude-opus-5-5 + gpt-6.1-sol · Trigger: manual · Workflow run
This review runs once per PR. A maintainer can request another with a /ai-review comment.
Generated Management API commands now take their names and polling behaviour from an `x-operation` extension and standard response `links` in the OpenAPI spec. Secrets are marked on the field, and flags follow a naming convention. The CLI keeps the noun allowlist, the verb vocabulary and an override table, which is empty today.
Only operations listed in generatedOperations generate commands. x-operation on any other operation is ignored until the spec metadata design settles.
- Agent runs on a terminal report failures as the standard JSON document. - Unlinked-project and branch-resolution failures map to usage, network and API error codes instead of internal_error. - Operation-failed and wait-timeout errors classify as API status. - --dry-run masks sensitive fields supplied through --body or --file. - Result schemas combine branches with anyOf. - Generation rejects nested groups and operations without a ref path parameter, and reads +json success schemas for wait pointers. - SIDE_EFFECTS telemetry wording matches what is recorded.
|
/ai-review |
There was a problem hiding this comment.
🤖 AI Review
Verified all three findings against the checked-out code and trusted conventions. Both Codex findings are confirmed as minor correctness issues; Claude's missing-newline finding is confirmed as a formatting nit. No findings overlap.
Findings
| Severity | Location | Category | Sources | Claim |
|---|---|---|---|---|
| 🟡 MINOR | apps/cli/src/commands/api/api-command-execute.ts:101 |
error-handling |
codex | Generated commands discard plan-gate entitlement metadata, losing upgrade guidance, structured entitlement details, and the associated telemetry. |
| 🟡 MINOR | apps/cli/scripts/api-command-derive.ts:384 |
correctness |
codex | Wait validation rejects valid JSON Pointers containing escaped property names. |
| ⚪ NIT | apps/cli/src/commands/api/api-command-execute.ts:155 |
output-consistency |
claude | JSON success responses without a trailing newline leave stdout unterminated, unlike dry-run previews and text or empty responses in JSON mode. |
Stats
Claude findings: 1 · Codex findings: 2 · Confirmed: 3 · Refuted: 0 · Uncertain: 0
Models: claude-opus-5-5 + gpt-6.1-sol · Trigger: manual · Workflow run
This review runs once per PR. A maintainer can request another with a /ai-review comment.
…ator Generated commands gain nested groups, one positional argument, header flags, action verbs, file-only body fields and reads that poll themselves, so `warehouse status --wait` waits for a final status. The generator rejects what the runtime cannot send safely: a secret held at any depth of a body field without a masked flag, secret header or query parameters, non-string positionals, nullable wait pointers and link expressions other than the project ref and response pointers. The runtime rejects an empty or dot-segment positional before any request. The command surface moves under `src/cli`, and the shared API command errors and stage annotation move under `src/command-internal`. The command policy replaces the override table, and the dry-run preview lists headers.
…generated commands Generated commands now parse the Management API entitlement_required body on a 4xx, carry the entitlement in the standard error document, print the upgrade hint in text mode, and fire cli_upgrade_suggested. The generator decodes ~1 and ~0 in --wait link pointers the same way the runtime does.
Add generated `warehouse disable` and `warehouse teardowns get` commands with explicit `--delete-data`, bounded waiting, and the existing Warehouse feature gate. Retain data by default, poll the accepted cleanup identity, and include the last observed lifecycle state in timeout errors. Reuse shared targeting, consent, output, and error handling. `warehouse teardowns get` reads current cleanup without an ID. Optional `--operation-id` pins observation; `warehouse disable --wait` supplies its ID automatically. Stacks on #7640. Depends on supabase/platform#42016. Implements PIPE-1447. Keeps the local request-preview contract; resolved impact previews remain follow-up work.
Generate `warehouse status` from `GET
/v2/projects/{ref}/warehouse/status`, preserving readiness,
capabilities, zero-target enablement and unavailable observations
through the shared runtime.
Preserve `warehouse enable --wait` with selection-bound setup polling.
Discover internal polling targets from response links without exposing a
`warehouse setups get` command; status has no wait flags. Retain
teardown waiting.
Keep text output on terminals, raw JSON when piped or requested, and
YAML through `-o yaml`.
Stacked on #7640 (including merged #7660). Depends on
supabase/platform#42039.
Implements PIPE-1445.
---------
Co-authored-by: Julien Goux <hi@jgoux.dev>
Generate `warehouse connection` from `GET
/v2/projects/{ref}/warehouse/connection`. It prints the Arrow Flight SQL
endpoint, the TLS requirement and source-database login guidance: use a
database role with its existing password (`postgres` uses the project's
database password) and `supabase_warehouse_reader` membership. The
command never fetches or prints a password, and a disabled, unconfigured
or unavailable Warehouse shows no connection string.
Text output on terminals, raw JSON when piped or requested, and YAML
through `-o yaml`, as for the other generated Warehouse commands. Help
includes a usql recipe.
Add `connection` to the generated command vocabulary and render `TLS` as
an acronym in text labels. The contract comes from an OpenAPI override
until it ships in the deployed Management API specification.
Stacked on #7671. Depends on
supabase/platform#42053.
Implements PIPE-1449.
---------
Co-authored-by: Julien Goux <hi@jgoux.dev>
Drive the experimental gate for generated command groups from the policy nouns instead of a warehouse-specific resolver, and replace the per-command warehouse SIDE_EFFECTS docs with a shared contract plus a generated per-command reference kept in sync by the generator check.
Summary
Adds the first commands generated from the Management API spec, for Warehouse:
supabase warehouse enablestarts replication and can--waitfor setup to finish;supabase warehouse disablestarts cleanup and can--waitfor it to finish;supabase warehouse statusreads the consolidated Warehouse status;supabase warehouse connectionreads the Arrow Flight SQL connection details;supabase warehouse teardowns getreads the current cleanup, and can--waiton it.They are experimental and hidden unless the project opts in, in the same way as
compute:or
SUPABASE_EXPERIMENTAL_WAREHOUSE=1in the shell.The goal is to settle the full pipeline on one real resource before adding more. That pipeline covers:
x-operationandlinks) → generated data;New commands should then need only an
x-operationentry in the spec. The generator and runtime already cover more shapes than Warehouse uses today: one positional argument, header flags, and body fields set only through--body/--file. Fixture specs exercise them in tests, so the next resources shouldn't need runtime changes. This is an alternative to the hand-writtenwarehouse enablein #7528.How it works
The generator writes data, not code. A build-time script turns the OpenAPI spec plus a small CLI policy file into two committed data modules and a generated per-command reference. At startup, one generic runtime builds real Effect CLI commands from that data. There is no per-command handler code.
flowchart LR subgraph build["Build time: pnpm generate / api-commands:check"] spec["packages/api<br/>openapi.json + typed client"] policy["api-command-policy.ts<br/>(allowlist, poll targets, nouns, verbs)"] gen["scripts/generate-api-commands.ts<br/>derive + lints"] data["generated.ts<br/>(command data)"] schemas["generated.schemas.ts<br/>(JSON Schemas)"] ref["generated.md<br/>(per-command reference)"] spec --> gen policy --> gen gen --> data gen --> schemas gen --> ref end subgraph run["Runtime"] rt["runtime.ts<br/>apiCommandGroup()"] root["cli/root.ts<br/>mounts each noun whose feature is enabled"] exec["request → send → --wait → output"] errs["errors.standard envelope"] data --> rt --> root rt --> exec --> errs end subgraph contract["Contract extraction"] surface["commandSurface()<br/>walks the mounted tree"] root --> surface schemas -. lazy import .-> surface endWhy committed data instead of resolving the spec at runtime
api-commands:checkis part ofcheck:all.api-package-sync.ymlregenerates the data and the reference whenever it syncs the spec, so drift turns up as a reviewable diff.Adding a command
A command is declared in the spec itself. The CLI keeps a small policy file: a temporary allowlist of generated operations, the nouns and the verb vocabulary. It has no per-command overrides and no per-command folder.
A command for an existing noun takes two edits: its
x-operation(andlinksfor--wait) in the spec, and its operation ID ingeneratedOperations.pnpm run generatewrites the rest. A new noun is onenounsentry; a noun with its own feature also needs thatexperimental.<feature>config key, whichApiNoun.featureenforces at type-check time.In the spec:
x-operationon an operation names its command. Only operations on the CLI allowlist generate a command;x-operationelsewhere is ignored, except on a hidden poll target (see below), where only itspollis used.group"warehouse"→supabase warehouse …"warehouse.tables"→supabase warehouse tables …methodgroup, the whole path is at most 4 lowercase kebab-case words."enable"→supabase warehouse enablepoll--waitand--timeout.The extension is decoded strictly: an unknown key fails generation. It holds only what another consumer of the spec (for example an MCP server generating tools) would also need. CLI-only choices such as flag names stay in the CLI. Its name and ownership will be agreed with the API owners before it moves upstream; until then the warehouse entries live in
openapi-overrides.json.pollfields:status"/data/attributes/status"succeeded["succeeded"]failedoperation_failed(exit 1).["failed"]error"/data/attributes/status_error"--waitcomes from standard OpenAPIlinks. When a 2xx response has a link to an operation withpoll, the command gets--waitand--timeout. Link parameters map as follows:$response.body#/…takes the value from the first response.$request.path.refreuses the project ref.A response pointer must be required at every level of the response schema, so
--waitalways has something to poll with. A response that still lacks the value ends--waitwith aninternal_errorinstead of a silent success.An operation either declares
pollor links to a polled operation, never both.A polled read doesn't have to be a command. A status read that only exists to back
--waitcan stay hidden: the CLI calls it through@supabase/apiwhile waiting, but it has no command of its own. The policy lists each hidden poll target together with a generated read-only command that inspects the same state, and a failed or timed-out wait names that command in its hint. Hidden targets go through the same checks as generated operations (experimental stage,pollor links but not both).Secrets are marked on the field with
writeOnly: true,format: "password"orx-sensitive: true. Those fields are masked in--dry-runoutput whether they come from a flag,--bodyor--file, and their flags are markedsensitivein the command surface. Generation fails when a body field looks like a credential (password,secret,token,key,private) and isn't marked. It also fails for a secret the preview can't mask: one held anywhere inside a body field that has no flag, and any secret header or query parameter.Flags follow a convention. A flag is the kebab-case field name. An array field with a plural name gets a singular, repeatable flag, so
tablesbecomes--table. Beyond body and query fields:ref, if there is one, becomes a positional argument. An empty value,.or..is a usage error before any request.Idempotency-Keybecomes--idempotency-key.Authorization,Content-TypeandAcceptstay with the client.--bodyor--fileonly.The warehouse operations carry (every operation is also
"x-scalar-stability": "experimental"):In the CLI:
api-command-policy.tsholds:generatedOperations: the operations that generate commands, todayv2-enable-warehouse,v2-disable-warehouse,v2-get-warehouse-status,v2-get-warehouse-connectionandv2-get-warehouse-teardown. It keeps spec annotations from reaching the CLI on their own while the design settles, and will be removed once it does.pollTargets: hidden polling reads a generated link may target, each mapped to the generated command that inspects its state. Todayv2-get-warehouse-setup→v2-get-warehouse-status.verbVocabulary:list,get,create,update,delete,enable,disable,status,connection,add,remove,resync.nouns: each top-level group, with its helpdescription, the experimentalfeaturethat gates it, and the help text of its sub-groups. The group is hidden unless[experimental] <feature> = trueorSUPABASE_EXPERIMENTAL_<FEATURE>=1. Startup reads only the feature of the noun being run, or every noun feature for root help and completion.Generation fails for:
pollTargets;pollTargetsentry that no link uses, or whose key is also a generated operation;The generator takes everything else from the spec:
required, repeatability and help text;/data/attributes/schema, …);warehouse_setup);The generator rejects anything the runtime cannot honour, so a bad spec never reaches users. It rejects:
x-scalar-stability: experimental;summary;x-operation;--bodyor--wait, and a name used by more than one of path, header, query and body;dry_run;refpath parameter or with more than one other path parameter, path parameters that aren't strings, cookie parameters, header or query parameters that aren't scalars, non-object bodies, recursive schemas and unconverted keywords;pollon a non-GET, or together with a link to a polled operation;What users get
All generated commands follow the same conventions.
Help comes from the spec, including a
PERMISSIONSsection that lists the extra permission--waitneeds. TheEXAMPLESentry is built by the CLI. Abridged:--dry-runprints the exact request and sends nothing. It needs no consent:Whole bodies are accepted from
--body '<json>',--file body.jsonor--file -(stdin). Flags then replace fields at their own location. Top-level keys the operation doesn't declare are rejected, so a body can't redirect the request to another project:Output. On a terminal, the result is rendered for people. A JSON:API envelope becomes a heading, then aligned fields, and arrays of objects become tables. Progress shows as a spinner, and during
--waitit shows the current status. When stdout is not a terminal, in agent runs, with--output-format json|stream-jsonor with-o json, stdout is the API response exactly as sent, as JSON. This keeps| jqand other consumers stable.--output-format textor-o prettyforces the rendering,-o yamlprints YAML, and any other-ovalue is a usage error. A dry run follows the same rule: it prints the request as text, or as a JSON or YAML document. Unlike most commands, the default depends on whether stdout is a terminal. This matches how these commands already render errors, so one run never mixes a text result with a JSON error.Consent follows ADR 0033. Mutations ask with a default of no. Non-interactive runs need
--yesorSUPABASE_YES. Read-only commands such asstatusdon't ask.--waitturns the accepted response into a polled status read:sequenceDiagram participant U as supabase warehouse enable --wait participant API as Management API U->>API: POST /v2/projects/{ref}/warehouse/enable API-->>U: 202 {data.attributes.selection_id} loop first read immediately, then backoff 1s → 2s → 4s → 8s → 10s cap (Retry-After wins if longer) U->>API: GET /v2/projects/{ref}/warehouse/setups/current?selection_id=… API-->>U: 200 {status, status_error} end alt status = succeeded U-->>U: print the final read, exit 0 else status = failed U-->>U: operation_failed with the status_error message, exit 1 else read answers non-2xx U-->>U: that API error (not_found, conflict, …), exit 1 else --timeout (default 10m) reached U-->>U: wait_timeout, exit 1 endBoth wait failures include a follow-up command in their hint. When the polled read is a command, the hint names it with the identity from the accepted response, as in
supabase warehouse teardowns get --operation-id <id> --remote=<ref>afterdisable --wait. When it is a hidden poll target, the hint names its inspect command, as insupabase warehouse status --remote=<ref>afterenable --wait.supabase warehouse disable --waitpolls the cleanup read the same way.supabase warehouse teardowns get --waitpolls its own route, with its own flags and no change request, and prints the last read.Standard error envelope (
errors.standard)Generated commands opt into a new machine-readable error contract via
withStandardErrors. Existing commands keep the legacy envelope;command-errors.annotation.tsrecords which contract each command uses.In machine modes (
--output-format json|stream-json, agent mode, a machine-o, or stdout that isn't a TTY), the last stderr line is one JSON document:{"code":"conflict","status":409,"message":"The selection changed: Re-run enable.","hint":null,"api_code":"selection_conflict"}An optional
contextobject carries details for some codes:operation_failedhas{status}andwait_timeouthas{timeout_ms}. A plan-gated 4xx (entitlement_required) addsentitlement: {feature, upgrade_url}, just like the legacy error object. A terminal run prints the upgrade hint, andcli_upgrade_suggestedfires.unauthenticated,forbidden,not_found,conflict,rate_limited,invalid_input,api_error,network_error,operation_failed,wait_timeout,internal_errorusage_error: bad flags, missing required fields, unsupported-o, conflicting target selectors, no linked project, missing--yescancelled: consent declined or interruptedHints are built where the information is still available:
Run `supabase login`.Machine-readable command surface
command-surface.tswalks the mounted command tree throughCommandSpec.resolve. Generated and hand-written commands therefore produce the same document, the one a futuresurface.json, the docs and agent tooling can consume. Its shape:An abridged entry:
generated.schemas.tsis loaded only by the surface walk, through a dynamic import. The CLI never bundles the schemas at runtime, and a test checks this with aBun.buildmetafile.This PR adds the extraction but doesn't write a committed
surface.jsonfile yet.Other changes
packages/api. The warehouse operations, with theirx-operationmetadata and the enable→setup and disable→teardown links, are added toopenapi-overrides.jsonuntil they appear in the published spec. The typed client, contracts and permissions are regenerated.experimental.warehouseto the config schema and to the document-only local paths inpackages/config;apps/cli/schemas/config/v1.jsonis regenerated.supabase#api-commands:generate, which runs after@supabase/api#generateand is part of rootgenerate, andapi-commands:check, which is part ofcheck:all.api-package-sync.ymlregenerates command data and the reference together with the spec. oxlint ignoresgenerated.ts; knip treats both data modules as entry points.run.tswrites the standard error as the last stderr line,main.tsandroot.tsresolve the enabled noun features throughapi-command-features.ts, and the error-tag snapshot gains the four new error tags.SIDE_EFFECTS.mdfor gating, consent, files,--wait, exit codes, telemetry and output. The generatedgenerated.mdlists each command's route, flags and bindings, and its--waitread;api-commands:checkkeeps it in sync.apps/cli/AGENTS.mdnow reserves per-command folders for hand-written commands.Not in this PR
x-operationand the links to the published spec.generatedOperationsallowlist.surface.jsonplus a breaking-change gate built on the surface walk.experimentalstage.