Skip to content

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

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

jgoux wants to merge 13 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.

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;
  • machine-readable command surface.

New commands should then need only an x-operation entry in the spec. The generator and runtime already cover more shapes than Warehouse uses today: one positional argument, header flags, and body fields set only through --body/--file. Fixture specs exercise them in tests, so the next resources shouldn't need runtime changes. This is an alternative to the hand-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 two committed data modules and a generated per-command reference. At startup, one generic runtime builds real Effect CLI commands from that data. There is no per-command handler code.

flowchart LR
  subgraph build["Build time: pnpm generate / api-commands:check"]
    spec["packages/api<br/>openapi.json + typed client"]
    policy["api-command-policy.ts<br/>(allowlist, poll targets, nouns, verbs)"]
    gen["scripts/generate-api-commands.ts<br/>derive + lints"]
    data["generated.ts<br/>(command data)"]
    schemas["generated.schemas.ts<br/>(JSON Schemas)"]
    ref["generated.md<br/>(per-command reference)"]
    spec --> gen
    policy --> gen
    gen --> data
    gen --> schemas
    gen --> ref
  end
  subgraph run["Runtime"]
    rt["runtime.ts<br/>apiCommandGroup()"]
    root["cli/root.ts<br/>mounts each noun whose feature is enabled"]
    exec["request → send → --wait → output"]
    errs["errors.standard envelope"]
    data --> rt --> root
    rt --> exec --> errs
  end
  subgraph contract["Contract extraction"]
    surface["commandSurface()<br/>walks the mounted tree"]
    root --> surface
    schemas -. lazy import .-> surface
  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 the verb vocabulary. It has no per-command overrides and no per-command folder.

A command for an existing noun takes two edits: its x-operation (and links for --wait) in the spec, and its operation ID in generatedOperations. pnpm run generate writes the rest. A new noun is one nouns entry; a noun with its own feature also needs that experimental.<feature> config key, 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; x-operation elsewhere is ignored, except on a hidden poll target (see below), where only its poll is used.

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. "warehouse" → supabase warehouse …
"warehouse.tables" → supabase warehouse tables …
method The verb, which is the last command word. It must be in the CLI's verb vocabulary, so every new verb is a deliberate, reviewed change. With group, the whole path is at most 4 lowercase kebab-case words. "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. It holds only what another consumer of the spec (for example an MCP server generating tools) would also need. CLI-only choices such as flag names stay in the CLI. Its name and ownership will be agreed with the API owners before it moves upstream; until then the warehouse entries live in openapi-overrides.json.

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"

--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 can stay hidden: the CLI calls it through @supabase/api while waiting, but it has no command of its own. The policy lists each hidden poll target together with a generated read-only command that inspects the same state, and a failed or timed-out wait names that command in its hint. Hidden targets go through the same checks as generated operations (experimental stage, 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, and their flags are marked sensitive in the command surface. Generation fails when a body field looks like a credential (password, secret, token, key, private) and isn't marked. It also fails for a secret the preview can't mask: one held anywhere inside a body field that has no flag, and any secret header or query parameter.

Flags follow a convention. A flag is the kebab-case field name. An array field with a plural name gets a singular, repeatable flag, so 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 header parameter becomes a flag, so Idempotency-Key becomes --idempotency-key. Authorization, Content-Type and Accept stay with the client.
  • A body field that can't be a flag, such as a nested object, is set through --body or --file only.

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 → hidden poll target, no command
"x-operation": { "group": "warehouse.setups", "method": "get", "poll": {
  "status": "/data/attributes/status", "succeeded": ["succeeded"], "failed": ["failed"],
  "error": "/data/attributes/status_error"
} }

// 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" }

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

  • generatedOperations: the operations that generate commands, today v2-enable-warehouse, v2-disable-warehouse, v2-get-warehouse-status, v2-get-warehouse-connection and v2-get-warehouse-teardown. It keeps spec annotations from reaching the CLI on their own while the design settles, and will be removed once it does.
  • pollTargets: hidden polling reads a generated link may target, each mapped to the generated command that inspects its state. Today v2-get-warehouse-setup → v2-get-warehouse-status.
  • verbVocabulary: list, get, create, update, delete, enable, disable, status, connection, add, remove, resync.
  • nouns: each top-level group, with its help description, the experimental feature that gates it, and the help text of its sub-groups. 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 a polled operation that is neither generated nor listed in pollTargets;
  • a pollTargets entry that no link uses, or whose key is also a generated operation;
  • 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);
  • response kind;
  • FGA permissions.

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, verbs outside the vocabulary, command words that aren't kebab-case, and paths longer than four words;
  • name collisions with hand-written commands or between generated ones, and a path that is both a command and a group;
  • non-kebab or duplicate flags, flags that collide with runtime flags such as --body or --wait, and a name used by more than one of path, header, 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 or query parameters that aren't scalars, non-object bodies, recursive schemas and unconverted keywords;
  • secrets the dry-run preview can't mask, as described above;
  • binary responses;
  • 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 EXAMPLES entry is built by the CLI. 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.
  --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 --schema <schema>

PERMISSIONS
  Scoped access token:
    Required:
      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:

$ 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. Progress shows as a spinner, and during --wait it shows the current status. When stdout is not a terminal, in agent runs, with --output-format json|stream-json or with -o json, stdout is the API response exactly as sent, as JSON. This keeps | jq and other consumers stable. --output-format text or -o pretty forces the rendering, -o yaml prints YAML, and any other -o value is a usage error. A dry run follows the same rule: it prints the request as text, or as a JSON or YAML document. Unlike most commands, the default depends on whether stdout is a terminal. This matches how these commands already render errors, so one run never mixes a text result with a JSON error.

Consent follows ADR 0033. Mutations ask with a default of no. Non-interactive runs need --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 hidden poll target, the hint names its inspect command, 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, a machine -o, or stdout that isn't a TTY), the last stderr line is one JSON document:

{"code":"conflict","status":409,"message":"The selection changed: Re-run enable.","hint":null,"api_code":"selection_conflict"}

An optional context object carries details for some codes: operation_failed has {status} and wait_timeout has {timeout_ms}. A plan-gated 4xx (entitlement_required) adds entitlement: {feature, upgrade_url}, 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, unsupported -o, 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.

Machine-readable command surface

command-surface.ts walks the mounted command tree through CommandSpec.resolve. Generated and hand-written commands therefore produce the same document, the one a future surface.json, the docs and agent tooling can consume. Its shape:

{
  globalFlags: { yes, output, output-format, profile, … },   // resolved once from the root
  commands:    { "<path>": entry, … },                         // default tree (warehouse hidden)
  variants:    { warehouse: { "warehouse": …, "warehouse enable": …, "warehouse disable": …, "warehouse status": …, … } }   // one per noun feature
}

An abridged entry:

"warehouse enable": {
  "path": ["warehouse", "enable"],
  "summary": "Enable Warehouse replication (experimental)",
  "stage": { "status": "experimental", "gate": { "kind": "feature", "feature": "warehouse" } },
  "target": { "group": "hosted", "consent": "no" },
  "permissions": { "status": "mapped", "operations": [
    { "operationId": "v2-enable-warehouse", "kind": "required" },
    { "operationId": "v2-get-warehouse-setup", "kind": "required", "when": [{ "flag": "wait", "is": true }] },
    …
  ]},
  "flags": { "table": { "type": "string", "variadic": true, "required": false, … }, "wait": { … }, … },
  "result": { "anyOf": [ { "title": "response" }, { "title": "waited" }, { "title": "dryRun" } ] },
  "errors": "standard",
  "api": {
    "operationId": "v2-enable-warehouse",
    "request": { "contentType": "application/json", "schema": { … } },
    "bindings": [ { "location": "path", "name": "ref", "source": "target" },
                  { "location": "body", "pointer": "/data/attributes/schema", "source": "flag", "flag": "schema" }, … ]
  }
}

generated.schemas.ts is loaded only by the surface walk, through a dynamic import. The CLI never bundles the schemas at runtime, and a test checks this with a Bun.build metafile.

This PR adds the extraction but doesn't write a committed surface.json file yet.

Other changes

  • packages/api. The warehouse operations, with their x-operation metadata and the enable→setup and disable→teardown links, are added to openapi-overrides.json until they appear in the published spec. 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, which runs after @supabase/api#generate and is part of root generate, and api-commands:check, which is part of check:all. api-package-sync.yml regenerates command data and the reference together with the spec. oxlint ignores generated.ts; knip treats both data modules as entry points.
  • CLI runtime. 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. Generated commands share one SIDE_EFFECTS.md for gating, consent, files, --wait, exit codes, telemetry and output. The generated generated.md lists each command's route, flags and bindings, and its --wait read; api-commands:check keeps it in sync. apps/cli/AGENTS.md now reserves per-command folders for hand-written commands.

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.
  • Removing the generatedOperations allowlist.
  • A committed surface.json plus a breaking-change gate built on the surface walk.
  • 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.

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

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

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants