Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions .github/ai-review/adjudicate-prompt.md
Original file line number Diff line number Diff line change
Expand Up @@ -96,8 +96,8 @@ higher than `minor`; these findings are advisory and never block the PR.
Verify each `breaking-change` finding against the behavior the PR changes:
refute it only when no released, non-experimental use fails or changes meaning,
when the change only rejects a value that never had a meaning, or when the
change matches the old `SIDE_EFFECTS.md`. The PR's intent, tests and
`SIDE_EFFECTS.md` edits are not counter-evidence. Keep the category
change restores behavior that the current stable release ships. The PR's
intent and its own test or doc edits are not counter-evidence. Keep the category
`breaking-change`, severity `major` and the request ending its `claim`, even
when merged with a Codex finding.

Expand Down
2 changes: 1 addition & 1 deletion .github/ai-review/claude-review-prompt.md
Original file line number Diff line number Diff line change
Expand Up @@ -113,7 +113,7 @@ errors, even when that is the fix the PR set out to make. Use category
`type(scope)!:` title, a `BREAKING CHANGE:` line in the PR description and, on
`develop`, a retarget to `next`. Do not report internal code, tests, CI,
additive changes, experimental commands, newly rejected values that never had a
meaning, or fixes that match the old `SIDE_EFFECTS.md`.
meaning, or fixes that restore behavior the current stable release ships.

## Output

Expand Down
4 changes: 2 additions & 2 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -100,8 +100,8 @@ comment states only the why that the code cannot carry. Most code needs no comme
### When to comment

Write a comment only for an invariant or constraint the types cannot express, an external quirk,
a decision that would otherwise read as a bug, or a pointer to an ADR, `SIDE_EFFECTS.md`, docs
page, or upstream issue. If the rationale needs more than three lines, move it to documentation.
a decision that would otherwise read as a bug, or a pointer to an ADR, docs page, or upstream
issue. If the rationale needs more than three lines, move it to documentation.

### How to comment

Expand Down
18 changes: 6 additions & 12 deletions apps/cli/AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,6 @@ src/commands/<command>/
<command>.command.ts # command definition, flags, layer provision
<command>.handler.ts # command implementation
<command>.errors.ts # domain errors
SIDE_EFFECTS.md # required compatibility contract
```

Register every command in `src/cli/root.ts`. Keep `.format.ts` and `.encoders.ts` pure. Handler
Expand Down Expand Up @@ -59,16 +58,13 @@ limits; put richer content in reference page bodies.

The established CLI surface is a contract: command paths, flags, output text and streams,
filesystem paths, API routes and request shapes, exit codes, and telemetry event timing and
payloads. Use current tests, command `SIDE_EFFECTS.md`, and shipped behavior as the source of
truth. Update tests and side-effect documentation with intentional behavior changes.
payloads. Use current tests, the error-tag fixture, the telemetry event catalog, and shipped
behavior as the source of truth. Update the tests, fixture, catalog entries, and user docs that
an intentional behavior change affects.

State locations are also public: preserve `~/.supabase/…`, `<workdir>/supabase/.temp/…`, and
native keyring entries. Do not move or rename them.

Every command has a `SIDE_EFFECTS.md` based on the [template](src/SIDE_EFFECTS_TEMPLATE.md), documenting exact
files and formats, API calls and shapes, environment variables, and exit codes. Keep it accurate;
it is the command compatibility checklist and an input to E2E coverage.

Every applicable command must preserve these invariants:

1. `linkedProjectCache.cache(ref)` and `telemetryState.flush` run through `Effect.ensuring`, on
Expand Down Expand Up @@ -107,8 +103,6 @@ rather than deleting it; `db remote commit` is the reference:
- Keep the old flag and argument config so existing invocations reach the removal error, not a
parse error, and register the command with `Command.unlisted`.
- Delete the handler, its tests, and its docs pages, and remove its `withDeprecated` annotation.
- `SIDE_EFFECTS.md` documents exit 1, the removal message and suggestion, and the post-run
`telemetry.json` read and write under `SUPABASE_HOME`.
- Test every tombstone through the real parser with and without its old flags, asserting the
`RemovedSurfaceError` message and suggestion.

Expand Down Expand Up @@ -198,7 +192,7 @@ Experimental paths may change outside the stable compatibility promise, but befo
family identify published config, disk, server, and telemetry boundaries and record the approved
compatibility decision in the PR. For the Compute transition, no local compatibility aliases or
migrations are required. Compute error tags intentionally start new fingerprints; server-owned
contracts remain unchanged. Update tests, generated schemas, and side-effect documentation.
contracts remain unchanged. Update tests, generated schemas, and user docs.

## Telemetry

Expand All @@ -225,8 +219,8 @@ path-valued `--output` remains redacted. Keep free-form user content redacted.
Do not remove, rename, or reshape custom events. Preserve login aliasing after token persistence,
link project and organization identity after the link write (including branch-link metadata),
stack-started after health succeeds, and upgrade-suggested billing-gate events with their existing
envelope and payload semantics. Use the catalog and the relevant command `SIDE_EFFECTS.md` for
the complete current event contract.
envelope and payload semantics. Use the catalog and the telemetry tests for the complete current
event contract.

## Error classification

Expand Down
6 changes: 2 additions & 4 deletions apps/cli/docs/command-target.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,11 +2,11 @@

Every command that acts on a database or hosted project announces the target it resolved, once, before it acts. The same identity goes to machine consumers as the JSON `target` object.

This page is the shared reference for how a command's target is chosen, which errors the selection raises, the deprecated selector flags, how a hosted write is confirmed, and what the banner and the JSON `target` carry. [ADR 0033](../../../docs/adr/0033-target-selection-and-hosted-mutation-consent.md) records why. The `SIDE_EFFECTS.md` of every `hosted`, `selectable` and `account` command opens with a `Target:` line that links here and lists only what is specific to that command: its own calls, files, exit codes and prompt, and any selector rule that differs from this page. A `local-only` command has no `Target:` line.
This page is the shared reference for how a command's target is chosen, which errors the selection raises, the deprecated selector flags, how a hosted write is confirmed, and what the banner and the JSON `target` carry. [ADR 0033](../../../docs/adr/0033-target-selection-and-hosted-mutation-consent.md) records why.

## Groups

The `Target:` line names the command's group and its consent default: `Target: <group>, consent default <No|Yes>`, or `Target: <group>, no consent` when the command never asks for hosted-mutation consent. A document that covers several subcommands gives each one's default.
Every command belongs to one group, which decides what it acts on when no target is given and which selector flags it takes. A command that confirms hosted writes through the shared consent prompt also has a consent default.

| Group | Acts on | With no `--remote` | Selector flags |
| ------------ | ------------------------------- | ------------------ | ---------------------------------------------------------------------------- |
Expand Down Expand Up @@ -91,8 +91,6 @@ A selector conflict lists only the selector flags the command has: `Only one of
- `--remote=<url>`: `--password can't be used with --remote=<db-url>. Put the password in the connection string: postgres://USER:PASSWORD@HOST:PORT/postgres`
- the local default: `--password only applies to a linked project. The local database uses [db].password from supabase/config.toml.`, followed by `To use the linked project instead, pass --remote.` in a linked checkout.

A command's own `SIDE_EFFECTS.md` records where else its password can come from and when it is withheld from a target.

## Deprecated selector flags

`--linked`, `--project-ref`, `--db-url` and `--local` (and `gen types --project-id`) still work in v3 and are removed in v4, as is the `linked` value of `db diff --from` and `--to`, which `remote` replaces. Each goes through the same resolver as the `--remote` form it maps to and prints a warning on stderr in every output format, before the `Target:` line. The warning names only the replacement:
Expand Down
31 changes: 31 additions & 0 deletions apps/cli/docs/compute-commands.md
Original file line number Diff line number Diff line change
Expand Up @@ -59,3 +59,34 @@ confirmation first, and both default to no. `compute delete` asks for the
compute's name to be typed back. Pass `--yes`, or set `SUPABASE_YES` in your
shell, to confirm in scripts and CI; without it, a run that cannot prompt fails
before changing anything.

## Excluding files from the build context

`compute push` packages a compute's source directory into the build context, minus the paths
that `[compute.<name>] exclude` matches. Patterns follow `.gitignore`'s path rules:

- A pattern matches that name at any depth unless a `/` other than a trailing one anchors it
at the compute's source directory: `dist/` matches every `dist` directory, `/dist/` only
the top-level one.
- A trailing `/` matches directories only. Repeated trailing separators count as one, so
`dist/` and `dist//` are the same pattern.
- `**` spans directories. Within one segment, `*`, `?` and character classes such as `[a-z]`
work as in the CLI's other glob options; a class negates with `^` (`[^a]`), not `!`.

An excluded directory is not descended into, so everything beneath it is out too, and the
`excluded <n> paths` count on the packaged line counts the directory, not its contents. For
the same reason, a trailing `**` matches what is inside a directory rather than the directory
itself: `cache/**` empties `cache` and keeps the directory, while `cache` removes it.

Re-inclusion with `!` is refused rather than read as a file name: a pattern re-admitting a
path beneath an excluded directory could never be reached. Empty patterns, empty path
segments (`src//dist`) and malformed character classes are refused too. Every refusal names
the compute and the pattern, and happens before anything is packaged or uploaded.

`compute push` applies only the patterns recorded in the config; it has no built-in defaults,
so a compute without an `exclude` key uploads its whole source directory. `compute new`
writes the selected runtime's default list into the project config, where it can be edited.

A source whose every file is excluded fails before upload with an error naming the compute's `exclude` setting.
An excluded symbolic link is skipped before the CLI checks whether it points outside the
source directory, so excluding a hoisted `node_modules` link resolves the escaping-link error.
30 changes: 20 additions & 10 deletions apps/cli/docs/stack-commands.md
Original file line number Diff line number Diff line change
Expand Up @@ -293,8 +293,7 @@ primary database without changing other services (webhooks setup only, creating
`supabase start` while that postgres-only stack is running stops it and starts the full
configured stack, keeping data. `--from-backup` is not supported on the stack path.
A local `db reset` and declarative resets rebuild the existing database while retaining stack
identity, ports, and composition. See
[`db/reset/SIDE_EFFECTS.md`](../src/commands/db/reset/SIDE_EFFECTS.md).
identity, ports, and composition.

A local `gen types` and `inspect db …` resolve the project stack through the same
local database target as `db dump`. They do not start a stack.
Expand Down Expand Up @@ -384,8 +383,7 @@ bucket seeding and stack `storage` commands then also need
`NODE_EXTRA_CA_CERTS="$(mkcert -CAROOT)/rootCA.pem"`), and
containers must reach the host from loopback: on macOS, Docker Desktop, colima and Podman machine
do; on Linux, rootful Docker, rootful Podman and rootless Podman on pasta don't, so a start that
serves the API over TLS fails there with `api.tls: unsupported networking`. The `stack start` side
effects list its errors.
serves the API over TLS fails there with `api.tls: unsupported networking`.

Stack mode keeps its state under `SUPABASE_HOME` and never reads or writes `supabase/.temp`: Storage
uploads live in `stacks/<stack-id>/uploads`, command scratch output (pgdelta debug bundles, Functions
Expand Down Expand Up @@ -436,9 +434,23 @@ release line or major) is refused. The refusal offers to keep the data by pinnin
`local.services.database.version` in your config file, setting `db.major_version` back when the major differs and removing any
`db.orioledb_version` when an OrioleDB build is requested, or to run `supabase stack destroy` and recreate it. `supabase link`
and `supabase stack update` warn when the versions they lock would be refused by an existing stack's
data. A database that never initialized adopts the change. See the [`start` side
effects](../src/commands/experimental/stack/start/SIDE_EFFECTS.md#service-versions-and-the-lock) for
details.
data. A database that never initialized adopts the change.

The project lease is `supabase/.supabase.lock.lease`. Before taking it, the CLI adds it and the
lock's staged writes (`.supabase.lock.*.tmp`) to `supabase/.gitignore` when they are missing. A
frozen start reads the lock without the lease and leaves `supabase/.gitignore` untouched; lock
writes are atomic renames, so it never sees a partial file.
When a `linked` service's observed release cannot be fetched because the release host is
unreachable, the start keeps going with the bundled version, recorded as `unobserved`, and warns;
any other failed resolution fails the start without writing the lock.

`supabase db reset`, the shadow database of `supabase db diff`, and the temporary Functions instance
of `supabase functions serve` read the lock without the lease and never resolve. Without a lock
they use the versions this CLI bundles, and an explicit service version it does not bundle fails
with `supabase/supabase.lock not found; run supabase start to create it`. A stale lock fails with
`is stale for: <service> (<reason>)`, except for a shadow database of a remote with a
`[remotes.<ref>]` block, which takes the bundled version of each stale service and fails only when
one of them has none.

## Port intents

Expand Down Expand Up @@ -548,9 +560,7 @@ core. A project with no `[storage.buckets]` or
`[storage.vector.buckets]` configured resolves no credentials and prints nothing. Auto-confirm is
safe here since a first-start stack has no pre-existing buckets. Any other unusable Storage state,
a missing capability/endpoint, a gateway activation failure, or an invalid bucket entry fails the
`start` command; startup does not silently skip the configured seed. See
[`stack/start/SIDE_EFFECTS.md`](../src/commands/experimental/stack/start/SIDE_EFFECTS.md).
`start` command; startup does not silently skip the configured seed.

**A local `db reset` and declarative reset** reapply the catalog, migrations, and seeds before
resuming the saved composition. Bucket-seeding failures warn after the database reset succeeds.
See [`db/reset/SIDE_EFFECTS.md`](../src/commands/db/reset/SIDE_EFFECTS.md).
Loading
Loading