Repository navigation
feat(cli): nudge legacy start and init users toward the new local stack #7649
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
base: develop
Are you sure you want to change the base?
Changes from all commits
e8d3fcd
393367c
b32fdf0
2b7c8a0
32befc7
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,103 @@ | ||
| import { Clock, Effect, FileSystem, Path, Schema } from "effect"; | ||
|
|
||
| import { CommandSettings } from "../config/command-settings.service.ts"; | ||
| import { resolveExperimentalFeature } from "../shared/config/experimental-feature.ts"; | ||
| import { Output } from "../shared/output/output.service.ts"; | ||
| import { agentDetected } from "./agent-mode.ts"; | ||
|
|
||
| const DOCS_URL = | ||
| "https://supabase.com/docs/guides/local-development/running-multiple-local-projects"; | ||
|
|
||
| const START_STACK_NUDGE_MESSAGE = `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: ${DOCS_URL}`; | ||
|
|
||
| const INIT_STACK_NUDGE_MESSAGE = `Try the new faster, lighter, parallel local stack: set SUPABASE_EXPERIMENTAL_STACK=1 before your next \`supabase init\`. | ||
| To switch this project: ${DOCS_URL}`; | ||
|
|
||
| const INIT_STACK_ENABLED_MESSAGE = | ||
| "Experimental local stack enabled in supabase/config.toml. Share feedback: https://github.com/supabase/cli/issues"; | ||
|
|
||
| const NUDGE_STATE_FILE = "stack-nudge.json"; | ||
| const NUDGE_INTERVAL_MILLIS = 7 * 24 * 60 * 60 * 1000; | ||
|
|
||
| const NudgeState = Schema.fromJsonString(Schema.Struct({ lastShownAt: Schema.Finite })); | ||
|
|
||
| const START_AGENT_ASK_LINE = | ||
| "Coding agents: offer this switch to the user and ask before changing supabase/config.toml."; | ||
| const INIT_AGENT_ASK_LINE = | ||
| "Coding agents: offer this to the user and ask before changing supabase/config.toml."; | ||
|
|
||
| /** | ||
| * Who to nudge: a coding agent, a human at a terminal, or nobody. Text mode writes to stderr so | ||
| * piped stdout stays clean; json and stream-json use `output.info` so result payloads are unchanged. | ||
| */ | ||
| const nudgeAudience = Effect.gen(function* () { | ||
| const output = yield* Output; | ||
| // With the config side pinned to true, only an explicit shell `SUPABASE_EXPERIMENTAL_STACK=0` | ||
| // resolves to false; that user opted out, so the nudge stays quiet. | ||
| const optedOut = !(yield* resolveExperimentalFeature({ | ||
| feature: "stack", | ||
| configValue: Effect.succeed(true), | ||
| }).pipe(Effect.orElseSucceed(() => true))); | ||
| if (optedOut) return undefined; | ||
| if (yield* agentDetected) return "agent" as const; | ||
| return output.interactive ? ("human" as const) : undefined; | ||
| }); | ||
|
avallete marked this conversation as resolved.
Resolved
|
||
|
|
||
| const emitNudge = Effect.fnUntraced(function* (message: string) { | ||
| const output = yield* Output; | ||
| if (output.format === "text") return yield* output.raw(`${message}\n`, "stderr"); | ||
| return yield* output.info(message); | ||
| }); | ||
|
|
||
| /** | ||
| * Prints the stack nudge on stderr at most once every 7 days. The throttle state is best-effort: | ||
| * any read or write failure is swallowed so it can never fail `start`. | ||
| */ | ||
| export const maybeShowStartStackNudge = Effect.fn("StackNudge.maybeShowStart")(function* () { | ||
| const audience = yield* nudgeAudience; | ||
| if (audience === undefined) return; | ||
| const fs = yield* FileSystem.FileSystem; | ||
| const path = yield* Path.Path; | ||
| const settings = yield* CommandSettings; | ||
| const statePath = path.join(settings.supabaseHome, NUDGE_STATE_FILE); | ||
| const now = yield* Clock.currentTimeMillis; | ||
|
|
||
| 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); | ||
|
Comment on lines
+67
to
+87
Contributor
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. 🟡 MINOR · 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. |
||
| }).pipe(Effect.ignore); | ||
| }); | ||
|
|
||
| /** Prints the `init` nudge or confirmation on stderr to a human at a terminal or an agent. */ | ||
| export const showInitStackNote = Effect.fn("StackNudge.showInit")(function* ( | ||
| experimentalStack: boolean, | ||
| ) { | ||
| const audience = yield* nudgeAudience; | ||
| if (audience === undefined) return; | ||
| if (experimentalStack) return yield* emitNudge(INIT_STACK_ENABLED_MESSAGE); | ||
| yield* emitNudge( | ||
| audience === "agent" | ||
| ? `${INIT_STACK_NUDGE_MESSAGE}\n${INIT_AGENT_ASK_LINE}` | ||
| : INIT_STACK_NUDGE_MESSAGE, | ||
| ); | ||
| }); | ||
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -58,6 +58,7 @@ import { | |
| classifyCliErrorActionability, | ||
| } from "../../shared/telemetry/error-actionability.ts"; | ||
| import { | ||
| AgentFlag, | ||
| DebugFlag, | ||
| ExperimentalFlag, | ||
| NetworkIdFlag, | ||
|
|
@@ -643,6 +644,8 @@ interface SetupOpts { | |
| readonly networkId?: Option.Option<string>; | ||
| /** `--experimental`/`SUPABASE_EXPERIMENTAL`. Defaults to `false`. */ | ||
| readonly experimental?: boolean; | ||
| /** Stdout is a terminal. Defaults to `false`. */ | ||
| readonly interactive?: boolean; | ||
| /** Replaces the `DbConnection.connect` behind the Postgres readiness probe. Defaults to succeeding. */ | ||
| readonly dbConnect?: (typeof DbConnection)["Service"]["connect"]; | ||
| } | ||
|
|
@@ -655,7 +658,7 @@ const setup = Effect.fnUntraced(function* (opts: SetupOpts = {}) { | |
| opts.configContents ?? `project_id = "${opts.configuredProjectId ?? "demo"}"\n`, | ||
| ); | ||
| } | ||
| const out = mockOutput({ format: opts.format ?? "text" }); | ||
| const out = mockOutput({ format: opts.format ?? "text", interactive: opts.interactive }); | ||
| const telemetry = mockTelemetryStateTracked(); | ||
| const analytics = mockAnalytics(); | ||
| const cliSettings = mockCommandSettings({ workdir }); | ||
|
|
@@ -1960,6 +1963,55 @@ describe("start integration", () => { | |
| }).pipe(Effect.provide([BunServices.layer, BunCrypto.layer])), | ||
| ); | ||
|
|
||
| describe("stack nudge", () => { | ||
| const NUDGE = "Try the new local stack"; | ||
| const nudgeShown = Effect.fnUntraced(function* () { | ||
| const { layer, out } = yield* setup({ interactive: true }); | ||
| yield* start(flags()).pipe(Effect.provide(layer)); | ||
| return out.stderrText.includes(NUDGE); | ||
| }); | ||
|
|
||
| it.effect("shows the nudge on stderr again only after 7 days", () => | ||
| Effect.gen(function* () { | ||
| expect(yield* nudgeShown()).toBe(true); | ||
|
|
||
| yield* TestClock.adjust(7 * 24 * 60 * 60 * 1000 - 1); | ||
| expect(yield* nudgeShown()).toBe(false); | ||
|
|
||
| yield* TestClock.adjust("1 millis"); | ||
| expect(yield* nudgeShown()).toBe(true); | ||
| }).pipe(Effect.provide([BunServices.layer, BunCrypto.layer])), | ||
| ); | ||
|
|
||
| it.effect("stays silent when stdout is not a terminal", () => | ||
| Effect.gen(function* () { | ||
| const { layer, out } = yield* setup({ interactive: false }); | ||
| yield* start(flags()).pipe(Effect.provide(layer)); | ||
| expect(out.stderrText).not.toContain(NUDGE); | ||
| }).pipe(Effect.provide([BunServices.layer, BunCrypto.layer])), | ||
| ); | ||
|
|
||
| it.effect( | ||
| "emits the nudge to an agent in json mode without changing the result payload", | ||
| () => | ||
| Effect.gen(function* () { | ||
| const { layer, out } = yield* setup({ format: "json", interactive: false }); | ||
| yield* start(flags()).pipe( | ||
| Effect.provide(Layer.mergeAll(layer, Layer.succeed(AgentFlag, "yes" as const))), | ||
| ); | ||
| const info = out.messages | ||
| .filter((m) => m.type === "info") | ||
| .map((m) => m.message) | ||
| .join("\n"); | ||
| expect(info).toContain(NUDGE); | ||
| expect(info).toContain("Coding agents: offer this switch to the user"); | ||
| expect(out.messages.find((m) => m.type === "success")?.data).toMatchObject({ | ||
| DB_URL: expect.any(String), | ||
| }); | ||
|
Comment on lines
+2008
to
+2010
Contributor
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. 🟡 MINOR · 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. |
||
| }).pipe(Effect.provide([BunServices.layer, BunCrypto.layer])), | ||
| ); | ||
| }); | ||
|
|
||
| it.effect("emits a machine status payload in json mode instead of the pretty table", () => | ||
| Effect.gen(function* () { | ||
| const { layer, out } = yield* setup({ format: "json" }); | ||
|
|
||
Uh oh!
There was an error while loading. Please reload this page.