docs(cli): record intentional start --ignore-health-check divergence from Go (CLI-1987) by Coly010 · Pull Request #6007 · supabase/cli

Coly010 · 2026-07-30T13:45:40Z

⚖ Parity ruling applied (CLI-1987, Colum, 2026-07-30)

Option (b) chosen: keep the TypeScript behaviour and document the intentional divergence. Option (a) — matching Go's quirk — was rejected. No runtime behaviour changes in this PR.

Go's start.IsUnhealthyError (apps/cli-go/internal/db/start/start.go:227-231) classifies anyerrors.Join-shaped error as "unhealthy". That shape check accidentally also matches ensureImagesCached's errors.Join(result...) (apps/cli-go/internal/start/start.go:257-260), so in Go, with --ignore-health-check set, a total image-pull failure — or a Docker daemon that becomes unreachable during the pre-pull — is swallowed: Go prints the error, skips rollback, prints Started supabase local development setup. + the status table + the security notice, and exits 0 with zero containers running. Go's own comment on IsUnhealthyError ("Health check always returns a joinError") shows the wider match was never intended.

The TS port already behaves differently — legacyIsUnhealthyStartError matches only LegacyHealthCheckTimeoutError, and the image pre-pull runs before the downgrade envelope — so the same scenario exits 1 with no success banner and no status table. Per the ruling, that behaviour is kept and is now documented + regression-pinned. --ignore-health-check downgrades health-check timeouts only.

What changed

Docs, comments, and one regression test — the runtime is untouched:

apps/cli/src/legacy/commands/start/start.rollback.ts — divergence record in legacyIsUnhealthyStartError's doc comment, including an explicit "do not fix this by widening the match toward Go's shape check" guard, so a future parity sweep can't silently reintroduce Go's exit-0 swallow.
apps/cli/src/legacy/commands/start/SIDE_EFFECTS.md — the image-pull exit-code row now states the failure stays fatal even with --ignore-health-check, and a new "Notes" entry records the full carve-out (scenario, Go's quirk behaviour, TS behaviour, why rollback is not part of the divergence — nothing has been created yet in either CLI — and that the flag's Go-byte-matched help text "Ignore unhealthy services and exit 0" over-promises here).
apps/cli/docs/go-cli-porting-status.md — the legacy start entry carries the same intentional-divergence note (the table's column padding was re-flowed by oxfmt; the substantive change is the start row only).
apps/cli/src/legacy/commands/start/start.integration.test.ts — new test in the "image pull" block: pre-pull exhaustion under --ignore-health-check still fails with LegacyImagePrepullError, prints no Started banner, emits nothing on stdout (no status table), creates no container, and triggers no rollback. The daemon-unreachable trigger funnels through the same LegacyImagePrepullError path, so the one scenario pins both documented triggers.

Overlap with CLI-1967

CLI-1967's doc-drift sweep also touches start documentation. The CLI-1987 carve-out (SIDE_EFFECTS "Notes" entry, exit-code row, porting-status start row, start.rollback.ts comment) is fully handled here — CLI-1967 should not re-document this divergence.

Possible follow-up (not in scope here)

Self-review flagged a DX gap that would require a runtime change, so it is deliberately not part of this docs-only ruling PR: when --ignore-health-check is set and the pre-pull fails, the error output never explains why the flag didn't apply (and the flag's help text says "exit 0"). A TS-only error.suggestion ("--ignore-health-check only downgrades health-check timeouts; image pull failures are always fatal") on that path — analogous to the existing TS-only exec format error suggestion — would close it.

Fixes CLI-1987

…from Go (CLI-1987) Go's start.IsUnhealthyError classifies any errors.Join-shaped error as "unhealthy", so with --ignore-health-check a total image-pull failure or a Docker daemon that dies during the pre-pull is swallowed: Go prints the error, skips rollback, prints the "Started supabase local development setup." banner + status table + security notice, and exits 0 with no container running. Per the CLI-1987 ruling (2026-07-30, option b) that quirk is intentionally NOT reproduced: the TS port keeps the scenario fatal — exit 1, no success banner, no status table. Docs + comments + one regression test only; no runtime change: - start.rollback.ts: divergence record on legacyIsUnhealthyStartError so a future "fix" toward Go's shape check doesn't happen silently - start/SIDE_EFFECTS.md: exit-code carve-out + Notes entry - docs/go-cli-porting-status.md: start entry divergence note (table re-padded by oxfmt) - start.integration.test.ts: pins pre-pull failure under --ignore-health-check to exit 1 with no banner/status table/rollback Fixes CLI-1987

Coly010 · 2026-07-30T13:45:51Z

@codex review

chatgpt-codex-connector · 2026-07-30T13:48:22Z

Codex Review: Didn't find any major issues. 🚀

Reviewed commit:7466b7b844

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

…7-parity-ruling-start-ignore-health-check-on-image-pulldaemon

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit:5161af9fcc

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

github-actions · 2026-07-31T10:03:35Z

Supabase CLI preview

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

Preview package for commit d0b81a9.

…e delta record (review: codex) - start.rollback.ts + SIDE_EFFECTS.md: the pre-pull failure is fatal because it propagates from before bring-up without reaching either legacyIsUnhealthyStartError call site — not because of the matcher exclusion (widening it would be a no-op); the observable delta also includes the security notice Go prints unconditionally at Run()'s tail - start.integration.test.ts: model the daemon-unreachable trigger (immediate inspect failure) instead of duplicating the flagless pull-exhaustion scenario through ~36s of real retry backoff

Coly010 · 2026-07-31T10:32:05Z

@codex review

All three round findings addressed in 69bdc5f: divergence record re-attributed to control flow (matcher widening is a no-op — verified against the two call sites), delta record completed with the security notice (verified against start.go:84-87), and the new integration test re-modeled onto the immediate daemon-unreachable path (~25ms instead of ~36s of real retry backoff).

chatgpt-codex-connector · 2026-07-31T10:34:30Z

Codex Review: Didn't find any major issues. Keep them coming!

Reviewed commit:69bdc5fa34

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

kanadgupta

Tiny assertion enhancement suggestion from Claude below but non-blocking — LGTM!

…-quirk pin (CLI-1987)

…audit (CLI-1967) (supabase#6074) ## What Doc/comment-accuracy sweep from `apps/cli/docs/go-parity-audit-2026-07-24.md` §6 (untracked locally, not part of this repo). No runtime behavior changes — every item below was independently re-verified against current Go (`apps/cli-go/`) and TS source before fixing, since the audit is 12 days old and several items had drifted further in that time (in both directions). ## Fixed - **`docs/go-cli-porting-status.md`** — `functions list` legacy-shell status `wrapped` → `ported` (verified: zero `LegacyGoProxy` refs). `functions download` status corrected the other way, `ported` → `wrapped` (its handler still delegates wholesale via `LegacyGoProxy` for the default `--use-docker` path; only `--use-api` is native — noted as a hybrid in the row). Added a `ported` definition to the legacy-status legend (it only defined `wrapped`/`missing`, despite `ported` being ~90% of rows) and retitled that section from "Legacy Shell Wrapping Status" to "Legacy Shell Command Status" to match. Fixed the adjacent `functions delete/deploy/list/new/serve` legacy-shell notes, which all still said "Wrapped in legacy shell" despite being natively ported. - **`legacy-pgdelta.seam.service.ts`** — fixed two stale doc comments (`execInherit`, `ensureLocalDatabaseStarted`) that referenced things as "not yet ported" when they now are (`db reset`, `start`/`db start`). Did **not** touch `exportCatalog`'s doc comment / `LegacyCatalogMode`, which the audit also flagged — that exact hunk is already being rewritten more completely by the in-flight CLI-1959 PR (supabase#6061, open); fixing it here would guarantee a conflict with a strictly better version. `legacy-db-bootstrap.seam.service.ts` (the audit's other named file) was checked and found already accurate — CLI-1954/1955 (native `db start`/`db reset --local`) are still unmerged, so its "not yet ported" claim is currently true. - **`network-restrictions/{get,update}/SIDE_EFFECTS.md`** — the `-o {json,yaml,toml,env}` sections previously implied Go itself produces distinct byte-identical output per format. Verified against Go source: `restrictions/get`/`update` never read `OutputFormat` at all — they always print the same 3-line `fmt.Printf` template regardless of `-o`. Corrected both docs to state this plainly, documented that TS's format-specific output here is a deliberate TS-only enhancement with no real Go behavior to match (including no Go casing convention, since TS uses the map-shaped encoders rather than CLI-1975's struct-spec ones), and trimmed the resulting repetition. - **`inspect/report/SIDE_EFFECTS.md`** — added the empty/no-file divergence on `COPY` failure: Go's `copyToCSV` opens the output file with `O_TRUNC` before running the query, so a failing query still leaves a file (empty or partial); TS buffers in memory and only writes on success, leaving no file on a fresh run — and leaving the *previous* run's stale CSV in place on a same-day re-run (the more consequential case). Cross-referenced from `legacy-db-connection.errors.ts`'s `LegacyDbCopyError` doc comment, which already covered the message-text angle of the same divergence. - **`domains.cname.ts`** — the comment describing Go's CNAME "failed to locate" error dump wrongly implied Go embeds readable JSON. Verified against Go source and empirically (compiled the equivalent locally): Go JSON-marshals the answers to a `[]byte`, then formats that `[]byte` with `%+v`, which Go's `fmt` renders as an uncapped decimal byte-value array, not the JSON text — a `%+v`-on-`[]byte` footgun, not an intended format. Fixed both the function's JSDoc and the inline comment (they'd contradicted each other after an earlier pass), and cross-referenced the divergence from `domains/SIDE_EFFECTS.md`. - **`branches/orgs/projects/secrets` SIDE_EFFECTS `-o toml`/`-o yaml` claims**, **`functions deploy`'s `NPM_AUTH_TOKEN` env table entry**, and **`update-root-key.handler.ts`'s color comment** — all already fixed by CLI-1975 (supabase#6002), CLI-1985 (supabase#6005), and CLI-1990 (supabase#5978) respectively, which merged after the audit ran. Verified current state matches; no changes needed. - **`start/SIDE_EFFECTS.md`'s `--ignore-health-check` ruling** — already fully handled by CLI-1987 (supabase#6007, merged), whose own description explicitly says CLI-1967 should not re-document it. Left untouched. ## Left as noted, not fixed (out of scope for a docs-only pass) - The `network-restrictions get`/`update` TS-only `-o` support is a real, pre-existing behavioral divergence from Go (Go has no such behavior at all for these two commands) — documented accurately here, but whether it should be *removed* to enforce strict parity is a ruling this PR doesn't make. - `docs/go-cli-porting-status.md`'s "Functions" section (next/-shell table) has a larger, pre-existing inaccuracy discovered while fixing the adjacent legacy-shell notes: it claims there's "still no dedicated `functions` CLI surface" in `next/`, but `next/commands/functions/` already exists (list/delete/deploy/download/new/dev, registered in `next/cli/root.ts`). Added command-path links and flagged the section as needing its own flag-by-flag parity audit rather than silently reclassifying rows without one. Fixes CLI-1967

Merge remote-tracking branch 'origin/develop' into columferry/cli-198…
5161af9
…7-parity-ruling-start-ignore-health-check-on-image-pulldaemon

Coly010 marked this pull request as ready for review July 31, 2026 09:55

Coly010 requested a review from a team as a code owner July 31, 2026 09:55

chatgpt-codex-connectorBot reviewed Jul 31, 2026
View reviewed changes

Comment threadapps/cli/src/legacy/commands/start/start.rollback.ts Outdated
Comment threadapps/cli/src/legacy/commands/start/start.integration.test.ts Outdated
Comment threadapps/cli/src/legacy/commands/start/start.rollback.ts Outdated

Coly010 self-assigned this Jul 31, 2026

kanadgupta approved these changes Jul 31, 2026
View reviewed changes

Comment threadapps/cli/src/legacy/commands/start/start.integration.test.ts

test(cli): assert security notice absent from stderr in start swallow…
d0b81a9
…-quirk pin (CLI-1987)

Coly010 added this pull request to the merge queue Aug 3, 2026

Merged via the queue into develop with commit b4d52dcAug 3, 2026
21 checks passed

Coly010 deleted the columferry/cli-1987-parity-ruling-start-ignore-health-check-on-image-pulldaemon branch August 3, 2026 10:27

supabase-cli-releaserBot mentioned this pull request Aug 4, 2026
chore: production deploy #6056
Merged

Coly010 mentioned this pull request Aug 5, 2026
docs(cli): fix porting-status and SIDE_EFFECTS drift from 2026-07-24 audit (CLI-1967) #6074
Merged

Navigation Menu

Uh oh!

docs(cli): record intentional start --ignore-health-check divergence from Go (CLI-1987) - #6007

docs(cli): record intentional start --ignore-health-check divergence from Go (CLI-1987)#6007
Coly010 merged 4 commits into
developfrom
columferry/cli-1987-parity-ruling-start-ignore-health-check-on-image-pulldaemon

Coly010 commented Jul 30, 2026

Uh oh!

Coly010 commented Jul 30, 2026

Uh oh!

chatgpt-codex-connectorBot commented Jul 30, 2026

Uh oh!

chatgpt-codex-connectorBot left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

github-actionsBot commented Jul 31, 2026•
edited
Loading

Uh oh!

Coly010 commented Jul 31, 2026

Uh oh!

chatgpt-codex-connectorBot commented Jul 31, 2026

Uh oh!

kanadgupta left a comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

Coly010 commented Jul 30, 2026

⚖ Parity ruling applied (CLI-1987, Colum, 2026-07-30)

What changed

Overlap with CLI-1967

Possible follow-up (not in scope here)

Uh oh!

Coly010 commented Jul 30, 2026

Uh oh!

chatgpt-codex-connectorBot commented Jul 30, 2026

Uh oh!

chatgpt-codex-connectorBot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

Uh oh!

Uh oh!

github-actionsBot commented Jul 31, 2026• edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Supabase CLI preview

Uh oh!

Coly010 commented Jul 31, 2026

Uh oh!

chatgpt-codex-connectorBot commented Jul 31, 2026

Uh oh!

kanadgupta left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

github-actionsBot commented Jul 31, 2026•
edited
Loading