Skip to content

feat(cli): nudge legacy start and init users toward the new local stack - #7649

Open
avallete wants to merge 5 commits into
developfrom
avallete/supabase-start-nudge-8c6d59
Open

avallete wants to merge 5 commits into
developfrom
avallete/supabase-start-nudge-8c6d59

Conversation

@avallete

@avallete avallete commented Nov 16, 2026 •

Copy link
Copy Markdown
Member

Summary

TL;DR: supabase start on the legacy backend and supabase init without the stack opt-in now point users to the experimental local stack (faster, lighter, one project per worktree). Coding agents get one extra line asking them to offer the switch to their user rather than act on it. This drives adoption and feedback for the new stack without changing any command result.

Before: nothing tells legacy users that the new stack exists.

After:

flowchart LR
  A["legacy start healthy<br/>or init done"] --> B{"TTY or<br/>coding agent?"}
  B -- no --> E[no nudge]
  B -- yes --> C{"start: shown<br/>in last 7 days?"}
  C -- yes --> E
  C -- no --> D["output.info nudge<br/>+ agent ask line if agent"]
Loading

What changed

  • New command-internal/stack-nudge.ts holds the messages, the audience check and the throttle.
  • start (fresh start only, never on the already-running path) emits:
    Try the new local stack: faster, lighter, and one project per worktree in parallel.
    To switch: remove the fixed ports from supabase/config.toml, then add `stack = true` under `[experimental]`.
    Steps and limitations: https://supabase.com/docs/guides/local-development/running-multiple-local-projects
    
    It shows at most once per 7 days, tracked best-effort in $SUPABASE_HOME/stack-nudge.json. Read and write failures never fail start.
  • init without the opt-in suggests SUPABASE_EXPERIMENTAL_STACK=1 supabase init. With the opt-in, it confirms the stack is enabled and links to the CLI issues page for feedback.
  • When the CLI detects a coding agent (--agent yes or an auto-detected AI tool), it adds one line: "Coding agents: offer this switch to the user and ask before changing …". Without it, agents in real-CLI runs only mentioned the stack; with it, they offered the switch and asked before editing config.
  • The nudge goes through output.info, not raw stderr. Agents run the CLI in JSON mode by default, so a text-only nudge would never reach them. The start JSON payload is unchanged; text and json render the line on stderr, and stream-json emits a log event.
  • Interactive-terminal detection uses stdout's TTY state, matching Output.interactive. Non-TTY, non-agent runs (CI, pipes) see nothing.
  • apps/cli/docs/supabase-home.md documents the stack-nudge.json state file.

Agent-driven runs

We drove fresh coding agents through the flow with a neutral task ("spin up my local Supabase and give me the .env values"), never mentioning the new stack, to see whether the nudge reaches them and what they do with it.

Setup Nudge version Agent reply
Stub CLI replaying start text Benefits + link Mentioned the new stack in passing
Real CLI (Docker) Text-only gate No nudge at all: the CLI switches agents to JSON output, so the text-only gate hid it. This led to the output.info channel
Real CLI Benefits + link via output.info Mentioned it in one line
Real CLI + exact switch steps Repeated the steps; did not offer (also with no "don't edit" restriction)
Real CLI + agent-only ask line Offered: "Want me to switch it?", and left config.toml untouched

Each row is a single run, so this shows direction rather than a rate. The init agent line has not had a real agent run.

Reviewer notes

  • Plain-text guidance addressed to agents is new for this CLI. The closest precedent is the login Claude Code hint tag.
  • No new telemetry event.

Linked issue

Supabase maintainer change; no linked issue.

🤖 Generated with Claude Code

`supabase start` on the legacy backend and `supabase init` without the
stack opt-in now emit an info log pointing to the experimental local
stack and its docs. Coding agents get an extra line asking them to offer
the switch to the user before changing config. The start nudge shows at
most once every 7 days, tracked in $SUPABASE_HOME/stack-nudge.json.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@avallete
avallete requested a review from a team as a code owner November 16, 2026 18:11
@avallete
avallete requested a review from kanadgupta November 16, 2026 18:11
@avallete

Copy link
Copy Markdown
Member Author

/ai-review

@github-actions

Copy link
Copy Markdown
Contributor

CLI benchmark (Lightweight Commands): no changes found

Commit e8d3fcd against develop at 4e2b1ed · 10 runs each · report only, never blocks merging

Command Workload Before After Change
supabase --version version 171 ms 177 ms no real change
supabase --help help 185 ms 186 ms no real change
supabase init init 207 ms 203 ms no real change
supabase migration new bench migration-new 180 ms 187 ms no real change
supabase config convert config-convert 206 ms 205 ms no real change
supabase config validate config-validate 217 ms 214 ms no real change
supabase gen types --lang typescript --project-id replayfixtureprojref gen-types 241 ms 238 ms no real change
supabase projects list projects-list 187 ms 185 ms no real change
supabase functions list --project-ref replayfixtureprojref functions-list 228 ms 214 ms no real change (-6%, within normal variation)

API calls: unchanged for all 9 commands.

Binary size: 135.1 MB, up 4.0 KB from 135.1 MB.

Details: timing ranges, API calls per command, slowest phases

Timing ranges

Command Workload Before range After range Change Verdict
supabase --version version 165-191 ms 165-217 ms +5 ms (+3%) within noise
supabase --help help 162-201 ms 164-212 ms +1 ms (+1%) within noise
supabase init init 185-239 ms 179-248 ms -3 ms (-2%) within noise
supabase migration new bench migration-new 172-205 ms 182-194 ms +8 ms (+4%) within noise
supabase config convert config-convert 181-277 ms 175-257 ms -1 ms (0%) within noise
supabase config validate config-validate 188-240 ms 190-260 ms -3 ms (-1%) within noise
supabase gen types --lang typescript --project-id replayfixtureprojref gen-types 205-268 ms 209-284 ms -3 ms (-1%) within noise
supabase projects list projects-list 170-198 ms 172-201 ms -2 ms (-1%) within noise
supabase functions list --project-ref replayfixtureprojref functions-list 177-257 ms 190-232 ms -14 ms (-6%) within noise

API calls per command

Command Workload Before After Endpoint changes
supabase --version version 0 0
supabase --help help 0 0
supabase init init 0 0
supabase migration new bench migration-new 0 0
supabase config convert config-convert 0 0
supabase config validate config-validate 0 0
supabase gen types --lang typescript --project-id replayfixtureprojref gen-types 2 2
supabase projects list projects-list 1 1
supabase functions list --project-ref replayfixtureprojref functions-list 2 2

Slowest phases

No command moved beyond noise, so there are no phase deltas.

Workflow run

Comment /bench to run the lightweight benchmark (this comment) again on the latest commit, or /bench full to also run the integration-heavy benchmark, which posts in its own comment.

@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 six findings against the checked-out code. All are confirmed: four behavior or documentation concerns and two test gaps. No findings overlap, and the supplied next-branch context shows no fundamental conflict.

Findings

Severity Location Category Sources Claim
🟡 MINOR apps/cli/src/command-internal/stack-nudge.ts:75 output-contract claude The nudge writes to stdout in text mode despite the new SIDE_EFFECTS documentation promising stderr. Agent detection enables this extra stdout output even when start or init is piped.
🟡 MINOR apps/cli/src/command-internal/stack-nudge.ts:75 output-contract claude In stream-json mode, start emits the nudge's log event after its result event, so consumers that stop processing at the result miss the agent-targeted note.
🟡 MINOR apps/cli/src/command-internal/stack-nudge.ts:16 usability codex The init nudge recommends SUPABASE_EXPERIMENTAL_STACK=1 supabase init immediately after initialization, but that command fails in the newly initialized project because its configuration already exists.
🟡 MINOR apps/cli/src/commands/start/start.integration.test.ts:1973 test-coverage codex The test named 'once per 7 days' verifies immediate suppression but never verifies the seven-day interval or expiration.
🟡 MINOR apps/cli/src/commands/start/start.integration.test.ts:2023 test-quality codex The JSON-mode test claims to verify stderr routing but observes only mock message records and success data, so it cannot detect incorrect output-stream routing.
⚪ NIT apps/cli/src/command-internal/stack-nudge.ts:71 error-handling claude A future lastShownAt timestamp suppresses the nudge until seven days after that future timestamp, potentially much longer than the intended weekly interval.

Stats

Claude findings: 3 · Codex findings: 3 · Confirmed: 6 · Refuted: 0 · Uncertain: 0


Models: claude-opus-5-5 + gpt-6.1-sol · Trigger: auto · Workflow run

This review runs once per PR. A maintainer can request another with a /ai-review comment.

@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 six findings and merged the duplicate post-init issue into one entry. Five findings are confirmed: broken init guidance, a log after the stream-json result, inaccurate documentation, missing throttle-expiry coverage, and an overstated test name. The last concern is downgraded to nit because shared JSON routing has separate coverage. Tests were not run.

Findings

Severity Location Category Sources Claim
🟡 MINOR apps/cli/src/command-internal/stack-nudge.ts:16 correctness claude+codex The post-init nudge recommends a command that fails in the project just initialized: SUPABASE_EXPERIMENTAL_STACK=1 supabase init rejects the config file that init just created.
🟡 MINOR apps/cli/src/commands/start/start.handler.ts:1669 output-contract claude For an eligible agent using stream-json, the nudge emits a log after the result event. Consumers treating the result as completion can miss the nudge or receive an unexpected trailing event.
🟡 MINOR apps/cli/src/commands/start/start.integration.test.ts:1973 test-coverage codex The seven-day throttle test checks immediate suppression but never exercises expiry, so permanent suppression or an incorrect positive interval would still pass.
⚪ NIT apps/cli/src/commands/start/SIDE_EFFECTS.md:414 documentation claude The start and init documentation incorrectly says interactive stdout enables the nudge in every output format. Humans using json or stream-json do not qualify solely because stdout is a TTY.
⚪ NIT apps/cli/src/commands/start/start.integration.test.ts:2023 test-quality codex The JSON-mode test claims to verify stderr routing, but only verifies recorded info messages and success data through a mock Output service.

Stats

Claude findings: 3 · Codex findings: 3 · Confirmed: 5 · 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.

- init nudge suggests `init --force`, since plain init fails on the
  config it just created
- text mode writes the nudge to stderr; json/stream-json keep
  output.info, and start emits it before the result event
- a future throttle timestamp counts as stale
- share agentDetected between hosted consent and the nudge
- drop unused exports (knip), tighten docs and tests

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@avallete

Copy link
Copy Markdown
Member 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

Both independent reviews completed. Code inspection confirms Claude's two low-priority UX findings; Codex reported none. No additional findings surfaced. Tests were not run.

Findings

Severity Location Category Sources Claim
⚪ NIT apps/cli/src/command-internal/stack-nudge.ts:14 ux claude The init nudge suggests a POSIX inline environment-variable assignment that cannot be copied directly into Windows cmd.exe or PowerShell.
⚪ NIT apps/cli/src/commands/start/start.handler.ts:1665 ux claude The stack promotion also appears after health-check failures accepted through --ignore-health-check, placing it after warnings even when the stack remains unhealthy.

Stats

Claude findings: 2 · Codex findings: 0 · Confirmed: 2 · 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.

avallete and others added 2 commits November 17, 2026 12:02
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…start-nudge-8c6d59

# Conflicts:
#	apps/cli/src/commands/init/SIDE_EFFECTS.md
#	apps/cli/src/commands/start/SIDE_EFFECTS.md
@avallete

Copy link
Copy Markdown
Member 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

CLI reference prose guidance: snapshot supabase/supabase@3b12d2e supplied to reviewers (advisory, not a style pass).

Four findings were confirmed. The highest-impact issue is that the init hint can lead users to overwrite another project's configuration after using --workdir. The start hint also ignores explicit stack opt-outs, concurrent starts can bypass the cooldown, and the JSON test leaves most of the result payload unchecked. The state-file documentation omission is verified, but the reported PR-description mismatch remains uncertain because the PR body was unavailable. The diff changes no CLI reference prose.

Findings

Severity Location Category Sources Claim
🟠 MAJOR apps/cli/src/command-internal/stack-nudge.ts:14 data-loss codex After a successful init with --workdir, following the hint from the same shell can overwrite another project's configuration. The suggested command omits --workdir even though the hint says it regenerates the config just created.
🟡 MINOR apps/cli/src/command-internal/stack-nudge.ts:34 correctness claude The start and init hints still appear after an explicit stack opt-out. With SUPABASE_EXPERIMENTAL_STACK=0, adding stack = true as instructed by the start hint cannot switch backends, even if the project already declares it.
🟡 MINOR apps/cli/src/command-internal/stack-nudge.ts:59 concurrency codex Concurrent starts that share a Supabase home can both show the hint within the seven-day cooldown.
🟡 MINOR apps/cli/src/commands/start/start.integration.test.ts:2008 test-coverage codex The agent JSON test would pass if the hint also appeared in the success payload or if status fields other than DB_URL disappeared.
🟡 MINOR apps/cli/src/command-internal/stack-nudge.ts:20 documentation claude The PR adds <SUPABASE_HOME>/stack-nudge.json, which is absent from the state-layout guide. Claude reports that the PR description says the guide documents the new file.

Stats

Claude findings: 2 · Codex findings: 3 · Confirmed: 4 · Refuted: 0 · Uncertain: 1


Models: claude-opus-5-5 + gpt-6.2-sol · Trigger: manual · Workflow run

This review runs once per PR. A maintainer can request another with a /ai-review comment.

Comment on lines +59 to +79
const lastShownAt = yield* fs.readFileString(statePath).pipe(
Effect.flatMap(Schema.decodeUnknownEffect(NudgeState)),
Effect.map((state) => state.lastShownAt),
Effect.orElseSucceed(() => undefined),
);
const throttled =
lastShownAt !== undefined &&
now - lastShownAt >= 0 &&
now - lastShownAt < NUDGE_INTERVAL_MILLIS;
yield* Effect.annotateCurrentSpan({ "stack_nudge.throttled": throttled });
if (throttled) return;

yield* emitNudge(
audience === "agent"
? `${START_STACK_NUDGE_MESSAGE}\n${START_AGENT_ASK_LINE}`
: START_STACK_NUDGE_MESSAGE,
);
yield* Effect.gen(function* () {
const encoded = yield* Schema.encodeEffect(NudgeState)({ lastShownAt: now });
yield* fs.makeDirectory(settings.supabaseHome, { recursive: true, mode: 0o700 });
yield* fs.writeFileString(statePath, encoded);

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.

🟡 MINOR · concurrency · source: codex

Concurrent starts that share a Supabase home can both show the hint within the seven-day cooldown.

Evidence: apps/cli/src/command-internal/stack-nudge.ts:55–56 builds a shared state path. Lines 59–69 read and check the timestamp, lines 71–75 emit the hint, and lines 76–80 write the timestamp. No interprocess synchronization covers those operations.

Suggested fix: Use a per-home lock to serialize the cooldown check, emission, and timestamp update. Keep lock and state failures from failing start.

Comment on lines +2008 to +2010
expect(out.messages.find((m) => m.type === "success")?.data).toMatchObject({
DB_URL: expect.any(String),
});

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.

🟡 MINOR · test-coverage · source: codex

The agent JSON test would pass if the hint also appeared in the success payload or if status fields other than DB_URL disappeared.

Evidence: apps/cli/src/commands/start/start.integration.test.ts:1995 names payload preservation as part of the test. Lines 2002–2007 check the info message separately, and lines 2008–2010 use a partial object match that requires only DB_URL.

Suggested fix: Assert the complete expected success payload for the fixture and keep the separate info-message assertion.

- init no longer suggests `init --force`; it points to the guide for
  switching this project and to the env var for the next init
- an explicit SUPABASE_EXPERIMENTAL_STACK=0 silences both nudges
- document stack-nudge.json in the SUPABASE_HOME guide

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

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.

1 participant