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.
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.
…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.
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>
Supabase CLI previewnpx --yes https://pkg.pr.new/supabase/cli/supabase@cdcbb7b140360f986a4a1926cfdd730e2c1c1fe2Preview package for commit |
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>
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.
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.
|
/ai-review |
There was a problem hiding this comment.
🤖 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 Warehouseaddoverrides 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.
| 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 }); |
There was a problem hiding this comment.
🟠 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}`, |
There was a problem hiding this comment.
🟡 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."), |
There was a problem hiding this comment.
🟡 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"; |
There was a problem hiding this comment.
🟡 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.
| 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); |
There was a problem hiding this comment.
🟡 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'`.", |
There was a problem hiding this comment.
⚪ 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.", |
There was a problem hiding this comment.
⚪ 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.", |
There was a problem hiding this comment.
⚪ 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.", |
There was a problem hiding this comment.
⚪ 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", |
There was a problem hiding this comment.
⚪ 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.”
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;supabase warehouse tables listlists 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-byand--partition-bytake a JSON value for their rule, and--reset-tablecopies the table again when the layout changes;supabase warehouse inspect query-statsreads Warehouse query statistics over a time range (--since, or--fromand--to), as labelled sample series;supabase warehouse inspect capacityreads Warehouse capacity, admission and activation measurements over a time range, in the same form;supabase warehouse replication addadds one eligible table (--schemaand--table) or a schema's currently eligible tables (--schemaalone) to replication;supabase warehouse replication removeremoves one selected table or all selected tables of a schema from replication, keeping the data already in Warehouse;supabase warehouse replication resyncresets and rebuilds one selected table (--schemaand--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: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 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-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 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 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 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(andlinksfor--wait) in the spec, and its operation ID ingeneratedOperations. The spec edit lands upstream, or inpackages/api/scripts/openapi-overrides.jsonuntil it is published.pnpm run generatedownloads the spec, applies the overrides and writes the rest. A new noun is onenounsentry; a noun with its own feature also needs thatexperimental.<feature>key inpackages/config/src/experimental.tsand infeatureSchemas/featureKeysinapps/cli/src/shared/config/experimental-feature.ts, 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, so the spec can name every operation for other consumers and a name stays inert until its operation is listed. Off the allowlist,x-operationis read only on an operation that an allowlisted operation links to (see below).group"warehouse"→supabase warehouse …"warehouse.tables"→supabase warehouse tables …methodlist,getorenable. A read of a singleton facet is named after the facet, such asstatusorconnection, and a report under aninspectgroup is named after the report, such asquery-stats. Every command word is lowercase kebab-case. Names are reviewed in the allowlist PR through thegenerated.mddiff."enable"→supabase warehouse enablepoll--waitand--timeout.The extension is decoded strictly: an unknown key fails generation, and so does a name with only one of
groupandmethod. A name is optional whenpollis 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.jsonrenames the setup read towarehouse.setups getand adds itspoll.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.pollfields:status"/data/attributes/status"succeeded["succeeded"]failedoperation_failed(exit 1).["failed"]error"/data/attributes/status_error"inspect"v2-get-warehouse-status"--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
--waitdeclarespolland 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/apiwhile waiting. Itspoll.inspectnames 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
linksof 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,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. 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
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.nullincluded, 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"):In the CLI:
api-command-policy.tsholds:generatedOperations: the operations that generate commands, todayv2-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-replicationandv2-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 isconfirmDescription, which prints the operation's API description before the interactive consent prompt. The replication commands,disableandtables layout updateuse 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 experimentalfeaturethat gates it and the help text of the sub-groups the generator creates (Warehouse describesreplication,inspect,tables,tables.layoutandteardowns). A noun is always a new top-level group: generated commands never join a hand-written one. 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:
x-operationis invalid;poll.inspect;The generator takes everything else from the spec:
required, repeatability and help text;/data/attributes/schema, …);warehouse_setup);@supabase/api/permissions, not generated here).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--waitor with registered global flags such as--profile, and a name used by more than one of path, query and body;dry_run;refpath parameter or with more than one other path parameter, path parameters that aren't strings, cookie parameters, header parameters other thanAuthorization,Content-TypeandAccept, query parameters that aren't scalars, bodies that aren't a JSON:API envelope, and numeric body fields;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. The CLI builds theEXAMPLESentry 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:--dry-runprints 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: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. 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 apointskey 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 printsNo results. Progress shows as a spinner, and during--waitit 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 (nullfor an empty body). This keeps| jqand other consumers stable. The legacy-o/--outputflag 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,
--bodyor--file), so options such asdisable --delete-dataorlayout update --reset-tableshow before you confirm. A command withconfirmDescriptionalso prints its API description first, soreplication addwarns that the pipeline restarts before you answer. 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 poll-only read, the hint names the command of itspoll.inspectoperation, 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, 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
contextobject carries details for some codes:operation_failedhas{status}andwait_timeouthas{timeout_ms, last_status}(last_statusis null when no read succeeded). A plan-gated 4xx (server body codeentitlement_required) keeps its status-derivedcodeand addsentitlement: {feature, upgrade_url}in place of the permission hint, 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, any-o/--output, an invalid--timeout(checked even without--wait), conflicting target selectors, no linked project, missing--yescancelled: consent declined or interruptedHints are built where the information is still available:
Run `supabase login`.Other changes
packages/api. Enable, disable, the setup and teardown reads and their links come from the published spec.openapi-overrides.jsonadds 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 towarehouse.setups getwithx-operation.poll.inspect.generate.tsnormalizes nullableoneOfunions as it already didanyOf. 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:generateandapi-commands:check, which is part ofcheck:all. Rootgenerateregenerates@supabase/apiand@supabase/stackfirst, then runssupabase#api-commands:generateandschemas:generatein 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.ymlregenerates command data and the reference together with the spec. oxlint ignoresgenerated.ts.linkedDbResolverRuntimeLayerbecomeslazyManagementApiRuntimeLayer, shared bydb,logs,migration,pulland the generated commands, so the API client is built only when a command needs it.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.generated.mdlists each command's route, experimental gate, flags and bindings, and its--waitread;api-commands:checkkeeps it in sync. Generated commands get no per-command folder.Not in this PR
x-operationand the links to the published spec.surface.json) and a breaking-change gate built on it. An extraction without a CI-checked consumer was dropped from this PR.experimentalstage.