From 1c49238deae4b8a8a80bca0b5f06d83f40d4c5c7 Mon Sep 17 00:00:00 2001 From: Julien Goux Date: Thu, 19 Nov 2026 21:15:46 +0000 Subject: [PATCH] chore(cli): remove per-command SIDE_EFFECTS.md files (#7727) Removes the per-command `SIDE_EFFECTS.md` files and `apps/cli/src/SIDE_EFFECTS_TEMPLATE.md`. They duplicated what the handlers, tests and user docs already state, and they drifted out of date. - Rationale that existed only in those files now lives next to the code as short comments, or in the existing guides (`apps/cli/docs/compute-commands.md`, `stack-commands.md`, `command-target.md`). - `apps/cli/AGENTS.md` names tests, the error-tag fixture, the telemetry event catalog and shipped behavior as the source of truth. - The automated review prompts judge breaking changes against what the stable release ships and what the tests at the merge base assert, instead of the old `SIDE_EFFECTS.md`. - ADRs are left unchanged as historical records. --- .github/ai-review/adjudicate-prompt.md | 4 +- .github/ai-review/claude-review-prompt.md | 2 +- AGENTS.md | 4 +- apps/cli/AGENTS.md | 18 +- apps/cli/docs/command-target.md | 6 +- apps/cli/docs/compute-commands.md | 31 ++ apps/cli/docs/stack-commands.md | 30 +- apps/cli/src/SIDE_EFFECTS_TEMPLATE.md | 125 ----- .../command-internal/db-connection.errors.ts | 4 +- .../src/commands/backups/list/SIDE_EFFECTS.md | 99 ---- .../commands/backups/restore/SIDE_EFFECTS.md | 91 ---- .../src/commands/bootstrap/SIDE_EFFECTS.md | 202 ------- .../commands/branches/create/SIDE_EFFECTS.md | 73 --- .../commands/branches/delete/SIDE_EFFECTS.md | 63 --- .../commands/branches/disable/SIDE_EFFECTS.md | 61 --- .../src/commands/branches/get/SIDE_EFFECTS.md | 61 --- .../commands/branches/list/SIDE_EFFECTS.md | 117 ---- .../commands/branches/pause/SIDE_EFFECTS.md | 57 -- .../commands/branches/unpause/SIDE_EFFECTS.md | 60 --- .../commands/branches/update/SIDE_EFFECTS.md | 62 --- .../src/commands/completion/SIDE_EFFECTS.md | 125 ----- .../commands/config/convert/SIDE_EFFECTS.md | 116 ---- .../src/commands/config/diff/SIDE_EFFECTS.md | 175 ------ .../src/commands/config/pull/SIDE_EFFECTS.md | 252 --------- .../src/commands/config/push/SIDE_EFFECTS.md | 392 -------------- .../commands/config/validate/SIDE_EFFECTS.md | 77 --- .../src/commands/db/advisors/SIDE_EFFECTS.md | 103 ---- .../src/commands/db/branch/SIDE_EFFECTS.md | 69 --- apps/cli/src/commands/db/diff/SIDE_EFFECTS.md | 397 -------------- apps/cli/src/commands/db/diff/pgadmin-diff.ts | 2 +- apps/cli/src/commands/db/dump/SIDE_EFFECTS.md | 138 ----- apps/cli/src/commands/db/lint/SIDE_EFFECTS.md | 103 ---- apps/cli/src/commands/db/pull/SIDE_EFFECTS.md | 247 --------- apps/cli/src/commands/db/push/SIDE_EFFECTS.md | 173 ------ .../cli/src/commands/db/query/SIDE_EFFECTS.md | 134 ----- .../src/commands/db/query/query.command.ts | 2 +- .../db/remote/changes/SIDE_EFFECTS.md | 62 --- .../commands/db/remote/commit/SIDE_EFFECTS.md | 62 --- .../cli/src/commands/db/reset/SIDE_EFFECTS.md | 373 ------------- .../declarative/generate/SIDE_EFFECTS.md | 123 ----- .../schema/declarative/sync/SIDE_EFFECTS.md | 194 ------- .../cli/src/commands/db/start/SIDE_EFFECTS.md | 267 --------- apps/cli/src/commands/db/test/SIDE_EFFECTS.md | 81 --- apps/cli/src/commands/domains/SIDE_EFFECTS.md | 115 ---- .../src/commands/domains/domains.format.ts | 2 +- .../src/commands/encryption/SIDE_EFFECTS.md | 95 ---- .../update-root-key.handler.ts | 2 +- .../compute/delete/SIDE_EFFECTS.md | 107 ---- .../experimental/compute/list/SIDE_EFFECTS.md | 88 --- .../experimental/compute/logs/SIDE_EFFECTS.md | 175 ------ .../experimental/compute/new/SIDE_EFFECTS.md | 151 ------ .../experimental/compute/new/new.handler.ts | 2 +- .../experimental/compute/push/SIDE_EFFECTS.md | 190 ------- .../compute/status/SIDE_EFFECTS.md | 92 ---- .../stack/destroy/SIDE_EFFECTS.md | 110 ---- .../stack/install/SIDE_EFFECTS.md | 100 ---- .../experimental/stack/list/SIDE_EFFECTS.md | 42 -- .../experimental/stack/logs/SIDE_EFFECTS.md | 89 --- .../stack/outdated/SIDE_EFFECTS.md | 67 --- .../experimental/stack/prune/SIDE_EFFECTS.md | 50 -- .../stack/restart/SIDE_EFFECTS.md | 47 -- .../experimental/stack/start/SIDE_EFFECTS.md | 466 ---------------- .../experimental/stack/start/start.handler.ts | 4 +- .../experimental/stack/status/SIDE_EFFECTS.md | 104 ---- .../experimental/stack/stop/SIDE_EFFECTS.md | 57 -- .../experimental/stack/update/SIDE_EFFECTS.md | 114 ---- .../src/commands/feedback/add/SIDE_EFFECTS.md | 152 ------ .../commands/feedback/delete/SIDE_EFFECTS.md | 145 ----- .../commands/functions/delete/SIDE_EFFECTS.md | 81 --- .../commands/functions/deploy/SIDE_EFFECTS.md | 143 ----- .../functions/download/SIDE_EFFECTS.md | 162 ------ .../commands/functions/list/SIDE_EFFECTS.md | 79 --- .../commands/functions/new/SIDE_EFFECTS.md | 87 --- .../commands/functions/serve/SIDE_EFFECTS.md | 182 ------- .../commands/gen/bearer-jwt/SIDE_EFFECTS.md | 110 ---- .../cli/src/commands/gen/keys/SIDE_EFFECTS.md | 63 --- .../commands/gen/signing-key/SIDE_EFFECTS.md | 64 --- .../src/commands/gen/types/SIDE_EFFECTS.md | 316 ----------- apps/cli/src/commands/init/SIDE_EFFECTS.md | 103 ---- .../commands/init/init.integration.test.ts | 3 +- .../src/commands/inspect/db/SIDE_EFFECTS.md | 153 ------ .../commands/inspect/report/SIDE_EFFECTS.md | 134 ----- apps/cli/src/commands/issue/SIDE_EFFECTS.md | 13 - apps/cli/src/commands/link/SIDE_EFFECTS.md | 275 ---------- apps/cli/src/commands/login/SIDE_EFFECTS.md | 86 --- apps/cli/src/commands/logout/SIDE_EFFECTS.md | 73 --- apps/cli/src/commands/logs/SIDE_EFFECTS.md | 75 --- .../commands/migration/down/SIDE_EFFECTS.md | 92 ---- .../commands/migration/fetch/SIDE_EFFECTS.md | 93 ---- .../commands/migration/list/SIDE_EFFECTS.md | 77 --- .../commands/migration/new/SIDE_EFFECTS.md | 64 --- .../commands/migration/repair/SIDE_EFFECTS.md | 107 ---- .../commands/migration/squash/SIDE_EFFECTS.md | 184 ------- .../commands/migration/squash/squash.diff.ts | 4 +- .../src/commands/migration/up/SIDE_EFFECTS.md | 92 ---- .../commands/network-bans/get/SIDE_EFFECTS.md | 93 ---- .../network-bans/remove/SIDE_EFFECTS.md | 97 ---- .../network-restrictions/get/SIDE_EFFECTS.md | 104 ---- .../update/SIDE_EFFECTS.md | 131 ----- .../commands/notebooks/pull/SIDE_EFFECTS.md | 131 ----- .../commands/notebooks/push/SIDE_EFFECTS.md | 143 ----- .../src/commands/orgs/create/SIDE_EFFECTS.md | 127 ----- .../src/commands/orgs/list/SIDE_EFFECTS.md | 99 ---- .../postgres-config/delete/SIDE_EFFECTS.md | 120 ----- .../postgres-config/get/SIDE_EFFECTS.md | 104 ---- .../postgres-config/update/SIDE_EFFECTS.md | 123 ----- .../cli/src/commands/projects/SIDE_EFFECTS.md | 99 ---- .../projects/api-keys/SIDE_EFFECTS.md | 110 ---- .../commands/projects/create/SIDE_EFFECTS.md | 113 ---- .../commands/projects/delete/SIDE_EFFECTS.md | 118 ---- .../commands/projects/list/SIDE_EFFECTS.md | 113 ---- apps/cli/src/commands/pull/SIDE_EFFECTS.md | 337 ------------ apps/cli/src/commands/pull/pull.types.ts | 2 +- .../src/commands/secrets/list/SIDE_EFFECTS.md | 96 ---- .../src/commands/secrets/set/SIDE_EFFECTS.md | 98 ---- .../commands/secrets/unset/SIDE_EFFECTS.md | 107 ---- .../src/commands/seed/buckets/SIDE_EFFECTS.md | 266 --------- .../cli/src/commands/services/SIDE_EFFECTS.md | 94 ---- .../snippets/download/SIDE_EFFECTS.md | 92 ---- .../snippets/download/download.handler.ts | 2 +- .../commands/snippets/list/SIDE_EFFECTS.md | 104 ---- .../ssl-enforcement/get/SIDE_EFFECTS.md | 111 ---- .../ssl-enforcement/update/SIDE_EFFECTS.md | 114 ---- .../update/update.live.test.ts | 4 +- apps/cli/src/commands/sso/add/SIDE_EFFECTS.md | 110 ---- .../cli/src/commands/sso/info/SIDE_EFFECTS.md | 83 --- .../cli/src/commands/sso/list/SIDE_EFFECTS.md | 80 --- .../src/commands/sso/remove/SIDE_EFFECTS.md | 84 --- .../cli/src/commands/sso/show/SIDE_EFFECTS.md | 87 --- apps/cli/src/commands/sso/sso.format.ts | 4 +- .../src/commands/sso/update/SIDE_EFFECTS.md | 117 ---- apps/cli/src/commands/start/SIDE_EFFECTS.md | 506 ------------------ apps/cli/src/commands/start/start.handler.ts | 11 +- .../commands/start/start.integration.test.ts | 2 +- apps/cli/src/commands/status/SIDE_EFFECTS.md | 402 -------------- apps/cli/src/commands/stop/SIDE_EFFECTS.md | 185 ------- .../src/commands/storage/cp/SIDE_EFFECTS.md | 151 ------ .../src/commands/storage/ls/SIDE_EFFECTS.md | 133 ----- .../src/commands/storage/mv/SIDE_EFFECTS.md | 134 ----- .../src/commands/storage/rm/SIDE_EFFECTS.md | 159 ------ .../telemetry/disable/SIDE_EFFECTS.md | 76 --- .../commands/telemetry/enable/SIDE_EFFECTS.md | 76 --- .../commands/telemetry/status/SIDE_EFFECTS.md | 66 --- apps/cli/src/commands/test/db/SIDE_EFFECTS.md | 167 ------ .../cli/src/commands/test/new/SIDE_EFFECTS.md | 65 --- apps/cli/src/commands/unlink/SIDE_EFFECTS.md | 73 --- .../activate/SIDE_EFFECTS.md | 97 ---- .../check-availability/SIDE_EFFECTS.md | 91 ---- .../vanity-subdomains/delete/SIDE_EFFECTS.md | 88 --- .../vanity-subdomains/get/SIDE_EFFECTS.md | 87 --- apps/cli/src/commands/whoami/SIDE_EFFECTS.md | 104 ---- .../cli/src/shared/compute/compute-exclude.ts | 6 +- apps/cli/src/shared/logs/request.ts | 1 + 153 files changed, 93 insertions(+), 16722 deletions(-) delete mode 100644 apps/cli/src/SIDE_EFFECTS_TEMPLATE.md delete mode 100644 apps/cli/src/commands/backups/list/SIDE_EFFECTS.md delete mode 100644 apps/cli/src/commands/backups/restore/SIDE_EFFECTS.md delete mode 100644 apps/cli/src/commands/bootstrap/SIDE_EFFECTS.md delete mode 100644 apps/cli/src/commands/branches/create/SIDE_EFFECTS.md delete mode 100644 apps/cli/src/commands/branches/delete/SIDE_EFFECTS.md delete mode 100644 apps/cli/src/commands/branches/disable/SIDE_EFFECTS.md delete mode 100644 apps/cli/src/commands/branches/get/SIDE_EFFECTS.md delete mode 100644 apps/cli/src/commands/branches/list/SIDE_EFFECTS.md delete mode 100644 apps/cli/src/commands/branches/pause/SIDE_EFFECTS.md delete mode 100644 apps/cli/src/commands/branches/unpause/SIDE_EFFECTS.md delete mode 100644 apps/cli/src/commands/branches/update/SIDE_EFFECTS.md delete mode 100644 apps/cli/src/commands/completion/SIDE_EFFECTS.md delete mode 100644 apps/cli/src/commands/config/convert/SIDE_EFFECTS.md delete mode 100644 apps/cli/src/commands/config/diff/SIDE_EFFECTS.md delete mode 100644 apps/cli/src/commands/config/pull/SIDE_EFFECTS.md delete mode 100644 apps/cli/src/commands/config/push/SIDE_EFFECTS.md delete mode 100644 apps/cli/src/commands/config/validate/SIDE_EFFECTS.md delete mode 100644 apps/cli/src/commands/db/advisors/SIDE_EFFECTS.md delete mode 100644 apps/cli/src/commands/db/branch/SIDE_EFFECTS.md delete mode 100644 apps/cli/src/commands/db/diff/SIDE_EFFECTS.md delete mode 100644 apps/cli/src/commands/db/dump/SIDE_EFFECTS.md delete mode 100644 apps/cli/src/commands/db/lint/SIDE_EFFECTS.md delete mode 100644 apps/cli/src/commands/db/pull/SIDE_EFFECTS.md delete mode 100644 apps/cli/src/commands/db/push/SIDE_EFFECTS.md delete mode 100644 apps/cli/src/commands/db/query/SIDE_EFFECTS.md delete mode 100644 apps/cli/src/commands/db/remote/changes/SIDE_EFFECTS.md delete mode 100644 apps/cli/src/commands/db/remote/commit/SIDE_EFFECTS.md delete mode 100644 apps/cli/src/commands/db/reset/SIDE_EFFECTS.md delete mode 100644 apps/cli/src/commands/db/schema/declarative/generate/SIDE_EFFECTS.md delete mode 100644 apps/cli/src/commands/db/schema/declarative/sync/SIDE_EFFECTS.md delete mode 100644 apps/cli/src/commands/db/start/SIDE_EFFECTS.md delete mode 100644 apps/cli/src/commands/db/test/SIDE_EFFECTS.md delete mode 100644 apps/cli/src/commands/domains/SIDE_EFFECTS.md delete mode 100644 apps/cli/src/commands/encryption/SIDE_EFFECTS.md delete mode 100644 apps/cli/src/commands/experimental/compute/delete/SIDE_EFFECTS.md delete mode 100644 apps/cli/src/commands/experimental/compute/list/SIDE_EFFECTS.md delete mode 100644 apps/cli/src/commands/experimental/compute/logs/SIDE_EFFECTS.md delete mode 100644 apps/cli/src/commands/experimental/compute/new/SIDE_EFFECTS.md delete mode 100644 apps/cli/src/commands/experimental/compute/push/SIDE_EFFECTS.md delete mode 100644 apps/cli/src/commands/experimental/compute/status/SIDE_EFFECTS.md delete mode 100644 apps/cli/src/commands/experimental/stack/destroy/SIDE_EFFECTS.md delete mode 100644 apps/cli/src/commands/experimental/stack/install/SIDE_EFFECTS.md delete mode 100644 apps/cli/src/commands/experimental/stack/list/SIDE_EFFECTS.md delete mode 100644 apps/cli/src/commands/experimental/stack/logs/SIDE_EFFECTS.md delete mode 100644 apps/cli/src/commands/experimental/stack/outdated/SIDE_EFFECTS.md delete mode 100644 apps/cli/src/commands/experimental/stack/prune/SIDE_EFFECTS.md delete mode 100644 apps/cli/src/commands/experimental/stack/restart/SIDE_EFFECTS.md delete mode 100644 apps/cli/src/commands/experimental/stack/start/SIDE_EFFECTS.md delete mode 100644 apps/cli/src/commands/experimental/stack/status/SIDE_EFFECTS.md delete mode 100644 apps/cli/src/commands/experimental/stack/stop/SIDE_EFFECTS.md delete mode 100644 apps/cli/src/commands/experimental/stack/update/SIDE_EFFECTS.md delete mode 100644 apps/cli/src/commands/feedback/add/SIDE_EFFECTS.md delete mode 100644 apps/cli/src/commands/feedback/delete/SIDE_EFFECTS.md delete mode 100644 apps/cli/src/commands/functions/delete/SIDE_EFFECTS.md delete mode 100644 apps/cli/src/commands/functions/deploy/SIDE_EFFECTS.md delete mode 100644 apps/cli/src/commands/functions/download/SIDE_EFFECTS.md delete mode 100644 apps/cli/src/commands/functions/list/SIDE_EFFECTS.md delete mode 100644 apps/cli/src/commands/functions/new/SIDE_EFFECTS.md delete mode 100644 apps/cli/src/commands/functions/serve/SIDE_EFFECTS.md delete mode 100644 apps/cli/src/commands/gen/bearer-jwt/SIDE_EFFECTS.md delete mode 100644 apps/cli/src/commands/gen/keys/SIDE_EFFECTS.md delete mode 100644 apps/cli/src/commands/gen/signing-key/SIDE_EFFECTS.md delete mode 100644 apps/cli/src/commands/gen/types/SIDE_EFFECTS.md delete mode 100644 apps/cli/src/commands/init/SIDE_EFFECTS.md delete mode 100644 apps/cli/src/commands/inspect/db/SIDE_EFFECTS.md delete mode 100644 apps/cli/src/commands/inspect/report/SIDE_EFFECTS.md delete mode 100644 apps/cli/src/commands/issue/SIDE_EFFECTS.md delete mode 100644 apps/cli/src/commands/link/SIDE_EFFECTS.md delete mode 100644 apps/cli/src/commands/login/SIDE_EFFECTS.md delete mode 100644 apps/cli/src/commands/logout/SIDE_EFFECTS.md delete mode 100644 apps/cli/src/commands/logs/SIDE_EFFECTS.md delete mode 100644 apps/cli/src/commands/migration/down/SIDE_EFFECTS.md delete mode 100644 apps/cli/src/commands/migration/fetch/SIDE_EFFECTS.md delete mode 100644 apps/cli/src/commands/migration/list/SIDE_EFFECTS.md delete mode 100644 apps/cli/src/commands/migration/new/SIDE_EFFECTS.md delete mode 100644 apps/cli/src/commands/migration/repair/SIDE_EFFECTS.md delete mode 100644 apps/cli/src/commands/migration/squash/SIDE_EFFECTS.md delete mode 100644 apps/cli/src/commands/migration/up/SIDE_EFFECTS.md delete mode 100644 apps/cli/src/commands/network-bans/get/SIDE_EFFECTS.md delete mode 100644 apps/cli/src/commands/network-bans/remove/SIDE_EFFECTS.md delete mode 100644 apps/cli/src/commands/network-restrictions/get/SIDE_EFFECTS.md delete mode 100644 apps/cli/src/commands/network-restrictions/update/SIDE_EFFECTS.md delete mode 100644 apps/cli/src/commands/notebooks/pull/SIDE_EFFECTS.md delete mode 100644 apps/cli/src/commands/notebooks/push/SIDE_EFFECTS.md delete mode 100644 apps/cli/src/commands/orgs/create/SIDE_EFFECTS.md delete mode 100644 apps/cli/src/commands/orgs/list/SIDE_EFFECTS.md delete mode 100644 apps/cli/src/commands/postgres-config/delete/SIDE_EFFECTS.md delete mode 100644 apps/cli/src/commands/postgres-config/get/SIDE_EFFECTS.md delete mode 100644 apps/cli/src/commands/postgres-config/update/SIDE_EFFECTS.md delete mode 100644 apps/cli/src/commands/projects/SIDE_EFFECTS.md delete mode 100644 apps/cli/src/commands/projects/api-keys/SIDE_EFFECTS.md delete mode 100644 apps/cli/src/commands/projects/create/SIDE_EFFECTS.md delete mode 100644 apps/cli/src/commands/projects/delete/SIDE_EFFECTS.md delete mode 100644 apps/cli/src/commands/projects/list/SIDE_EFFECTS.md delete mode 100644 apps/cli/src/commands/pull/SIDE_EFFECTS.md delete mode 100644 apps/cli/src/commands/secrets/list/SIDE_EFFECTS.md delete mode 100644 apps/cli/src/commands/secrets/set/SIDE_EFFECTS.md delete mode 100644 apps/cli/src/commands/secrets/unset/SIDE_EFFECTS.md delete mode 100644 apps/cli/src/commands/seed/buckets/SIDE_EFFECTS.md delete mode 100644 apps/cli/src/commands/services/SIDE_EFFECTS.md delete mode 100644 apps/cli/src/commands/snippets/download/SIDE_EFFECTS.md delete mode 100644 apps/cli/src/commands/snippets/list/SIDE_EFFECTS.md delete mode 100644 apps/cli/src/commands/ssl-enforcement/get/SIDE_EFFECTS.md delete mode 100644 apps/cli/src/commands/ssl-enforcement/update/SIDE_EFFECTS.md delete mode 100644 apps/cli/src/commands/sso/add/SIDE_EFFECTS.md delete mode 100644 apps/cli/src/commands/sso/info/SIDE_EFFECTS.md delete mode 100644 apps/cli/src/commands/sso/list/SIDE_EFFECTS.md delete mode 100644 apps/cli/src/commands/sso/remove/SIDE_EFFECTS.md delete mode 100644 apps/cli/src/commands/sso/show/SIDE_EFFECTS.md delete mode 100644 apps/cli/src/commands/sso/update/SIDE_EFFECTS.md delete mode 100644 apps/cli/src/commands/start/SIDE_EFFECTS.md delete mode 100644 apps/cli/src/commands/status/SIDE_EFFECTS.md delete mode 100644 apps/cli/src/commands/stop/SIDE_EFFECTS.md delete mode 100644 apps/cli/src/commands/storage/cp/SIDE_EFFECTS.md delete mode 100644 apps/cli/src/commands/storage/ls/SIDE_EFFECTS.md delete mode 100644 apps/cli/src/commands/storage/mv/SIDE_EFFECTS.md delete mode 100644 apps/cli/src/commands/storage/rm/SIDE_EFFECTS.md delete mode 100644 apps/cli/src/commands/telemetry/disable/SIDE_EFFECTS.md delete mode 100644 apps/cli/src/commands/telemetry/enable/SIDE_EFFECTS.md delete mode 100644 apps/cli/src/commands/telemetry/status/SIDE_EFFECTS.md delete mode 100644 apps/cli/src/commands/test/db/SIDE_EFFECTS.md delete mode 100644 apps/cli/src/commands/test/new/SIDE_EFFECTS.md delete mode 100644 apps/cli/src/commands/unlink/SIDE_EFFECTS.md delete mode 100644 apps/cli/src/commands/vanity-subdomains/activate/SIDE_EFFECTS.md delete mode 100644 apps/cli/src/commands/vanity-subdomains/check-availability/SIDE_EFFECTS.md delete mode 100644 apps/cli/src/commands/vanity-subdomains/delete/SIDE_EFFECTS.md delete mode 100644 apps/cli/src/commands/vanity-subdomains/get/SIDE_EFFECTS.md delete mode 100644 apps/cli/src/commands/whoami/SIDE_EFFECTS.md diff --git a/.github/ai-review/adjudicate-prompt.md b/.github/ai-review/adjudicate-prompt.md index cef6536f5f..0e939964fa 100644 --- a/.github/ai-review/adjudicate-prompt.md +++ b/.github/ai-review/adjudicate-prompt.md @@ -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. diff --git a/.github/ai-review/claude-review-prompt.md b/.github/ai-review/claude-review-prompt.md index b9630e6c41..d679db5b56 100644 --- a/.github/ai-review/claude-review-prompt.md +++ b/.github/ai-review/claude-review-prompt.md @@ -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 diff --git a/AGENTS.md b/AGENTS.md index 192a8e1361..252a76ec65 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -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 diff --git a/apps/cli/AGENTS.md b/apps/cli/AGENTS.md index 2cd808501f..c6b5879aaa 100644 --- a/apps/cli/AGENTS.md +++ b/apps/cli/AGENTS.md @@ -22,7 +22,6 @@ src/commands// .command.ts # command definition, flags, layer provision .handler.ts # command implementation .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 @@ -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/…`, `/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 @@ -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. @@ -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 @@ -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 diff --git a/apps/cli/docs/command-target.md b/apps/cli/docs/command-target.md index 5a6cd540b2..42e5db5ada 100644 --- a/apps/cli/docs/command-target.md +++ b/apps/cli/docs/command-target.md @@ -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: , consent default `, or `Target: , 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 | | ------------ | ------------------------------- | ------------------ | ---------------------------------------------------------------------------- | @@ -91,8 +91,6 @@ A selector conflict lists only the selector flags the command has: `Only one of - `--remote=`: `--password can't be used with --remote=. 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: diff --git a/apps/cli/docs/compute-commands.md b/apps/cli/docs/compute-commands.md index d755a93c1a..669dbc8bae 100644 --- a/apps/cli/docs/compute-commands.md +++ b/apps/cli/docs/compute-commands.md @@ -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.] 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 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. diff --git a/apps/cli/docs/stack-commands.md b/apps/cli/docs/stack-commands.md index 61da3e4eea..c627c9e481 100644 --- a/apps/cli/docs/stack-commands.md +++ b/apps/cli/docs/stack-commands.md @@ -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. @@ -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//uploads`, command scratch output (pgdelta debug bundles, Functions @@ -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: ()`, except for a shadow database of a remote with a +`[remotes.]` block, which takes the bundled version of each stale service and fails only when +one of them has none. ## Port intents @@ -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). diff --git a/apps/cli/src/SIDE_EFFECTS_TEMPLATE.md b/apps/cli/src/SIDE_EFFECTS_TEMPLATE.md deleted file mode 100644 index 11b03f843e..0000000000 --- a/apps/cli/src/SIDE_EFFECTS_TEMPLATE.md +++ /dev/null @@ -1,125 +0,0 @@ -# Side-effect Documentation Template - -> **What is this file?** -> Every command must include a `SIDE_EFFECTS.md` in its command directory. -> It documents all observable behavior of the command: files touched, API calls made, -> environment variables consumed, and exit codes. This is the source of truth for -> the command's side effects, and the primary input to the E2E compatibility test -> suite. -> -> **How to use this template:** -> Copy this file to `src/commands//SIDE_EFFECTS.md` (or -> `src/commands///SIDE_EFFECTS.md` for subcommands). -> Fill in every section. Use `—` for "none" rather than leaving a section empty. -> See `src/commands/orgs/list/SIDE_EFFECTS.md` for a complete example. - ---- - -# `supabase [subcommand]` - - - -## Files Read - - - -| Path | Format | When | -| --------------------------------- | ------------------------- | ---------------------------------------------------------- | -| `~/.supabase/access-token` | plain text (token string) | when `SUPABASE_ACCESS_TOKEN` unset and keyring unavailable | -| `/.supabase/config.json` | JSON | always, to resolve linked project ref | - -## Files Written - - - -| Path | Format | When | -| ---- | ------ | ---- | -| — | — | — | - -## API Routes - - - -| Method | Path | Auth | Request body | Response (used fields) | -| ------ | ------------------- | ------------ | ------------ | ---------------------- | -| `GET` | `/v1/some-resource` | Bearer token | none | `[{id, name}]` | - -## Environment Variables - - - -| Variable | Purpose | Required? | -| -------------------------- | ------------------------------------------------------------------------------------------ | ------------------------------------------------------- | -| `SUPABASE_ACCESS_TOKEN` | auth token (bypasses credential file/keyring lookup) | no (falls back to keyring → `~/.supabase/access-token`) | -| `SUPABASE_PROFILE` | built-in profile name or YAML file path | no (falls back to `~/.supabase/profile` -> `supabase`) | -| `SUPABASE_API_MAX_RETRIES` | Management API client retries after the first attempt (`0` = send once), not command loops | no (falls back to 5) | - -## Exit Codes - - - -| Code | Condition | -| ---- | ------------------------------------- | -| `0` | success | -| `1` | API error (non-2xx response) | -| `1` | authentication error (no token found) | -| `1` | network / connection failure | - -## Telemetry Events Fired - - - -| Event | When | Notable properties / groups | -| ---------------------- | ------------------------------------------ | ----------------------------------- | -| `cli_command_executed` | post-run, success or failure (via wrapper) | `exit_code`, `duration_ms`, `flags` | - -## Output - - - -### `--output-format text` - - - -``` - ID NAME - xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx My Org -``` - -### `--output-format json` - - - -```json -[{ "id": "…", "name": "…" }] -``` - -### `--output-format stream-json` - - - -```ndjson -{"type":"result","data":[{"id":"…","name":"…"}]} -``` - -## Notes - - diff --git a/apps/cli/src/command-internal/db-connection.errors.ts b/apps/cli/src/command-internal/db-connection.errors.ts index ca9b241fff..6f42367df6 100644 --- a/apps/cli/src/command-internal/db-connection.errors.ts +++ b/apps/cli/src/command-internal/db-connection.errors.ts @@ -74,8 +74,8 @@ export class DbExecError extends Data.TaggedError("DbExecError")<{ /** * A server-side `COPY (...) TO STDOUT` stream failed. The report handler maps a later * file-write failure to its own separate error, since bytes are collected before the output - * file is opened. See `inspect/report/SIDE_EFFECTS.md`, "Divergence on the query that was in - * flight when `COPY` failed", for the on-disk consequences. + * file is opened: a failed query writes no file, and a same-day re-run leaves the previous + * run's CSV for that query in place. */ export class DbCopyError extends Data.TaggedError("DbCopyError")<{ readonly message: string; diff --git a/apps/cli/src/commands/backups/list/SIDE_EFFECTS.md b/apps/cli/src/commands/backups/list/SIDE_EFFECTS.md deleted file mode 100644 index 84c1630ae8..0000000000 --- a/apps/cli/src/commands/backups/list/SIDE_EFFECTS.md +++ /dev/null @@ -1,99 +0,0 @@ -# `supabase backups list` - -Target: hosted, no consent — see [Command target](../../../../docs/command-target.md) - -## Files Read - -| Path | Format | When | -| ----------------------------------------- | ------------------------- | --------------------------------------------------------------------------------------------- | -| `/proc/sys/kernel/osrelease` (Linux) | plain text | once on layer init — disables keyring on WSL (`WSL` / `Microsoft` substring match) | -| keyring `"Supabase CLI"` / `` | OS keychain | when `SUPABASE_ACCESS_TOKEN` unset and keyring available; account = `CommandSettings.profile` | -| keyring `"Supabase CLI"` / `access-token` | OS keychain | legacy-key fallback when the profile-keyed lookup misses | -| `~/.supabase/access-token` | plain text (token string) | last-resort fallback after env + keyring miss | -| `/supabase/.temp/project-ref` | plain text | when neither `--remote=` nor `SUPABASE_PROJECT_ID` is set | - -## Files Written - -| Path | Format | When | -| ---------------------------------------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `/supabase/.temp/linked-project.json` | JSON | after the command runs (in `Effect.ensuring`), unless the file already exists, `.temp/project-ref` names a different project, no access token resolves, or the project lookup is not 200 | -| `~/.supabase/telemetry.json` | JSON | always (in `Effect.ensuring`) at end of command | - -## API Routes - -| Method | Path | Auth | Request body | Response (used fields) | -| ------ | ------------------------------------- | ------------ | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `GET` | `/v1/projects/{ref}/database/backups` | Bearer token | none | `{region, walg_enabled, pitr_enabled, backups: [{inserted_at, status, is_physical_backup}], physical_backup_data: {earliest_physical_backup_date_unix?, latest_physical_backup_date_unix?}}` | -| `GET` | `/v1/projects` | Bearer token | none | `[{id, ref, name, organization_slug, region, ...}]` — TTY-prompt fallback only | -| `GET` | `/v1/projects/{ref}` | Bearer token | none | `{ref, name, organization_id, organization_slug}` — linked-project cache miss only (best-effort, after the command) | -| `GET` | `/v1/projects/{parent}/branches` | Bearer token | none | `[{id, name, project_ref, is_default}]` — only for `--remote=` (or the deprecated `--project-ref=`), and for a bare `--remote` followed by a word that could name a branch; `{parent}` is `SUPABASE_PROJECT_ID`, else the linked project | -| `GET` | `/v1/branches/{id}` | Bearer token | none | `{ref, status, …}` — only for `--remote=` when no project is linked | - -## Environment Variables - -| Variable | Purpose | Required? | -| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- | -| `SUPABASE_ACCESS_TOKEN` | auth token (bypasses credential file/keyring lookup) | no (falls back to keyring → `~/.supabase/access-token`) | -| `SUPABASE_PROFILE` | selects API base URL: `supabase` → `api.supabase.com`, `supabase-staging` → `api.supabase.green`, `supabase-local` → `http://localhost:8080`. May alternatively be a filesystem path to a YAML profile with at least `api_url:` and optional `name:` (used by the cli-e2e test harness). | no (defaults to `supabase`) | -| `SUPABASE_PROJECT_ID` | project ref fallback when `--remote=` is not given | no (also reads `/supabase/.temp/project-ref` then prompts on TTY) | -| `SUPABASE_WORKDIR` | base directory for the `.temp/project-ref` lookup | no (walks up from CWD looking for `supabase/config.toml` or `supabase/config.json`) | - -## Exit Codes - -| Code | Condition | -| ---- | ------------------------------------------------------------------------------------- | -| `0` | success — backup list printed to stdout | -| `1` | `AccessTokenRequiredError` — no token in env/keyring/file | -| `1` | `InvalidAccessTokenError` — token violates `^sbp_(oauth_\|v0_)?[a-f0-9]{40}$` | -| `1` | `ProjectRefNotLinkedError` — no `--remote=`, env/file empty, and stdin not a TTY | -| `1` | `InvalidProjectRefError` — resolved ref violates `^[a-z]{20}$` | -| `1` | `BackupListUnexpectedStatusError` — non-2xx response from the backups endpoint | -| `1` | `BackupListNetworkError` — transport-level network failure | - -## Telemetry Events Fired - -| Event | When | Notable properties / groups | -| ---------------------- | ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `cli_command_executed` | post-run, success or failure (via wrapper) | `exit_code`, `duration_ms`, `flags` (`--remote=` → the ref, a bare `--remote` → `true`, any other `--remote` value → ``; `--project-ref` → the ref when ref-shaped, else ``) | - -## Output - -The `--output {pretty,json,yaml,toml,env}` flag and the `--output-format {text,json,stream-json}` flag are both honored. `--output` wins when both are supplied. `pretty` and `text` map to the same render path. - -### `--output pretty` (default) / `--output-format text` - -For PITR-only projects, prints a styled markdown table with columns: `REGION`, `WALG`, `PITR`, `EARLIEST TIMESTAMP`, `LATEST TIMESTAMP`. For projects with logical/physical backups, prints columns: `REGION`, `BACKUP TYPE`, `STATUS`, `CREATED AT (UTC)`. - -### `--output json` - -Indented JSON (`json.MarshalIndent(resp, "", " ")` equivalent) of the full backup response, terminated by a newline. - -### `--output yaml` - -YAML document (CLI-1975): keys are lowercased field names (`walgenabled`, -`physicalbackupdata`), nil values render as explicit `null`, and nested -mappings use 4-column indentation. - -### `--output toml` - -TOML document (CLI-1975): keys are PascalCase field names (`WalgEnabled`, -`[PhysicalBackupData]`), absent fields are omitted, and sub-tables follow -the primitive keys with 2-space indentation. An empty `backups` array is -omitted entirely. - -### `--output env` - -`KEY=VALUE` lines (one per leaf), one per line, sorted lexicographically. Keys are flattened with `.` separators then converted to SCREAMING_SNAKE_CASE; values are double-quoted with `"` and `\\` escaped. - -### `--output-format json` - -Single JSON object emitted via `Output.success` with the full backup response as the `data` field. - -### `--output-format stream-json` - -One `result` NDJSON event on success containing the backup response object. - -## Notes - -- The interactive picker calls `GET /v1/projects` and writes `"Selected project: "` to stderr in text mode. It does **not** persist the choice; only `supabase link` and `supabase bootstrap` write the temp file. -- Sends `User-Agent: SupabaseCLI/` and Bearer auth. No `X-Supabase-Command` headers. diff --git a/apps/cli/src/commands/backups/restore/SIDE_EFFECTS.md b/apps/cli/src/commands/backups/restore/SIDE_EFFECTS.md deleted file mode 100644 index b0a3ef4867..0000000000 --- a/apps/cli/src/commands/backups/restore/SIDE_EFFECTS.md +++ /dev/null @@ -1,91 +0,0 @@ -# `supabase backups restore` - -Target: hosted, consent default No — see [Command target](../../../../docs/command-target.md) - -## Files Read - -| Path | Format | When | -| ----------------------------------------- | ------------------------- | --------------------------------------------------------------------------------------------- | -| `/proc/sys/kernel/osrelease` (Linux) | plain text | once on layer init — disables keyring on WSL (`WSL` / `Microsoft` substring match) | -| keyring `"Supabase CLI"` / `` | OS keychain | when `SUPABASE_ACCESS_TOKEN` unset and keyring available; account = `CommandSettings.profile` | -| keyring `"Supabase CLI"` / `access-token` | OS keychain | legacy-key fallback when the profile-keyed lookup misses | -| `~/.supabase/access-token` | plain text (token string) | last-resort fallback after env + keyring miss | -| `/supabase/.temp/project-ref` | plain text | when neither `--remote=` nor `SUPABASE_PROJECT_ID` is set | - -## Files Written - -| Path | Format | When | -| ---------------------------------------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `/supabase/.temp/linked-project.json` | JSON | after the command runs (in `Effect.ensuring`), unless the file already exists, `.temp/project-ref` names a different project, no access token resolves, or the project lookup is not 200 | -| `~/.supabase/telemetry.json` | JSON | always (in `Effect.ensuring`) at end of command | - -## API Routes - -| Method | Path | Auth | Request body | Response (used fields) | -| ------ | -------------------------------------------------- | ------------ | ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `POST` | `/v1/projects/{ref}/database/backups/restore-pitr` | Bearer token | `{recovery_time_target_unix: int64}` | none (201 Created) | -| `GET` | `/v1/projects` | Bearer token | none | `[{id, ref, name, organization_slug, region, ...}]` — TTY-prompt fallback only | -| `GET` | `/v1/projects/{ref}` | Bearer token | none | `{ref, name, organization_id, organization_slug}` — linked-project cache miss only (best-effort, after the command) | -| `GET` | `/v1/projects/{parent}/branches` | Bearer token | none | `[{id, name, project_ref, is_default}]` — only for `--remote=` (or the deprecated `--project-ref=`), and for a bare `--remote` followed by a word that could name a branch; `{parent}` is `SUPABASE_PROJECT_ID`, else the linked project | -| `GET` | `/v1/branches/{id}` | Bearer token | none | `{ref, status, …}` — only for `--remote=` when no project is linked | - -## Environment Variables - -| Variable | Purpose | Required? | -| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- | -| `SUPABASE_ACCESS_TOKEN` | auth token (bypasses credential file/keyring lookup) | no (falls back to keyring → `~/.supabase/access-token`) | -| `SUPABASE_PROFILE` | selects API base URL: `supabase` → `api.supabase.com`, `supabase-staging` → `api.supabase.green`, `supabase-local` → `http://localhost:8080`. May alternatively be a filesystem path to a YAML profile with at least `api_url:` and optional `name:` (used by the cli-e2e test harness). | no (defaults to `supabase`) | -| `SUPABASE_PROJECT_ID` | project ref fallback when `--remote=` is not given | no (also reads `/supabase/.temp/project-ref` then prompts on TTY) | -| `SUPABASE_WORKDIR` | base directory for the `.temp/project-ref` lookup | no (walks up from CWD looking for `supabase/config.toml` or `supabase/config.json`) | -| `SUPABASE_YES` | approves the hosted-mutation confirmation like `--yes` (shell environment only; `supabase/.env` is ignored) | no | - -## Exit Codes - -| Code | Condition | -| ---- | ---------------------------------------------------------------------------------------------------------------------- | -| `0` | success — restore initiated | -| `1` | `AccessTokenRequiredError` — no token in env/keyring/file | -| `1` | `InvalidAccessTokenError` — token violates `^sbp_(oauth_\|v0_)?[a-f0-9]{40}$` | -| `1` | `ProjectRefNotLinkedError` — no `--remote=`, env/file empty, and stdin not a TTY | -| `1` | `InvalidProjectRefError` — resolved ref violates `^[a-z]{20}$` | -| `1` | `BackupRestoreUnexpectedStatusError` — non-201 response from the restore endpoint | -| `1` | `BackupRestoreNetworkError` — transport-level network failure | -| `1` | `HostedMutationConsentRequiredError` — no `--yes` / shell `SUPABASE_YES` and the run cannot prompt; nothing is changed | -| `1` | `HostedMutationDeclinedError` — the confirmation prompt was declined | - -## Telemetry Events Fired - -| Event | When | Notable properties / groups | -| ---------------------- | ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `cli_command_executed` | post-run, success or failure (via wrapper) | `exit_code`, `duration_ms`, `flags` (`--remote=` → the ref, a bare `--remote` → `true`, any other `--remote` value → ``; `--project-ref` → the ref when ref-shaped, else ``; `--timestamp` → ``) | - -## Output - -This command ignores `--output` entirely and always writes the success line to -**stderr**, for every `--output` value. The `--output-format` JSON modes get a -structured payload. - -### `--output pretty|yaml|toml|env` / `--output-format text` - -Writes `"Started PITR restore: \n"` to **stderr**. - -### `--output json` - -Indented JSON object on stdout: `{ "message": "Started PITR restore", "project_ref": "" }`. - -### `--output-format json` - -Single JSON success event via `Output.success("Started PITR restore", { project_ref })`. - -### `--output-format stream-json` - -One `result` NDJSON event on success with the project ref payload. - -## Notes - -- `--timestamp` / `-t` accepts seconds since Unix epoch (int64). Defaults to `0`, which the API interprets as "now". -- Known gap: the generated `V1RestorePitrBackupInput` schema enforces `recovery_time_target_unix >= 0`, so a negative value is rejected locally with a schema decode error instead of being forwarded to the API (the underlying field has no lower bound). Resolving this requires an upstream OpenAPI spec change. -- The interactive picker calls `GET /v1/projects` and writes `"Selected project: "` to stderr in text mode. It does **not** persist the choice; only `supabase link` and `supabase bootstrap` write the temp file. -- Sends `User-Agent: SupabaseCLI/` and Bearer auth. No `X-Supabase-Command` headers. - -- **Consent.** Asks once, after the project is resolved and before the POST, with default No: `Restore the database to Unix timestamp (PITR)`. With no `--timestamp` the action reads `Start a PITR restore without a recovery time target`. diff --git a/apps/cli/src/commands/bootstrap/SIDE_EFFECTS.md b/apps/cli/src/commands/bootstrap/SIDE_EFFECTS.md deleted file mode 100644 index e83e23a1c6..0000000000 --- a/apps/cli/src/commands/bootstrap/SIDE_EFFECTS.md +++ /dev/null @@ -1,202 +0,0 @@ -# `supabase bootstrap [template]` - -Target: account, consent default Yes — see [Command target](../../../docs/command-target.md) - -`bootstrap` is a meta-orchestrator: it chains a workdir prompt → hosted-mutation consent → -template fetch/download → blank `init` → ensure-login → `projects create` → `projects api-keys` → `link` services → -health poll → write `.env` → `db push` → start suggestion. Every step is native TypeScript, -including the migration push (`dbPushCore`, shared with the standalone `supabase db push` -command — see Notes). - -## Files Read - -| Path | Format | When | -| ------------------------------------------------------------------ | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `~/.supabase/access-token` | plain text | ensure-login token miss (env unset and keyring unavailable) | -| `/.env.example` | dotenv | optional; merged into the generated `.env` | -| `/supabase/{.env..local,.env.local,.env.,.env}` | dotenv | step I (`loadProjectEnvValues`), before config.toml validation and again inside `checkDbConfig`; `` is `SUPABASE_ENV` (default `development`), `.env.local` is skipped when `SUPABASE_ENV=test`; first of the 4 files (in this order) to set a key wins, and this `supabase/` directory tier beats the workdir-root tier below — feeds config.toml `env(VAR)` expansion and the push step's `SUPABASE_YES` auto-confirm default | -| `/{.env..local,.env.local,.env.,.env}` | dotenv | same read as above; lower-precedence fallback tier, only consulted for a key none of the `supabase/` directory's 4 files above already set | -| `/supabase/.temp/project-ref` | plain text | link-services step, to tell whether it names the new project | -| `/supabase/config.toml` | TOML | native push step (embedded defaults used when absent) | -| `/supabase/.temp/pooler-url` | plain text | native push step's connection resolution, only when the direct `db..:5432` host is unreachable (IPv4-only network) — `resolveLinkedConn` falls back through the saved pooler URL `link.LinkServices` wrote in the earlier link-services step | -| `/supabase/migrations/` | directory | native push step, when `[db.migrations].enabled` (default true) | -| `/supabase/migrations/*.sql` | SQL | native push step, for each pending migration applied | -| seed files from `[db.seed].sql_paths` | SQL | native push step (`--include-seed` is always set; gated on `[db.seed].enabled`) | -| `/supabase/roles.sql` | SQL | native push step (`--include-roles` is always set; existence check + apply) | -| `PGSSL*` PEM, `pg_service.conf` | PEM, libpq | native push step, remote project, when set; see `db push` | - -## Files Written - -| Path | Format | When | -| ----------------------------------------------------------------------------------------------------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `/supabase/config.toml` | TOML | blank/`scratch` path only (via `initProject` with `force`, which also removes `supabase/config.json`/`config.jsonc`) | -| `/