Skip to content

feat(cli): generate warehouse commands from the Management API spec - #7640

Draft
jgoux wants to merge 48 commits into
developfrom
feat/generated-warehouse-commands
Draft

jgoux wants to merge 48 commits into
developfrom
feat/generated-warehouse-commands

Conversation

@jgoux

@jgoux jgoux commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

Summary

Adds the first commands generated from the Management API spec, for Warehouse:

  • supabase warehouse enable starts replication and can --wait for setup to finish;
  • supabase warehouse disable starts cleanup and can --wait for it to finish;
  • supabase warehouse status reads the consolidated Warehouse status;
  • supabase warehouse connection reads the Arrow Flight SQL connection details;
  • supabase warehouse teardowns get reads the current cleanup, and can --wait on it;
  • supabase warehouse tables list lists the replicated tables with their replication state and lag;
  • supabase warehouse tables get <table-id> reads one table, including its replication feedback;
  • supabase warehouse tables layout get <table-id> reads a table's saved sorting and partitioning rules beside the layout the DuckLake catalog records;
  • supabase warehouse tables layout update <table-id> changes those rules: --sort-by and --partition-by take a JSON value for their rule, and --reset-table copies the table again when the layout changes;
  • supabase warehouse inspect query-stats reads Warehouse query statistics over a time range (--since, or --from and --to), as labelled sample series;
  • supabase warehouse inspect capacity reads Warehouse capacity, admission and activation measurements over a time range, in the same form;
  • supabase warehouse replication add adds one eligible table (--schema and --table) or a schema's currently eligible tables (--schema alone) to replication;
  • supabase warehouse replication remove removes one selected table or all selected tables of a schema from replication, keeping the data already in Warehouse;
  • supabase warehouse replication resync resets and rebuilds one selected table (--schema and --table). It has no wait, idempotency or revision flags.

They are experimental and hidden unless the project opts in, in the same way as compute:

# supabase/config.toml
[experimental]
warehouse = true

or SUPABASE_EXPERIMENTAL_WAREHOUSE=1 in the shell.

The goal is to settle the full pipeline on one real resource before adding more. That pipeline covers:

  • spec (with x-operation and links) → generated data;
  • generic runtime → standard errors.

New commands should then need only an x-operation entry in the spec. The generator and runtime support exactly the shapes Warehouse uses (path and query parameters, JSON:API envelope bodies, JSON responses) and reject anything else at generation time, so a resource that needs a new shape adds it to the runtime explicitly. This is an alternative to the hand-written warehouse enable in #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 a committed data module 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, nouns)"]
    gen["scripts/generate-api-commands.ts<br/>derive + lints"]
    data["generated.ts<br/>(command data)"]
    ref["generated.md<br/>(per-command reference)"]
    spec --> gen
    policy --> gen
    gen --> data
    gen --> ref
  end
  subgraph run["Runtime"]
    rt["runtime.ts<br/>withApiCommands()"]
    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
Loading

Why committed data instead of resolving the spec at runtime

Resolve at runtime Generate code per command Generate data + one runtime (this PR)
Reviewable diff when the spec changes no yes, but noisy yes, data only
Spec loaded in the binary whole spec no only the selected operations
Lints fail the build, not the user no yes yes
Behaviour fixes land once yes regenerate every file yes

api-commands:check is part of check:all. api-package-sync.yml regenerates 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 optional per-command presentation choices. It never overrides what the spec says about an operation, and there is no per-command folder.

A command for an existing noun takes two edits: its x-operation (and links for --wait) in the spec, and its operation ID in generatedOperations. The spec edit lands upstream, or in packages/api/scripts/openapi-overrides.json until it is published. pnpm run generate downloads the spec, applies the overrides and writes the rest. A new noun is one nouns entry; a noun with its own feature also needs that experimental.<feature> key in packages/config/src/experimental.ts and in featureSchemas/featureKeys in apps/cli/src/shared/config/experimental-feature.ts, which ApiNoun.feature enforces at type-check time.

In the spec: x-operation on an operation names its command. Only operations on the CLI allowlist generate a command, so the spec can name every operation for other consumers and a name stays inert until its operation is listed. Off the allowlist, x-operation is read only on an operation that an allowlisted operation links to (see below).

Field Meaning Example
group A dot-separated path that starts with a CLI-declared noun. Each segment becomes a command word, and every sub-group needs help text in the CLI's nouns table. A noun is always a new top-level command. "warehouse" → supabase warehouse …
"warehouse.tables" → supabase warehouse tables …
method The last command word. It is usually a verb such as list, get or enable. A read of a singleton facet is named after the facet, such as status or connection, and a report under an inspect group is named after the report, such as query-stats. Every command word is lowercase kebab-case. Names are reviewed in the allowlist PR through the generated.md diff. "enable" → supabase warehouse enable
poll Optional, on a read (GET) only. Says the read reports the state of a long-running operation. The read itself gets --wait and --timeout. See below

The extension is decoded strictly: an unknown key fails generation, and so does a name with only one of group and method. A name is optional when poll is set. 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. The published spec already carries it for enable, disable and the teardown read. openapi-overrides.json renames the setup read to warehouse.setups get and adds its poll.inspect. It also adds the status, connection, tables (list, get, layout get and update), query-stats, capacity and replication (add, remove and resync) operations until they are published.

poll fields:

Field Meaning Warehouse value
status JSON pointer to the status in the read response. "/data/attributes/status"
succeeded Status values that end the wait successfully (exit 0). ["succeeded"]
failed Status values that end the wait as operation_failed (exit 1). ["failed"]
error Optional. JSON pointer to a failure reason. It supplies the message when the wait ends on a failed status; it doesn't end the wait by itself. "/data/attributes/status_error"
inspect Required on a poll-only read and ignored on a generated one, whose own command is named instead. The operation ID of the read-only command that inspects the same state. "v2-get-warehouse-status"

--wait comes from standard OpenAPI links. When a 2xx response has a link to an operation with poll, the command gets --wait and --timeout. Link parameters map as follows:

  • $response.body#/… takes the value from the first response.
  • $request.path.ref reuses the project ref.
  • Any other expression, an unknown target, or more than one polled link fails generation.

A response pointer must be required at every level of the response schema, so --wait always has something to poll with. A response that still lacks the value ends --wait with an internal_error instead of a silent success.

An operation either declares poll or 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 --wait declares poll and stays off the allowlist: a poll-only read. It may carry a name for other consumers, but it gets no command: the CLI calls it through @supabase/api while waiting. Its poll.inspect names the operation whose command inspects the same state, and a failed or timed-out wait names that command in its hint.

The generator finds a poll-only read through the response links of the allowlisted operations, and ignores one that nothing links to. Nothing in the CLI lists these reads: a new one shows up as a diff in the generated data and reference. Poll-only reads go through the same checks as generated operations (experimental stage, GET, poll or links but not both).

Secrets are marked on the field with writeOnly: true, format: "password" or x-sensitive: true. Those fields are masked in --dry-run output whether they come from a flag, --body or --file. 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 nested body field, whose JSON value the preview doesn't mask, 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 tables becomes --table. Beyond body and query fields:

  • The path parameter besides ref, if there is one, becomes a positional argument. An empty value, . or .. is a usage error before any request.
  • A nested body field (an object, an array of objects or a union) gets a flag that takes a JSON value for that field, null included, so --sort-by '{"kind":"none"}' needs no JSON:API envelope. The value goes through the same schema validation as the rest of the body, before consent.

The warehouse operations carry (every operation is also "x-scalar-stability": "experimental"):

// POST /v2/projects/{ref}/warehouse/enable → supabase warehouse enable
"x-operation": { "group": "warehouse", "method": "enable" },
"responses": { "202": { "links": { "setup": {
  "operationId": "v2-get-warehouse-setup",
  "parameters": { "ref": "$request.path.ref", "selection_id": "$response.body#/data/attributes/selection_id" }
} } } }

// GET /v2/projects/{ref}/warehouse/setups/current → poll-only read, not on the allowlist
"x-operation": { "group": "warehouse.setups", "method": "get", "poll": {
  "status": "/data/attributes/status", "succeeded": ["succeeded"], "failed": ["failed"],
  "error": "/data/attributes/status_error", "inspect": "v2-get-warehouse-status"
} }

// DELETE /v2/projects/{ref}/warehouse → supabase warehouse disable
"x-operation": { "group": "warehouse", "method": "disable" },
"responses": { "202": { "links": { "teardown": {
  "operationId": "v2-get-warehouse-teardown",
  "parameters": { "ref": "$request.path.ref", "operation_id": "$response.body#/data/id" }
} } } }

// GET /v2/projects/{ref}/warehouse/teardowns/current → supabase warehouse teardowns get
"x-operation": { "group": "warehouse.teardowns", "method": "get", "poll": {
  "status": "/data/attributes/lifecycle_status", "succeeded": ["disabled"], "failed": ["deletion_failed"],
  "error": "/data/attributes/cleanup_error"
} }

// GET /v2/projects/{ref}/warehouse/status → supabase warehouse status
"x-operation": { "group": "warehouse", "method": "status" }

// GET /v2/projects/{ref}/warehouse/connection → supabase warehouse connection
"x-operation": { "group": "warehouse", "method": "connection" }

// GET /v2/projects/{ref}/warehouse/tables → supabase warehouse tables list
"x-operation": { "group": "warehouse.tables", "method": "list" }

// GET /v2/projects/{ref}/warehouse/tables/{table_id} → supabase warehouse tables get <table-id>
"x-operation": { "group": "warehouse.tables", "method": "get" }

// GET /v2/projects/{ref}/warehouse/tables/{table_id}/layout → supabase warehouse tables layout get <table-id>
"x-operation": { "group": "warehouse.tables.layout", "method": "get" }

// PATCH /v2/projects/{ref}/warehouse/tables/{table_id}/layout → supabase warehouse tables layout update <table-id>
"x-operation": { "group": "warehouse.tables.layout", "method": "update" }

// GET /v2/projects/{ref}/warehouse/query-stats → supabase warehouse inspect query-stats
"x-operation": { "group": "warehouse.inspect", "method": "query-stats" }

// GET /v2/projects/{ref}/warehouse/capacity → supabase warehouse inspect capacity
"x-operation": { "group": "warehouse.inspect", "method": "capacity" }

// POST /v2/projects/{ref}/warehouse/replication/add → supabase warehouse replication add
"x-operation": { "group": "warehouse.replication", "method": "add" }

// POST /v2/projects/{ref}/warehouse/replication/remove → supabase warehouse replication remove
"x-operation": { "group": "warehouse.replication", "method": "remove" }

// POST /v2/projects/{ref}/warehouse/replication/resync → supabase warehouse replication resync
"x-operation": { "group": "warehouse.replication", "method": "resync" }

In the CLI: api-command-policy.ts holds:

  • generatedOperations: the operations that generate commands, today v2-get-warehouse-status, v2-get-warehouse-connection, v2-enable-warehouse, v2-disable-warehouse, v2-get-warehouse-teardown, v2-list-warehouse-tables, v2-get-warehouse-table, v2-get-warehouse-table-layout, v2-update-warehouse-table-layout, v2-get-warehouse-query-stats, v2-get-warehouse-capacity, v2-add-warehouse-replication, v2-remove-warehouse-replication and v2-resync-warehouse-replication. It is the only thing that turns an operation into a command, so a spec annotation never reaches the CLI on its own.
  • commandPolicies: CLI presentation choices per operation. Today the only one is confirmDescription, which prints the operation's API description before the interactive consent prompt. The replication commands, disable and tables layout update use it, because their descriptions spell out effects such as pipeline restarts, permanent data deletion or a table recopy that the request values alone don't show.
  • nouns: each top-level group, with the experimental feature that gates it and the help text of the sub-groups the generator creates (Warehouse describes replication, inspect, tables, tables.layout and teardowns). A noun is always a new top-level group: generated commands never join a hand-written one. The group is hidden unless [experimental] <feature> = true or SUPABASE_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:

  • an allowlisted operation missing from the spec or left without a name;
  • a link to an operation whose x-operation is invalid;
  • a poll-only read without poll.inspect;
  • an inspect operation that isn't generated, changes state, or needs input beyond the project ref.

The generator takes everything else from the spec:

  • summary and description;
  • flags, with their types, required, repeatability and help text;
  • where each flag goes in the request (/data/attributes/schema, …);
  • the JSON:API envelope type (warehouse_setup);
  • FGA permissions (read at runtime from @supabase/api/permissions, not generated here).

The generator rejects anything the runtime cannot honour, so a bad spec never reaches users. It rejects:

  • operations not marked x-scalar-stability: experimental;
  • operations without a summary;
  • unknown keys in x-operation;
  • groups that don't start with a declared noun, sub-groups without help text, and command words that aren't kebab-case;
  • a noun that is already a hand-written command, collisions between generated commands, and a path that is both a command and a group (a name off the allowlist meets these checks once its operation is listed);
  • non-kebab or duplicate flags, flags that collide with runtime flags such as --body or --wait or with registered global flags such as --profile, and a name used by more than one of path, query and body;
  • server-side dry_run;
  • parameter, body or schema shapes the runtime can't bind: operations without a ref path parameter or with more than one other path parameter, path parameters that aren't strings, cookie parameters, header parameters other than Authorization, Content-Type and Accept, query parameters that aren't scalars, bodies that aren't a JSON:API envelope, and numeric body fields;
  • secrets the dry-run preview can't mask, as described above;
  • success responses that aren't JSON;
  • poll on a non-GET, or together with a link to a polled operation;
  • unsupported links;
  • waits whose pointers don't resolve in the responses or aren't always present, or whose parameters or status values don't match the read operation.

What users get

All generated commands follow the same conventions.

Help comes from the spec, including a PERMISSIONS section that lists the extra permission --wait needs. The CLI builds the EXAMPLES entry from the positional argument and the required flags that don't set a body field; a command that takes a body shows --file <path>, since a flag alone may not make a valid body. Abridged:

$ supabase warehouse enable --help
DESCRIPTION
  …

TARGET
  Remote only. Uses the linked project; pass --remote=<ref|branch> for another.

FLAGS
  --remote[=<ref|branch>]             Target another project: --remote=<ref|branch>. Defaults to the linked project.
  --body string                       Whole request body as JSON; other flags replace fields at their own location.
  --file string                       Read the whole request body from a JSON file, or - for stdin.
  --dry-run                           Print the request that would be sent and send nothing.
  --wait                              Wait until the operation reaches a final status.
  --timeout string                    How long --wait polls, as a duration such as 90s or 10m.
  --warehouse-region string           Optional Warehouse compute region, …
  --destination-project-ref string    Supabase project to use for both the DuckLake PostgreSQL catalog and Supabase Storage. …
  --install-fdw                       Whether to configure and install the Warehouse FDW in the project database. …
  --schema string                     Source PostgreSQL schema. Without tables, selects its currently eligible tables only. Required unless the field is in --body or --file.
  --table string                      Table names in schema. Omit to select the currently eligible tables in that schema.

GLOBAL FLAGS
  …

EXAMPLES
  # Enable Warehouse replication
  supabase warehouse enable --file <path>

PERMISSIONS
  Scoped access token:
    Required:
      project_admin_write
      database_write
    Required with --wait:
      database_read
    May be required:
      projects_read
      …

--dry-run prints the exact request and sends nothing. It needs no consent, and with a literal --remote=<ref> it needs no login either: it builds no API client, makes no request and writes no cache:

$ supabase warehouse enable --remote=abcdefghijklmnopqrst --schema public --table orders --table customers --dry-run
{"method":"POST","path":"/v2/projects/abcdefghijklmnopqrst/warehouse/enable","query":{},"headers":{},
 "body":{"data":{"type":"warehouse_setup","attributes":{"schema":"public","tables":["orders","customers"]}}}}

Whole bodies are accepted from --body '<json>', --file body.json or --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:

$ supabase warehouse enable --remote=abcdefghijklmnopqrst --yes --body '{"ref":"zyxwvutsrqponmlkjihg","data":{}}'
{"code":"usage_error","status":null,"message":"--body/--file has the field \"ref\", which the request body does not take.","hint":"Top-level fields: data."}
# exit 2

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. A table keeps the scalar columns, and each row's nested fields print in a block below it, with - for null. A sample series under a points key shows its last 10 samples, in response order, with a notice of how many were left out; every other list prints in full, and JSON output shows everything. An empty list prints No results. Progress shows as a spinner, and during --wait it shows the current status. When stdout is not a terminal, in agent runs, or with --output-format json|stream-json, stdout is the API response exactly as sent, as JSON (null for an empty body). This keeps | jq and other consumers stable. The legacy -o/--output flag is a usage error that points to --output-format, since it goes away in V4. A dry run follows the same rule: it prints the request as text, or as a JSON 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, and the question lists the request values (path, query and body fields, from flags, --body or --file), so options such as disable --delete-data or layout update --reset-table show before you confirm. A command with confirmDescription also prints its API description first, so replication add warns that the pipeline restarts before you answer. Non-interactive runs need --yes or SUPABASE_YES. Read-only commands such as status don't ask.

--wait turns 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
  end
Loading

Both 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> after disable --wait. When it is a poll-only read, the hint names the command of its poll.inspect operation, as in supabase warehouse status --remote=<ref> after enable --wait.

supabase warehouse disable --wait polls the cleanup read the same way. supabase warehouse teardowns get --wait polls 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.ts records which contract each command uses.

In machine modes (--output-format json|stream-json, agent mode, or stdout that isn't a TTY), and for the usage error that rejects -o/--output, 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 context object carries details for some codes: operation_failed has {status} and wait_timeout has {timeout_ms, last_status} (last_status is null when no read succeeded). A plan-gated 4xx (server body code entitlement_required) keeps its status-derived code and adds entitlement: {feature, upgrade_url} in place of the permission hint, just like the legacy error object. A terminal run prints the upgrade hint, and cli_upgrade_suggested fires.

exit codes
0 success or dry run
1 unauthenticated, forbidden, not_found, conflict, rate_limited, invalid_input, api_error, network_error, operation_failed, wait_timeout, internal_error
2 usage_error: bad flags, missing required fields, any -o/--output, an invalid --timeout (checked even without --wait), conflicting target selectors, no linked project, missing --yes
130 cancelled: consent declined or interrupted

Hints are built where the information is still available:

  • 401 → Run `supabase login` .
  • 403 → the FGA permissions the operation needs.
  • A hint from the server always takes precedence.

Other changes

  • packages/api. Enable, disable, the setup and teardown reads and their links come from the published spec. openapi-overrides.json adds the status, connection, tables, table, table layout (read and update), query statistics, capacity and replication (add, remove and resync) operations until they are published, and moves the setup read to warehouse.setups get with x-operation.poll.inspect. generate.ts normalizes nullable oneOf unions as it already did anyOf. The typed client, contracts and permissions are regenerated.
  • Config. Adds experimental.warehouse to the config schema and to the document-only local paths in packages/config; apps/cli/schemas/config/v1.json is regenerated.
  • Tooling. Adds the Turbo tasks supabase#api-commands:generate and api-commands:check, which is part of check:all. Root generate regenerates @supabase/api and @supabase/stack first, then runs supabase#api-commands:generate and schemas:generate in a second Turbo run, so the command data is derived from the refreshed spec rather than from a cache keyed on the old one. api-package-sync.yml regenerates command data and the reference together with the spec. oxlint ignores generated.ts.
  • CLI runtime. linkedDbResolverRuntimeLayer becomes lazyManagementApiRuntimeLayer, shared by db, logs, migration, pull and the generated commands, so the API client is built only when a command needs it. run.ts writes the standard error as the last stderr line, main.ts and root.ts resolve the enabled noun features through api-command-features.ts, and the error-tag snapshot gains the four new error tags.
  • Docs. The generated generated.md lists each command's route, experimental gate, flags and bindings, and its --wait read; api-commands:check keeps it in sync. Generated commands get no per-command folder.

Not in this PR

  • More generated resources. Warehouse is the pilot, and its remaining commands follow once their API operations are in the spec.
  • Upstreaming x-operation and the links to the published spec.
  • A machine-readable command surface (surface.json) and a breaking-change gate built on it. An extraction without a CI-checked consumer was dropped from this PR.
  • Generated commands outside the experimental stage.

@jgoux jgoux self-assigned this Nov 16, 2026
@jgoux

jgoux commented Nov 16, 2026

Copy link
Copy Markdown
Contributor Author

/ai-review

@github-actions github-actions Bot left a comment •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Comment thread apps/cli/src/shared/cli/run.ts Resolved
Comment thread apps/cli/scripts/api-command-derive.ts Resolved
Comment thread apps/cli/scripts/api-command-derive.ts Resolved
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.
@jgoux

jgoux commented Nov 16, 2026

Copy link
Copy Markdown
Contributor Author

/ai-review

@github-actions github-actions Bot left a comment •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Superseded by a newer AI review

🤖 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.

Comment thread apps/cli/scripts/api-command-derive.ts Resolved
…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.
bnjjj and others added 2 commits November 17, 2026 15:56
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.
bnjjj and others added 3 commits November 17, 2026 22:21
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.
jgoux and others added 7 commits November 18, 2026 14:41
A read that a `--wait` polls without being a command now carries
`x-operation: { poll: { ..., inspect } }` with no `group`/`method`.
The generator finds it through the response links of the generated
operations, and `poll.inspect` names the operation whose command the
failure and timeout hint points to.

This replaces the `pollTargets` map in the command policy. The runtime
and the generated command files are unchanged.
The deployed Management API spec now includes the Warehouse disable
route, the teardown read and its response schema, so the overrides that
added them collided and spec regeneration failed. The regenerated
files differ only in ordering.
Only the generated operations list decides whether an operation becomes
a command, and a generated name still goes through every collision
check. A polled read the CLI does not generate may keep its own name
next to poll and inspect, so the spec can name every operation for
other consumers. The setup read's override now names it
warehouse.setups get.
…oined

Generated commands rebuild the group they join, which bypassed the stack
group's own Command.provide. Each stack subcommand now provides the stack
runtime layer itself, so the sealed-group list and its generator check go.
Generate `warehouse tables list` from `GET
/v2/projects/{ref}/warehouse/tables`. It lists the tables selected for
Warehouse replication with their freshness:

- `status`: `syncing`, `live`, `error`, `stopped` or `unknown`;
- the raw replication state;
- when the state was observed;
- `lag_ms`, the flush lag of the replication slot that carries the
table.

Text output shows one row per table. `-o json` and `-o yaml` also
include the full replication feedback. That feedback includes
`flush_lag_bytes`, which reads 0 for a caught-up slot whose lag time
Postgres no longer reports.

Also generate `warehouse tables get <table-id>` from `GET
/v2/projects/{ref}/warehouse/tables/{table_id}`. It reads one of those
tables by the source OID that `warehouse tables list` shows as its ID,
with the same attributes. Its text output also shows the nested
replication feedback, and a table that isn't replicated is an API error.
This is the first generated command with a positional argument on a real
operation, so the generic bindings test now supplies positional path
parameters.

Two generic changes to the text output of generated commands:

- an empty collection prints `No results` instead of `Data  -`;
- a column that holds a nested object in any row is left out of the
table. Before, rows with a nested object printed it as compact JSON
while rows with `null` printed `-`.

The tables contracts, and `flush_lag_bytes` in the status contract, come
from OpenAPI overrides until they ship in the deployed Management API
specification.

Stacked on #7640. Depends on
supabase/platform#42055 and
supabase/platform#42108.

Implements PIPE-1451 and PIPE-1453.

---------

Co-authored-by: Julien Goux <hi@jgoux.dev>
@jgoux jgoux added the run-preview-packages Publish pkg.pr.new preview CLI packages for this PR label Nov 19, 2026
@github-actions

github-actions Bot commented Nov 19, 2026 •

Copy link
Copy Markdown
Contributor

Supabase CLI preview

npx --yes https://pkg.pr.new/supabase/cli/supabase@cdcbb7b140360f986a4a1926cfdd730e2c1c1fe2

Preview package for commit cdcbb7b.

bnjjj and others added 2 commits November 19, 2026 11:56
Add the experimental `supabase warehouse inspect query-stats` command,
stacked on #7640.

```sh
supabase warehouse inspect query-stats --remote <project-ref> --since 30m
```

Generate the command from the public Management API contract. Support
`--from`/`--to`, `--attributes`, and `--interval`.

Use the shared output contract: text on a terminal, JSON when piped, and
explicit JSON/YAML/pretty output. Text preserves nested ranges, labels,
and sample values, with the last 10 items of each nested array and an
omission notice. JSON/YAML retain the complete response, including null
samples and unknown fields.

Range validation and metric semantics remain server-owned. The shared
renderer also retains nested fields in other generated resource
collections.

Closes PIPE-1461.

---------

Co-authored-by: Julien Goux <hi@jgoux.dev>
bnjjj and others added 6 commits November 19, 2026 12:04
Add the experimental `supabase warehouse inspect capacity` command,
stacked on #7640.

```sh
supabase warehouse inspect capacity --remote <project-ref> --since 30m
```

Generate the command from the public capacity API contract, with
`--from`/`--to`, `--attributes`, and `--interval`. Keep metric selection
defaults and range validation server-owned.

Reuse the shared text, JSON, and YAML output contract, preserving units,
dimensions, null values, and availability. JSON/YAML retain the complete
response.

No new generated-command runtime or generator logic is needed.

Closes PIPE-1463.
… commands

A body field that is not a scalar or an array of scalars now gets a flag that takes a JSON value
for that field, so warehouse tables layout update accepts --sort-by and --partition-by without a
--body envelope. The value is validated against the operation schema before consent.
Layout reads require application_status, pipeline_id and reset_table, as
the platform does, and the update response reuses the read schema. The
capacity schema override gets the comment the override loader requires.
The layout update attributes are now a union of two closed objects, one
requiring sort_by and one requiring partition_by, so an empty or reset-only
patch fails locally before dry-run, consent and the request, as the server
rejects it.

Generated commands derive their flags from union attributes whose branches
share their properties, and a missing choice reports
"Pass at least one of --sort-by, --partition-by".
Metrics commands get one range form instead of combining since with from/to, the
metadata assertion that mirrored the surface under test is gone, and commands whose
inputs are all required no longer repeat the same request.
… in consent

Generated commands now take their presentation from --output-format and the
TTY alone, the same rule failures use, and reject -o/--output with a pointer
to --output-format. YAML output goes away with it.

Consent lists the validated request's path, query and body values, so
destructive options such as --delete-data and --reset-table show in the
prompt. A passed --timeout is validated even without --wait.
A dry run against a literal ref now needs no access token, sends no request
and leaves the linked-project cache untouched. Generated commands build
the Management API client through the lazy factory, so the client exists
only once a request is about to be sent. The lazy runtime layer has a new
name that fits both of its consumers.

A --wait poll now parses each response once.
Warehouse, the only generated noun, owns its whole subtree, so merging
generated commands into hand-written groups had no consumer. The join path,
its generator exemptions and its fixture tests are removed; a noun that
collides with a hand-written root command still fails generation. The
Stack group gets its single group-level layer provide back.
The command surface reads bindings and stage from the generated entry, so the
mounted annotation carries only the operation id and the stage annotation is
gone. Body-bound flags are no longer reported as required on the command line,
and the side-effects doc covers stack-mode project state and the workdir order.
bnjjj and others added 11 commits November 19, 2026 20:26
Adds experimental `warehouse replication add`, `remove` and `resync`
commands on top of #7640.

All three use the generated request/runtime path and preserve the
immediate API response. All support `--dry-run` as a local request
preview, with no server-side dry-run contract. Resync has no
idempotency, revision or wait flags.

The shared generator/runtime gains CLI policy for API impact
descriptions in consent. Local previews use the existing shared
behavior. No hand-written command handlers are added.

Depends on #7640 and the companion Management API endpoints.

---------

Co-authored-by: Julien Goux <hi@jgoux.dev>
…oute help

An ambiguous --remote maps only 401, 403 and token failures to auth
documents; a 404 branch listing stays a usage error. The --wait spinner
status and a non-JSON text-mode success body are escaped for display,
while JSON output keeps the original bytes. Routing args drop a leading
help so `help warehouse` and `help compute` resolve their feature, and
the stack backend reuses that. Help tests assert the cache and poll
permissions outside dry runs.
The noun's gate field is now `experimental`, matching the `experimental.<name>` config key it
reads. Entries no longer copy it; the reference reads the noun and prints how to enable it.
Develop removed every per-command SIDE_EFFECTS.md; the generated per-command
reference and the tests now carry the generated command contract.
…n contract

The description contract test now builds the warehouse command tree, and the
warehouse connection example is wrapped in a code span so `<host>` no longer
parses as HTML.
@jgoux

jgoux commented Nov 19, 2026

Copy link
Copy Markdown
Contributor Author

/ai-review

@github-actions github-actions Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🤖 AI Review

CLI reference prose guidance: snapshot supabase/supabase@6f13230 supplied to reviewers (advisory, not a style pass).

A malformed polling response can leave a warehouse operation waiting until the default ten-minute timeout. The review also confirmed that dry runs can contact the Management API during target resolution, warehouse success output bypasses NDJSON framing, and the generators have several edge cases. The reported silent overwrite of upstream OpenAPI entries is refuted by an explicit collision guard. Both independent reviews and the pinned prose guidance were available. The adjudication was static, with no test execution.

Findings

Severity Location Category Sources Claim
🟠 MAJOR apps/cli/src/commands/api/api-command-execute.ts:229 error-handling codex A malformed successful polling response is treated as an operation still in progress. After the mutation has been accepted, repeated malformed responses can consume the default ten-minute wait and surface a timeout instead of the response error.
🟡 MINOR apps/cli/src/commands/api/api-command-request.ts:254 security codex The generated-command runtime can echo rejected values for fields marked sensitive when it formats request validation failures.
🟡 MINOR apps/cli/src/commands/api/runtime.ts:112 cli-help codex --dry-run promises to “send nothing,” but resolving the target can still send Management API requests.
🟡 MINOR apps/cli/scripts/generate-api-commands.ts:4 code-generation codex The command generator requires its own TypeScript output to load before it can recreate that file or report it missing in check mode.
🟡 MINOR apps/cli/scripts/api-command-derive.ts:449 code-generation codex A valid operation-level override of a path-item query parameter can fail command generation with a duplicate flag.
🟡 MINOR apps/cli/scripts/api-command-derive.ts:207 code-generation codex Reordering properties in one anyOf branch can make the command generator reject an otherwise equivalent request schema.
🟡 MINOR apps/cli/scripts/api-command-derive.ts:1038 code-generation codex The generator can approve a linked wait when a success response lacks the value needed to poll. A mutation can then succeed before the CLI exits with a defect.
🟡 MINOR packages/api/scripts/generate.ts:340 correctness codex Normalizing a nullable oneOf that already has an explicit null branch adds a second null branch. The resulting exclusive union has two matches for null.
🟡 MINOR apps/cli/scripts/api-command-reference.ts:30 documentation codex The generated reference inserts a literal backslash into the copyable Flight SQL connection example.
🟡 MINOR apps/cli/src/commands/api/api-commands.integration.test.ts:2237 test-coverage codex The test named “keeps JSON for success and failure when --output-format text is piped” does not verify that the failure is rendered as JSON.
⚪ NIT apps/cli/src/commands/api/api-command-execute.ts:165 output-consistency claude A warehouse success response can be emitted without a record terminator under --output-format stream-json, which advertises NDJSON.
⚪ NIT apps/cli/src/commands/api/api-commands.e2e.test.ts:200 test-coverage codex Two subprocess tests repeat the same successful enable-and-wait sequence. One invocation can cover piped output selection and assert the linked request paths.
⚪ NIT apps/cli/src/shared/cli/run.ts:48 style codex The patch changes Tty to a value import even though the file only uses it as a type.
⚪ NIT apps/cli/src/commands/api/generated.ts:11 docs-style codex The connection help uses “Login” in prose and omits the Oxford comma in its list of values the API excludes.
⚪ NIT apps/cli/src/commands/api/generated.ts:369 docs-style codex Warehouse help uses “PostgreSQL” in descriptive prose where the snapshot calls for “Postgres.”
⚪ NIT apps/cli/src/commands/api/generated.ts:267 docs-style codex Query-stats help refers to since, from, and to without the -- prefixes readers need to enter those CLI flags.
⚪ NIT apps/cli/src/commands/api/generated.ts:28 docs-style codex The disable help gives the API query field for permanent deletion and introduces “FDW” without expansion.
⚪ NIT apps/cli/src/commands/api/api-command-policy.ts:46 docs-style codex The top-level warehouse description uses “Manage” where it could name the actions the command group supports.
Refuted findings (kept for transparency, not posted as review comments)
  • packages/api/scripts/openapi-overrides.json:157 (code-generation): The temporary Warehouse add overrides will silently replace upstream path items and schemas published under the same keys.
    Refuted: This repository’s override implementation rejects existing object keys and identifies the conflicting pointer. A collision fails regeneration before any replacement occurs.

Stats

Claude findings: 1 · Codex findings: 18 · Confirmed: 18 · Refuted: 1 · Uncertain: 0


Models: claude-opus-5-5 + gpt-6.2-sol · Trigger: manual · Workflow run

This review runs once per PR. A maintainer can request another with a /ai-review comment.

Comment on lines +229 to +249
const readPoll = (wait: ApiCommandWait, response: ApiCommandResponse): PollRead => {
const body = parseResponse(response);
const status = readPointer(body, wait.status);
return { response, body, status: typeof status === "string" ? status : undefined };
};

const classify = (wait: ApiCommandWait, read: PollRead, statusHint: string) => {
const { response, body, status } = read;
if (status !== undefined && wait.failed.includes(status)) {
const reason =
wait.error === undefined ? undefined : failureReason(readPointer(body, wait.error));
return Effect.fail(
new ApiCommandOperationFailedError({
status,
message: reason ?? `The operation failed with status "${status}".`,
hint: statusHint,
}),
);
}
const done = status !== undefined && wait.succeeded.includes(status);
return Effect.succeed<PollOutcome>({ done, response });

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟠 MAJOR · error-handling · source: codex

A malformed successful polling response is treated as an operation still in progress. After the mutation has been accepted, repeated malformed responses can consume the default ten-minute wait and surface a timeout instead of the response error.

Evidence: api-command-execute.ts:150–151 and :229–249 reduce invalid JSON and missing or non-string statuses to an unfinished poll. Lines 315–340 repeat that outcome until completion or timeout. runtime.ts:56 sets the default to 10m.

Suggested fix: Return a typed response error with the status-check hint when the body is invalid JSON or the required status is missing or non-string. Continue polling for well-formed nonterminal statuses.

});
}
return new ApiCommandUsageError({
message: `The request is not valid: ${error.message}`,

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 MINOR · security · source: codex

The generated-command runtime can echo rejected values for fields marked sensitive when it formats request validation failures.

Evidence: api-command.model.ts:47–48 defines sensitive fields. api-command-derive.ts:887 and :915 can generate the annotation. api-command-request.ts:253–266 forwards error.message without checking the binding. runtime.ts:220–225 validates before preview masking, and standard-errors.ts:171–172 and :264–278 forward the usage message to stderr.

Suggested fix: Render schema issues affecting sensitive fields with the field path and expected constraint. Omit rejected values and add coverage for a sensitive field supplied through a body override.

),
}),
dryRun: Flag.Boolean("dry-run").pipe(
Flag.withDescription("Print the request that would be sent and send nothing."),

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 MINOR · cli-help · source: codex

--dry-run promises to “send nothing,” but resolving the target can still send Management API requests.

Evidence: runtime.ts:112 promises no requests and :213 resolves the target before the dry-run return at :223–225. project-ref.layer.ts:75 can call listAllProjects, and branch-resolution.ts:174 can call listAllBranches. api-commands.integration.test.ts:1911–1922 explicitly accounts for target-resolution operations on a dry run.

Suggested fix: Say that dry run skips the warehouse operation and that resolving the project or branch can still contact the Management API.

import { BunRuntime, BunServices } from "@effect/platform-bun";
import { Console, Data, Effect, FileSystem, Path, Predicate, Schema, Stream } from "effect";
import { ChildProcess, ChildProcessSpawner } from "effect/process";
import { rootCommandForFeatures } from "../src/cli/root.ts";

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 MINOR · code-generation · source: codex

The command generator requires its own TypeScript output to load before it can recreate that file or report it missing in check mode.

Evidence: generate-api-commands.ts:4 imports rootCommandForFeatures from root.ts, which imports withApiCommands at :29. runtime.ts:54 statically imports ./generated.ts. The generator checks whether that file exists only at generate-api-commands.ts:113–120.

Suggested fix: Collect hand-written root names from a module whose imports do not load the generated commands.

Comment on lines +449 to +452
const operationParameters = (spec: JsonObject, operation: Operation): ReadonlyArray<JsonObject> =>
[...asArray(operation.pathItem.parameters), ...asArray(operation.node.parameters)]
.map((raw) => asRecord(resolve(spec, raw)))
.filter(Predicate.isNotUndefined);

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 MINOR · code-generation · source: codex

A valid operation-level override of a path-item query parameter can fail command generation with a duplicate flag.

Evidence: api-command-derive.ts:449–452 concatenates the parameter lists, :748–767 derives a field from each query entry, and :877–882 reports duplicate names and keys.

Suggested fix: Merge resolved parameters by (in, name) before deriving flags and give operation-level declarations precedence.

definition: "v2GetWarehouseConnection",
summary: "Get Warehouse Flight SQL connection details",
description:
"Returns the public Arrow Flight SQL endpoint resolved from the project's Warehouse routing, with TLS required on port 443. Status is configured availability and query connectivity is not checked, so DNS readiness does not prove a query will succeed. Login uses a role in the source project database with that role's existing password (postgres uses the project database password), including when the catalog and storage are in another project. The role needs supabase_warehouse_reader membership, which is separate from Management API authorization. No passwords, tokens, catalog credentials or private endpoints are returned, and endpoint, host and port are null unless status is available or pending. Example client: `usql -W 'flightsql://postgres@<host>:443?tls=enabled'`.",

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚪ NIT · docs-style · source: codex

The connection help uses “Login” in prose and omits the Oxford comma in its list of values the API excludes.

Evidence: generated.ts:11 says “Login uses a role in the source project database” and “No passwords, tokens, catalog credentials or private endpoints are returned.” The pinned guidance prefers “sign in” in prose and a serial comma. https://github.com/supabase/supabase/blob/6f13230f5269fc192a533617c8cdc238afe14784/apps/docs/style-guide/WORD_LIST.md#login-and-log-in https://github.com/supabase/supabase/blob/6f13230f5269fc192a533617c8cdc238afe14784/apps/docs/style-guide/01-voice-and-tone.md#use-the-oxford-comma

Suggested fix: In the source description, use “Sign in with a role in the source project database using that role’s existing password” and “No passwords, tokens, catalog credentials, or private endpoints are returned.” Regenerate the help.

type: "string",
repeatable: false,
required: true,
description: "Literal source PostgreSQL schema. Omit table to select its current tables.",

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚪ NIT · docs-style · source: codex

Warehouse help uses “PostgreSQL” in descriptive prose where the snapshot calls for “Postgres.”

Evidence: generated.ts:108, :369, :407, :420, and :471 use phrases such as “Literal source PostgreSQL schema” and “Source PostgreSQL rows.” The pinned word list prefers “Postgres” for prose. https://github.com/supabase/supabase/blob/6f13230f5269fc192a533617c8cdc238afe14784/apps/docs/style-guide/WORD_LIST.md#postgres

Suggested fix: Use “Source Postgres schema,” “Literal source Postgres schema,” and “Source Postgres rows” in the source descriptions, then regenerate the help.

definition: "v2GetWarehouseQueryStats",
summary: "Inspect Warehouse workload query statistics",
description:
"Returns aggregate workload measurements over a bounded time range, using the project’s stored Warehouse placement. Use since or both from and to; the default is the last 30 minutes. Each measurement includes its definition, unit, aggregation, requested and effective ranges, rate_window_seconds, source-sample freshness, availability, and full series with dimension labels. Point timestamps are evaluation times; last_sample_at is the original source-sample time. Rates and latency quantiles describe the effective rate window at each point, not the entire requested range. Do not average interval percentiles into a whole-range percentile. Executor invocations include metadata/schema work and are not counts of user SQL statements. Timeouts are included in errors; cancellation is separate. Missing and unavailable values remain null. No query history, individual-query attribution, raw queries, or backend selectors are exposed. Each request returns up to eight measurements. A failure of one measurement does not discard the other results.",

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚪ NIT · docs-style · source: codex

Query-stats help refers to since, from, and to without the -- prefixes readers need to enter those CLI flags.

Evidence: generated.ts:267 says “Use since or both from and to,” and :284, :301, and :309 repeat the bare names. Capacity help at :178 uses --since, --from, and --to. The snapshot calls for literal flag spellings in code formatting. https://github.com/supabase/supabase/blob/6f13230f5269fc192a533617c8cdc238afe14784/apps/docs/style-guide/02-elements.md#use-bold-italics-and-code-for-distinct-purposes

Suggested fix: Use --since, --from, and --to in the source descriptions. For the command description, use “Use --since or specify both --from and --to. The default is the last 30 minutes.”

definition: "v2DisableWarehouse",
summary: "Disable Warehouse replication and access",
description:
"Stops replication and removes the Warehouse publication, FDW and dependent foreign tables, reader group, catalog access and query routing asynchronously. Stored Warehouse data is retained by default. Set delete_data=true to permanently delete the managed catalog schema and dedicated Storage bucket; destination SQL and Storage write permissions are also required. Legacy shared buckets and source Postgres tables are preserved. Reader memberships are not restored on re-enablement. Safe retries return the existing cleanup identity; changing an in-progress data policy returns a conflict. Poll the linked teardown for completion or partial cleanup failures.",

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚪ NIT · docs-style · source: codex

The disable help gives the API query field for permanent deletion and introduces “FDW” without expansion.

Evidence: generated.ts:28 says “Set delete_data=true” and “removes the Warehouse publication, FDW and dependent foreign tables.” Lines 33 and 49–51 bind the CLI flag --delete-data to delete_data. The snapshot distinguishes literal flags in prose and calls for expanding unfamiliar abbreviations. https://github.com/supabase/supabase/blob/6f13230f5269fc192a533617c8cdc238afe14784/apps/docs/style-guide/02-elements.md#use-bold-italics-and-code-for-distinct-purposes https://github.com/supabase/supabase/blob/6f13230f5269fc192a533617c8cdc238afe14784/apps/docs/style-guide/WORD_LIST.md#abbreviations

Suggested fix: Use “Use --delete-data to permanently delete the managed catalog schema and dedicated Storage bucket. This requires destination SQL and Storage write permissions.” Spell out “foreign data wrapper (FDW)” on first use.


export const nouns = {
warehouse: {
description: "Manage the data warehouse for a project",

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚪ NIT · docs-style · source: codex

The top-level warehouse description uses “Manage” where it could name the actions the command group supports.

Evidence: api-command-policy.ts:46 says “Manage the data warehouse for a project.” runtime.ts:365–386 uses that text as the group description. The pinned guidance asks writers to name concrete actions and gives “manage tables” as an example. https://github.com/supabase/supabase/blob/6f13230f5269fc192a533617c8cdc238afe14784/apps/docs/style-guide/WORD_LIST.md#vague-verbs

Suggested fix: Use “Configure and inspect a project’s data warehouse.”

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

run-preview-packages Publish pkg.pr.new preview CLI packages for this PR

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants