From 11d1902cc1ca23c0f9adef1dc9bcb356460d9699 Mon Sep 17 00:00:00 2001 From: Mike Donnalley Date: Wed, 18 Nov 2026 12:48:12 -0700 Subject: [PATCH 1/3] chore(cli): declare experimental access and deprecation on commands --- apps/cli/AGENTS.md | 2 +- apps/cli/src/cli/complete.ts | 5 +- .../command-access-policy.integration.test.ts | 123 ++++++++++++++++++ .../command-internal/command-access-policy.ts | 36 +++++ .../src/command-internal/experimental-gate.ts | 13 +- .../db/schema/declarative/declarative.gate.ts | 26 ++-- .../declarative/declarative.gate.unit.test.ts | 28 ++-- .../declarative/generate/generate.command.ts | 2 + .../declarative/generate/generate.handler.ts | 4 +- .../schema/declarative/sync/sync.command.ts | 2 + .../schema/declarative/sync/sync.handler.ts | 6 +- .../inspect/db/cache-hit/cache-hit.command.ts | 4 +- .../db/index-sizes/index-sizes.command.ts | 4 +- .../db/index-usage/index-usage.command.ts | 4 +- .../db/role-configs/role-configs.command.ts | 4 +- .../role-connections.command.ts | 4 +- .../inspect/db/seq-scans/seq-scans.command.ts | 4 +- .../table-record-counts.command.ts | 4 +- .../db/table-sizes/table-sizes.command.ts | 4 +- .../unused-indexes/unused-indexes.command.ts | 4 +- .../commands/network-bans/get/get.command.ts | 5 +- .../network-bans/remove/remove.command.ts | 5 +- .../network-restrictions/get/get.command.ts | 5 +- .../update/update.command.ts | 5 +- .../postgres-config/delete/delete.command.ts | 5 +- .../postgres-config/get/get.command.ts | 5 +- .../postgres-config/update/update.command.ts | 5 +- .../ssl-enforcement/get/get.command.ts | 5 +- .../ssl-enforcement/update/update.command.ts | 5 +- .../cli/src/commands/storage/cp/cp.command.ts | 5 +- .../cli/src/commands/storage/ls/ls.command.ts | 5 +- .../cli/src/commands/storage/mv/mv.command.ts | 5 +- .../cli/src/commands/storage/rm/rm.command.ts | 5 +- .../activate/activate.command.ts | 5 +- .../check-availability.command.ts | 5 +- .../delete/delete.command.ts | 5 +- .../vanity-subdomains/get/get.command.ts | 5 +- apps/cli/src/docs/docs-spec.tables.ts | 51 +------- apps/cli/src/docs/docs-spec.ts | 44 +------ apps/cli/src/docs/docs-spec.unit.test.ts | 95 +++++++------- apps/cli/src/shared/output/json-formatter.ts | 3 +- apps/cli/src/shared/output/subcommand-help.ts | 46 +++++++ apps/cli/src/shared/output/target-help.ts | 29 +---- apps/cli/src/shared/output/text-formatter.ts | 4 +- 44 files changed, 401 insertions(+), 239 deletions(-) create mode 100644 apps/cli/src/command-internal/command-access-policy.integration.test.ts create mode 100644 apps/cli/src/command-internal/command-access-policy.ts create mode 100644 apps/cli/src/shared/output/subcommand-help.ts diff --git a/apps/cli/AGENTS.md b/apps/cli/AGENTS.md index 9fb0e71065..6541a44464 100644 --- a/apps/cli/AGENTS.md +++ b/apps/cli/AGENTS.md @@ -99,7 +99,7 @@ rather than deleting it; `db remote commit` is the reference: `withJsonErrorHandling`. Provide only `commandRuntimeLayer` and `telemetryStateLayer`. - 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 drop it from `DOCS_EXCLUDED`. +- 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 diff --git a/apps/cli/src/cli/complete.ts b/apps/cli/src/cli/complete.ts index ff8ba4b3b2..6977729121 100644 --- a/apps/cli/src/cli/complete.ts +++ b/apps/cli/src/cli/complete.ts @@ -6,6 +6,7 @@ import { GlobalFlag } from "effect/cli"; import type { Command, Param, Primitive } from "effect/cli"; import type { PlatformError } from "effect/PlatformError"; import process from "node:process"; +import { deprecatedShortDescription } from "../command-internal/command-access-policy.ts"; import { outputFormatsForCommand } from "../command-internal/output-formats.ts"; import { unwrapParam } from "../command-internal/param-introspection.ts"; import { REMOTE_FLAG_NAME } from "../command-internal/target/remote-vocabulary.ts"; @@ -842,7 +843,7 @@ function helpArgumentCandidates( const visibleSubcommands = flattenSubcommands(resolved).filter((sub) => !sub.unlisted); const candidates: Array = visibleSubcommands.map((sub) => ({ name: sub.name, - description: sub.shortDescription ?? sub.description, + description: deprecatedShortDescription(sub) ?? sub.shortDescription ?? sub.description, })); // `help` is included when nothing after it resolved, since it's one of root's own subcommands. if (matchedPath.length === 0) { @@ -973,7 +974,7 @@ export function classifyCompletion(input: ClassifyCompletionInput): CompletionRe directive = CompletionDirective.NoFileComp; const subcommandCandidates: Array = visibleSubcommands.map((sub) => ({ name: sub.name, - description: sub.shortDescription ?? sub.description, + description: deprecatedShortDescription(sub) ?? sub.shortDescription ?? sub.description, })); // `help` isn't a real command node in this tree; synthesize it as a candidate, but // only at root, not recursively on descendants. diff --git a/apps/cli/src/command-internal/command-access-policy.integration.test.ts b/apps/cli/src/command-internal/command-access-policy.integration.test.ts new file mode 100644 index 0000000000..673eb80645 --- /dev/null +++ b/apps/cli/src/command-internal/command-access-policy.integration.test.ts @@ -0,0 +1,123 @@ +import { BunServices } from "@effect/platform-bun"; +import { describe, expect, it } from "@effect/vitest"; +import { Console, Effect, Layer, Schema } from "effect"; +import { CliOutput, Command, Flag } from "effect/cli"; + +import { fakeConsole } from "../../tests/helpers/mocks.ts"; +import { respondToComplete } from "../cli/complete.ts"; +import { jsonCliOutputFormatter } from "../shared/output/json-formatter.ts"; +import { docsCommandTree } from "../docs/docs-spec.ts"; +import { textCliOutputFormatter } from "../shared/output/text-formatter.ts"; +import { defineExperimentalAccess, withDeprecated } from "./command-access-policy.ts"; + +describe("command access policy", () => { + it.effect( + "retains check arguments, typed failure and success for optional experimental access", + () => + Effect.gen(function* () { + const access = defineExperimentalAccess({ + experimental: "optional", + check: (enabled: boolean) => + enabled ? Effect.succeed("allowed") : Effect.fail("disabled"), + }); + let executed = false; + const command = Command.make("preview", { enabled: Flag.Boolean("enabled") }).pipe( + Command.withHandler((flags) => + Effect.gen(function* () { + const result = yield* access.check(flags.enabled); + executed = result === "allowed"; + }), + ), + access.annotate, + ); + const layer = Layer.mergeAll(BunServices.layer, CliOutput.layer(textCliOutputFormatter())); + expect( + yield* Command.runWith(command, { version: "0" })(["--enabled=false"]).pipe( + Effect.flip, + Effect.provide(layer), + ), + ).toBe("disabled"); + expect(executed).toBe(false); + yield* Command.runWith(command, { version: "0" })(["--enabled"]).pipe( + Effect.provide(layer), + ); + expect(executed).toBe(true); + }), + ); + + it.effect("keeps a deprecated command runnable and visible in help but not the docs tree", () => + Effect.gen(function* () { + let executed = false; + const leaf = Command.make("old").pipe( + Command.withDescription("Use the replacement instead."), + withDeprecated, + Command.withShortDescription("Show old data"), + Command.withHandler(() => + Effect.sync(() => { + executed = true; + }), + ), + ); + const other = Command.make("other").pipe( + Command.withShortDescription("Other data"), + withDeprecated, + ); + const fallback = Command.make("fallback").pipe( + withDeprecated, + Command.withDescription("First line\nMore detail"), + ); + const root = Command.make("supabase").pipe(Command.withSubcommands([leaf, other, fallback])); + const context = { rootCommand: root, args: ["--help"] }; + const { console, calls } = fakeConsole(); + const formatterLayer = (formatter: CliOutput.Formatter) => + Layer.mergeAll( + BunServices.layer, + CliOutput.layer(formatter), + Layer.succeed(Console.Console, console), + ); + const layer = formatterLayer(textCliOutputFormatter(context)); + yield* Command.runWith(root, { version: "0" })(["--help"]).pipe(Effect.provide(layer)); + expect(calls.join("\n")).toContain("Show old data (deprecated)"); + expect(calls.join("\n")).toContain("Other data (deprecated)"); + const rows = [ + { + name: "old", + description: "Use the replacement instead.", + shortDescription: "Show old data (deprecated)", + }, + { name: "other", description: "", shortDescription: "Other data (deprecated)" }, + { + name: "fallback", + description: "First line\nMore detail", + shortDescription: "First line (deprecated)", + }, + ]; + calls.length = 0; + yield* Command.runWith(root, { version: "0" })(["--help"]).pipe( + Effect.provide(formatterLayer(jsonCliOutputFormatter(context))), + ); + const json = yield* Schema.decodeEffect(Schema.fromJsonString(Schema.Unknown))( + calls.join("\n").replace(/^log:/, ""), + ); + expect(json).toHaveProperty("doc.subcommands.0.commands", rows); + for (const prefix of [["__complete"], ["__complete", "help"]]) { + const result = respondToComplete(root, [...prefix, ""]); + for (const row of rows) + expect(result?.candidates).toContainEqual({ + name: row.name, + description: row.shortDescription, + }); + } + expect(executed).toBe(false); + expect(docsCommandTree(root).has("supabase-old")).toBe(false); + calls.length = 0; + yield* Command.runWith(root, { version: "0" })(["old", "--help"]).pipe(Effect.provide(layer)); + expect(calls.join("\n")).toContain("Use the replacement instead."); + expect(calls.join("\n")).not.toContain("(deprecated)"); + calls.length = 0; + yield* Command.runWith(root, { version: "0" })(["old"]).pipe(Effect.provide(layer)); + expect(executed).toBe(true); + expect(calls).toEqual([]); + }), + ); +}); diff --git a/apps/cli/src/command-internal/command-access-policy.ts b/apps/cli/src/command-internal/command-access-policy.ts new file mode 100644 index 0000000000..49af1c6252 --- /dev/null +++ b/apps/cli/src/command-internal/command-access-policy.ts @@ -0,0 +1,36 @@ +import { Context, Option } from "effect"; +import { Command } from "effect/cli"; + +/** Documentation requirement paired with the check that enforces experimental access. */ +export class ExperimentalAccessAnnotation extends Context.Service< + ExperimentalAccessAnnotation, + "required" | "optional" +>()("supabase/ExperimentalAccessAnnotation") {} + +export const defineExperimentalAccess = (policy: { + readonly experimental: "required" | "optional"; + readonly check: Check; +}) => ({ + check: policy.check, + annotate: Command.annotate(ExperimentalAccessAnnotation, policy.experimental), +}); + +export const readExperimentalAccess = (command: Command.Command.Any) => + Context.getOption(command.annotations, ExperimentalAccessAnnotation); + +/** Marks commands that remain in help but are excluded from the published reference. */ +export class DeprecatedCommandAnnotation extends Context.Service< + DeprecatedCommandAnnotation, + true +>()("supabase/DeprecatedCommandAnnotation") {} + +export const withDeprecated = Command.annotate(DeprecatedCommandAnnotation, true); + +export const isDeprecated = (command: Command.Command.Any): boolean => + Option.isSome(Context.getOption(command.annotations, DeprecatedCommandAnnotation)); + +export function deprecatedShortDescription(command: Command.Command.Any): string | undefined { + if (!isDeprecated(command)) return undefined; + const base = command.shortDescription ?? command.description?.split("\n")[0] ?? ""; + return `${base} (deprecated)`; +} diff --git a/apps/cli/src/command-internal/experimental-gate.ts b/apps/cli/src/command-internal/experimental-gate.ts index 3b1ccffa95..47aa206cfe 100644 --- a/apps/cli/src/command-internal/experimental-gate.ts +++ b/apps/cli/src/command-internal/experimental-gate.ts @@ -6,6 +6,7 @@ import { ErrorActionabilityId, } from "../shared/telemetry/error-actionability.ts"; import { resolveExperimental } from "./global-flags.ts"; +import { defineExperimentalAccess } from "./command-access-policy.ts"; /** * Gates access to experimental commands and their children. Must run before any @@ -28,7 +29,13 @@ export class ExperimentalRequiredError extends Data.TaggedError("ExperimentalReq } /** Fails with {@link ExperimentalRequiredError} unless experimental is enabled. */ -export const requireExperimental = Effect.gen(function* () { - if (yield* resolveExperimental) return; - return yield* new ExperimentalRequiredError(); +export const requiredExperimentalAccess = defineExperimentalAccess({ + experimental: "required", + check: Effect.gen(function* () { + if (yield* resolveExperimental) return; + return yield* new ExperimentalRequiredError(); + }), }); + +/** Flag-conditional experimental check, without command-level documentation metadata. */ +export const requireExperimental = requiredExperimentalAccess.check; diff --git a/apps/cli/src/commands/db/schema/declarative/declarative.gate.ts b/apps/cli/src/commands/db/schema/declarative/declarative.gate.ts index 4795d192ab..783c44fe45 100644 --- a/apps/cli/src/commands/db/schema/declarative/declarative.gate.ts +++ b/apps/cli/src/commands/db/schema/declarative/declarative.gate.ts @@ -4,6 +4,7 @@ import { Effect } from "effect"; import { aqua, bold } from "../../../../command-internal/colors.ts"; import { configSetting } from "../../../../command-internal/config-advice.ts"; import { DeclarativeNotEnabledError } from "./declarative.errors.ts"; +import { defineExperimentalAccess } from "../../../../command-internal/command-access-policy.ts"; /** * Whether the declarative (pg-delta) code paths are enabled: the gate is open when either the @@ -29,15 +30,18 @@ export function pgDeltaSuggestion(configPath: string, configFormat: ConfigFormat * handler's own mutually-exclusive-flags check — a closed gate wins over a flag conflict, not * the other way around. */ -export const requirePgDelta = Effect.fnUntraced(function* (opts: { - readonly experimental: boolean; - readonly pgDeltaEnabled: boolean; - readonly configPath: string; - readonly configFormat?: ConfigFormat; -}) { - if (isPgDeltaEnabled(opts.experimental, opts.pgDeltaEnabled)) return; - return yield* new DeclarativeNotEnabledError({ - message: "declarative commands require --experimental flag or pg-delta enabled in config", - suggestion: pgDeltaSuggestion(opts.configPath, opts.configFormat), - }); +export const pgDeltaAccess = defineExperimentalAccess({ + experimental: "optional", + check: Effect.fnUntraced(function* (opts: { + readonly experimental: boolean; + readonly pgDeltaEnabled: boolean; + readonly configPath: string; + readonly configFormat?: ConfigFormat; + }) { + if (isPgDeltaEnabled(opts.experimental, opts.pgDeltaEnabled)) return; + return yield* new DeclarativeNotEnabledError({ + message: "declarative commands require --experimental flag or pg-delta enabled in config", + suggestion: pgDeltaSuggestion(opts.configPath, opts.configFormat), + }); + }), }); diff --git a/apps/cli/src/commands/db/schema/declarative/declarative.gate.unit.test.ts b/apps/cli/src/commands/db/schema/declarative/declarative.gate.unit.test.ts index 9695623059..ae1048ebfe 100644 --- a/apps/cli/src/commands/db/schema/declarative/declarative.gate.unit.test.ts +++ b/apps/cli/src/commands/db/schema/declarative/declarative.gate.unit.test.ts @@ -3,7 +3,7 @@ import { describe, expect, it } from "@effect/vitest"; import { stripAnsi } from "../../../../../tests/helpers/ansi.ts"; import { DeclarativeNotEnabledError } from "./declarative.errors.ts"; -import { isPgDeltaEnabled, pgDeltaSuggestion, requirePgDelta } from "./declarative.gate.ts"; +import { isPgDeltaEnabled, pgDeltaSuggestion, pgDeltaAccess } from "./declarative.gate.ts"; const EXPECTED_SUGGESTION = "Pass --experimental to run declarative commands while [experimental.pgdelta] enabled = false is set in supabase/config.toml"; @@ -28,25 +28,29 @@ describe("pgDeltaSuggestion", () => { }); }); -describe("requirePgDelta", () => { +describe("pgDeltaAccess", () => { it.effect("passes through when the gate is open", () => Effect.gen(function* () { - const exit = yield* requirePgDelta({ - experimental: true, - pgDeltaEnabled: false, - configPath: "supabase/config.toml", - }).pipe(Effect.exit); + const exit = yield* pgDeltaAccess + .check({ + experimental: true, + pgDeltaEnabled: false, + configPath: "supabase/config.toml", + }) + .pipe(Effect.exit); expect(Exit.isSuccess(exit)).toBe(true); }), ); it.effect("fails with DeclarativeNotEnabledError when the gate is closed", () => Effect.gen(function* () { - const error = yield* requirePgDelta({ - experimental: false, - pgDeltaEnabled: false, - configPath: "supabase/config.toml", - }).pipe(Effect.flip); + const error = yield* pgDeltaAccess + .check({ + experimental: false, + pgDeltaEnabled: false, + configPath: "supabase/config.toml", + }) + .pipe(Effect.flip); expect(error).toBeInstanceOf(DeclarativeNotEnabledError); expect(error.message).toBe( "declarative commands require --experimental flag or pg-delta enabled in config", diff --git a/apps/cli/src/commands/db/schema/declarative/generate/generate.command.ts b/apps/cli/src/commands/db/schema/declarative/generate/generate.command.ts index d51c7aea4f..08185d8eba 100644 --- a/apps/cli/src/commands/db/schema/declarative/generate/generate.command.ts +++ b/apps/cli/src/commands/db/schema/declarative/generate/generate.command.ts @@ -22,6 +22,7 @@ import { dbSchemaDeclarativeGenerateRuntimeLayer } from "./generate.layers.ts"; import { cliConfigValuesLayer } from "../../../../../config/cli-config-values.layer.ts"; import { branchResolution } from "../../../../../command-internal/target/branch-resolution.ts"; import { targetFlags } from "../../../../../command-internal/target/target-flags.ts"; +import { pgDeltaAccess } from "../declarative.gate.ts"; import { withTargetPolicy } from "../../../../../command-internal/target/target-policy.ts"; const config = { @@ -137,6 +138,7 @@ export const dbSchemaDeclarativeGenerateCommand = Command.make("generate", confi Command.provide(dbSchemaDeclarativeGenerateRuntimeLayer), Command.provide(cliConfigValuesLayer), withCliConfigFlags(config), + pgDeltaAccess.annotate, withTargetPolicy({ group: "selectable", consent: "none", diff --git a/apps/cli/src/commands/db/schema/declarative/generate/generate.handler.ts b/apps/cli/src/commands/db/schema/declarative/generate/generate.handler.ts index d2e4127e6f..30b00a33d5 100644 --- a/apps/cli/src/commands/db/schema/declarative/generate/generate.handler.ts +++ b/apps/cli/src/commands/db/schema/declarative/generate/generate.handler.ts @@ -19,7 +19,7 @@ import { TelemetryState } from "../../../../../telemetry/telemetry-state.service import { isPgDeltaDebugEnabled } from "../../../../../command-internal/pgdelta.ts"; import { DeclarativeWriteError } from "../../../shared/pgdelta.errors.ts"; import { warnFormerDeclarativeDefault } from "../declarative.former-default.ts"; -import { requirePgDelta } from "../declarative.gate.ts"; +import { pgDeltaAccess } from "../declarative.gate.ts"; import { type DeclarativeRunContext, generateDeclarativeOutput, @@ -56,7 +56,7 @@ export const dbSchemaDeclarativeGenerate = Effect.fn("db.schema.declarative.gene const baseToml = yield* readDbConfig(fs, path, cliSettings.workdir); // Gate on the base config: a remote `experimental.pgdelta.enabled = true` must not enable a // base-disabled command without `--experimental`. - yield* requirePgDelta({ + yield* pgDeltaAccess.check({ experimental, pgDeltaEnabled: baseToml.pgDelta.enabled, configPath: baseToml.configFile.path, diff --git a/apps/cli/src/commands/db/schema/declarative/sync/sync.command.ts b/apps/cli/src/commands/db/schema/declarative/sync/sync.command.ts index 56b8c1cab1..0bf63022ff 100644 --- a/apps/cli/src/commands/db/schema/declarative/sync/sync.command.ts +++ b/apps/cli/src/commands/db/schema/declarative/sync/sync.command.ts @@ -12,6 +12,7 @@ import { dbSchemaDeclarativeSharedBase } from "../declarative.shared.ts"; import { dbSchemaDeclarativeSync } from "./sync.handler.ts"; import { dbSchemaDeclarativeSyncRuntimeLayer } from "./sync.layers.ts"; import { cliConfigValuesLayer } from "../../../../../config/cli-config-values.layer.ts"; +import { pgDeltaAccess } from "../declarative.gate.ts"; import { withTargetPolicy } from "../../../../../command-internal/target/target-policy.ts"; import { STACK_SELECTOR_FLAG_NAMES } from "../../../../../command-internal/stack-target.ts"; @@ -108,5 +109,6 @@ export const dbSchemaDeclarativeSyncCommand = Command.make("sync", config).pipe( Command.provide(dbSchemaDeclarativeSyncRuntimeLayer), Command.provide(cliConfigValuesLayer), withCliConfigFlags(config), + pgDeltaAccess.annotate, withTargetPolicy({ group: "local-only", consent: "none" }), ); diff --git a/apps/cli/src/commands/db/schema/declarative/sync/sync.handler.ts b/apps/cli/src/commands/db/schema/declarative/sync/sync.handler.ts index 97b936db14..dafdaac555 100644 --- a/apps/cli/src/commands/db/schema/declarative/sync/sync.handler.ts +++ b/apps/cli/src/commands/db/schema/declarative/sync/sync.handler.ts @@ -61,7 +61,7 @@ import { currentShellPlatform } from "../../../../../command-internal/shell-quot import { rejectStackSelectorOnLegacy } from "../../../../../command-internal/stack-target.ts"; import { warnFormerDeclarativeDefault } from "../declarative.former-default.ts"; import { appendExtensionDeclarations } from "../declarative.extension-repair.ts"; -import { requirePgDelta } from "../declarative.gate.ts"; +import { pgDeltaAccess } from "../declarative.gate.ts"; import { type DeclarativeRunContext, type DeclarativeSyncResult, @@ -106,8 +106,8 @@ export const dbSchemaDeclarativeSync = Effect.fn("db.schema.declarative.sync")(f if ((yield* currentStackBackend).kind === "stack") yield* stackRequireSelected; const toml = yield* readDbConfig(fs, path, cliSettings.workdir); // Gate before the mutex check below — order matters; see - // requirePgDelta's doc comment for why. - yield* requirePgDelta({ + // pgDeltaAccess's doc comment for why. + yield* pgDeltaAccess.check({ experimental, pgDeltaEnabled: toml.pgDelta.enabled, configPath: toml.configFile.path, diff --git a/apps/cli/src/commands/inspect/db/cache-hit/cache-hit.command.ts b/apps/cli/src/commands/inspect/db/cache-hit/cache-hit.command.ts index 03404a48dd..6384389e94 100644 --- a/apps/cli/src/commands/inspect/db/cache-hit/cache-hit.command.ts +++ b/apps/cli/src/commands/inspect/db/cache-hit/cache-hit.command.ts @@ -1,4 +1,5 @@ import { Command } from "effect/cli"; +import { withDeprecated } from "../../../../command-internal/command-access-policy.ts"; import { withPermissions } from "../../../../command-internal/command-permissions/command-permissions.annotation.ts"; import { inspectDbCacheHit } from "./cache-hit.handler.ts"; import { @@ -15,11 +16,12 @@ export const inspectDbCacheHitCommand = Command.make("cache-hit", INSPECT_DB_FLA Command.withDescription( 'Show cache hit rates for tables and indices. Deprecated: use "db-stats" instead.', ), - Command.withShortDescription("Show cache hit rates (deprecated)"), + Command.withShortDescription("Show cache hit rates"), withPermissions(INSPECT_DB_PERMISSIONS), Command.withHandler(inspectDbCommandHandler(inspectDbCacheHit)), Command.provide(inspectDbRuntimeLayer("cache-hit")), Command.provide(cliConfigValuesLayer), withCliConfigFlags(INSPECT_DB_FLAGS), withInspectDbTargetPolicy, + withDeprecated, ); diff --git a/apps/cli/src/commands/inspect/db/index-sizes/index-sizes.command.ts b/apps/cli/src/commands/inspect/db/index-sizes/index-sizes.command.ts index b1cf72223b..6ded402cbf 100644 --- a/apps/cli/src/commands/inspect/db/index-sizes/index-sizes.command.ts +++ b/apps/cli/src/commands/inspect/db/index-sizes/index-sizes.command.ts @@ -1,4 +1,5 @@ import { Command } from "effect/cli"; +import { withDeprecated } from "../../../../command-internal/command-access-policy.ts"; import { withPermissions } from "../../../../command-internal/command-permissions/command-permissions.annotation.ts"; import { inspectDbIndexSizes } from "./index-sizes.handler.ts"; import { @@ -15,11 +16,12 @@ export const inspectDbIndexSizesCommand = Command.make("index-sizes", INSPECT_DB Command.withDescription( 'Show index sizes of individual indexes. Deprecated: use "index-stats" instead.', ), - Command.withShortDescription("Show individual index sizes (deprecated)"), + Command.withShortDescription("Show individual index sizes"), withPermissions(INSPECT_DB_PERMISSIONS), Command.withHandler(inspectDbCommandHandler(inspectDbIndexSizes)), Command.provide(inspectDbRuntimeLayer("index-sizes")), Command.provide(cliConfigValuesLayer), withCliConfigFlags(INSPECT_DB_FLAGS), withInspectDbTargetPolicy, + withDeprecated, ); diff --git a/apps/cli/src/commands/inspect/db/index-usage/index-usage.command.ts b/apps/cli/src/commands/inspect/db/index-usage/index-usage.command.ts index b584230c0a..b99231c23f 100644 --- a/apps/cli/src/commands/inspect/db/index-usage/index-usage.command.ts +++ b/apps/cli/src/commands/inspect/db/index-usage/index-usage.command.ts @@ -1,4 +1,5 @@ import { Command } from "effect/cli"; +import { withDeprecated } from "../../../../command-internal/command-access-policy.ts"; import { withPermissions } from "../../../../command-internal/command-permissions/command-permissions.annotation.ts"; import { inspectDbIndexUsage } from "./index-usage.handler.ts"; import { @@ -15,11 +16,12 @@ export const inspectDbIndexUsageCommand = Command.make("index-usage", INSPECT_DB Command.withDescription( 'Show information about the efficiency of indexes. Deprecated: use "index-stats" instead.', ), - Command.withShortDescription("Show index efficiency (deprecated)"), + Command.withShortDescription("Show index efficiency"), withPermissions(INSPECT_DB_PERMISSIONS), Command.withHandler(inspectDbCommandHandler(inspectDbIndexUsage)), Command.provide(inspectDbRuntimeLayer("index-usage")), Command.provide(cliConfigValuesLayer), withCliConfigFlags(INSPECT_DB_FLAGS), withInspectDbTargetPolicy, + withDeprecated, ); diff --git a/apps/cli/src/commands/inspect/db/role-configs/role-configs.command.ts b/apps/cli/src/commands/inspect/db/role-configs/role-configs.command.ts index 057274f77e..1530bd2626 100644 --- a/apps/cli/src/commands/inspect/db/role-configs/role-configs.command.ts +++ b/apps/cli/src/commands/inspect/db/role-configs/role-configs.command.ts @@ -1,4 +1,5 @@ import { Command } from "effect/cli"; +import { withDeprecated } from "../../../../command-internal/command-access-policy.ts"; import { withPermissions } from "../../../../command-internal/command-permissions/command-permissions.annotation.ts"; import { inspectDbRoleConfigs } from "./role-configs.handler.ts"; import { @@ -15,11 +16,12 @@ export const inspectDbRoleConfigsCommand = Command.make("role-configs", INSPECT_ Command.withDescription( 'Show configuration settings for database roles when they have been modified. Deprecated: use "role-stats" instead.', ), - Command.withShortDescription("Show role configs (deprecated)"), + Command.withShortDescription("Show role configs"), withPermissions(INSPECT_DB_PERMISSIONS), Command.withHandler(inspectDbCommandHandler(inspectDbRoleConfigs)), Command.provide(inspectDbRuntimeLayer("role-configs")), Command.provide(cliConfigValuesLayer), withCliConfigFlags(INSPECT_DB_FLAGS), withInspectDbTargetPolicy, + withDeprecated, ); diff --git a/apps/cli/src/commands/inspect/db/role-connections/role-connections.command.ts b/apps/cli/src/commands/inspect/db/role-connections/role-connections.command.ts index 686089f083..c99f7a365e 100644 --- a/apps/cli/src/commands/inspect/db/role-connections/role-connections.command.ts +++ b/apps/cli/src/commands/inspect/db/role-connections/role-connections.command.ts @@ -1,4 +1,5 @@ import { Command } from "effect/cli"; +import { withDeprecated } from "../../../../command-internal/command-access-policy.ts"; import { withPermissions } from "../../../../command-internal/command-permissions/command-permissions.annotation.ts"; import { inspectDbRoleConnections } from "./role-connections.handler.ts"; import { @@ -18,11 +19,12 @@ export const inspectDbRoleConnectionsCommand = Command.make( Command.withDescription( 'Show number of active connections for all database roles. Deprecated: use "role-stats" instead.', ), - Command.withShortDescription("Show role connections (deprecated)"), + Command.withShortDescription("Show role connections"), withPermissions(INSPECT_DB_PERMISSIONS), Command.withHandler(inspectDbCommandHandler(inspectDbRoleConnections)), Command.provide(inspectDbRuntimeLayer("role-connections")), Command.provide(cliConfigValuesLayer), withCliConfigFlags(INSPECT_DB_FLAGS), withInspectDbTargetPolicy, + withDeprecated, ); diff --git a/apps/cli/src/commands/inspect/db/seq-scans/seq-scans.command.ts b/apps/cli/src/commands/inspect/db/seq-scans/seq-scans.command.ts index 599ad3b392..44b9164478 100644 --- a/apps/cli/src/commands/inspect/db/seq-scans/seq-scans.command.ts +++ b/apps/cli/src/commands/inspect/db/seq-scans/seq-scans.command.ts @@ -1,4 +1,5 @@ import { Command } from "effect/cli"; +import { withDeprecated } from "../../../../command-internal/command-access-policy.ts"; import { withPermissions } from "../../../../command-internal/command-permissions/command-permissions.annotation.ts"; import { inspectDbSeqScans } from "./seq-scans.handler.ts"; import { @@ -15,11 +16,12 @@ export const inspectDbSeqScansCommand = Command.make("seq-scans", INSPECT_DB_FLA Command.withDescription( 'Show number of sequential scans recorded against all tables. Deprecated: use "index-stats" instead.', ), - Command.withShortDescription("Show sequential scans (deprecated)"), + Command.withShortDescription("Show sequential scans"), withPermissions(INSPECT_DB_PERMISSIONS), Command.withHandler(inspectDbCommandHandler(inspectDbSeqScans)), Command.provide(inspectDbRuntimeLayer("seq-scans")), Command.provide(cliConfigValuesLayer), withCliConfigFlags(INSPECT_DB_FLAGS), withInspectDbTargetPolicy, + withDeprecated, ); diff --git a/apps/cli/src/commands/inspect/db/table-record-counts/table-record-counts.command.ts b/apps/cli/src/commands/inspect/db/table-record-counts/table-record-counts.command.ts index bc9cfd673c..ab360cef40 100644 --- a/apps/cli/src/commands/inspect/db/table-record-counts/table-record-counts.command.ts +++ b/apps/cli/src/commands/inspect/db/table-record-counts/table-record-counts.command.ts @@ -1,4 +1,5 @@ import { Command } from "effect/cli"; +import { withDeprecated } from "../../../../command-internal/command-access-policy.ts"; import { withPermissions } from "../../../../command-internal/command-permissions/command-permissions.annotation.ts"; import { inspectDbTableRecordCounts } from "./table-record-counts.handler.ts"; import { @@ -18,11 +19,12 @@ export const inspectDbTableRecordCountsCommand = Command.make( Command.withDescription( 'Show estimated number of rows per table. Deprecated: use "table-stats" instead.', ), - Command.withShortDescription("Show table record counts (deprecated)"), + Command.withShortDescription("Show table record counts"), withPermissions(INSPECT_DB_PERMISSIONS), Command.withHandler(inspectDbCommandHandler(inspectDbTableRecordCounts)), Command.provide(inspectDbRuntimeLayer("table-record-counts")), Command.provide(cliConfigValuesLayer), withCliConfigFlags(INSPECT_DB_FLAGS), withInspectDbTargetPolicy, + withDeprecated, ); diff --git a/apps/cli/src/commands/inspect/db/table-sizes/table-sizes.command.ts b/apps/cli/src/commands/inspect/db/table-sizes/table-sizes.command.ts index 7ea8782416..8d5634a97a 100644 --- a/apps/cli/src/commands/inspect/db/table-sizes/table-sizes.command.ts +++ b/apps/cli/src/commands/inspect/db/table-sizes/table-sizes.command.ts @@ -1,4 +1,5 @@ import { Command } from "effect/cli"; +import { withDeprecated } from "../../../../command-internal/command-access-policy.ts"; import { withPermissions } from "../../../../command-internal/command-permissions/command-permissions.annotation.ts"; import { inspectDbTableSizes } from "./table-sizes.handler.ts"; import { @@ -15,11 +16,12 @@ export const inspectDbTableSizesCommand = Command.make("table-sizes", INSPECT_DB Command.withDescription( 'Show table sizes of individual tables without their index sizes. Deprecated: use "table-stats" instead.', ), - Command.withShortDescription("Show table sizes (deprecated)"), + Command.withShortDescription("Show table sizes"), withPermissions(INSPECT_DB_PERMISSIONS), Command.withHandler(inspectDbCommandHandler(inspectDbTableSizes)), Command.provide(inspectDbRuntimeLayer("table-sizes")), Command.provide(cliConfigValuesLayer), withCliConfigFlags(INSPECT_DB_FLAGS), withInspectDbTargetPolicy, + withDeprecated, ); diff --git a/apps/cli/src/commands/inspect/db/unused-indexes/unused-indexes.command.ts b/apps/cli/src/commands/inspect/db/unused-indexes/unused-indexes.command.ts index 4557296b46..e8b78b36da 100644 --- a/apps/cli/src/commands/inspect/db/unused-indexes/unused-indexes.command.ts +++ b/apps/cli/src/commands/inspect/db/unused-indexes/unused-indexes.command.ts @@ -1,4 +1,5 @@ import { Command } from "effect/cli"; +import { withDeprecated } from "../../../../command-internal/command-access-policy.ts"; import { withPermissions } from "../../../../command-internal/command-permissions/command-permissions.annotation.ts"; import { inspectDbUnusedIndexes } from "./unused-indexes.handler.ts"; import { @@ -13,11 +14,12 @@ import { withCliConfigFlags } from "../../../../config/cli-config-flags.ts"; export const inspectDbUnusedIndexesCommand = Command.make("unused-indexes", INSPECT_DB_FLAGS).pipe( Command.withDescription('Show indexes with low usage. Deprecated: use "index-stats" instead.'), - Command.withShortDescription("Show unused indexes (deprecated)"), + Command.withShortDescription("Show unused indexes"), withPermissions(INSPECT_DB_PERMISSIONS), Command.withHandler(inspectDbCommandHandler(inspectDbUnusedIndexes)), Command.provide(inspectDbRuntimeLayer("unused-indexes")), Command.provide(cliConfigValuesLayer), withCliConfigFlags(INSPECT_DB_FLAGS), withInspectDbTargetPolicy, + withDeprecated, ); diff --git a/apps/cli/src/commands/network-bans/get/get.command.ts b/apps/cli/src/commands/network-bans/get/get.command.ts index 278b0ea5a8..dfd981708f 100644 --- a/apps/cli/src/commands/network-bans/get/get.command.ts +++ b/apps/cli/src/commands/network-bans/get/get.command.ts @@ -9,7 +9,7 @@ import { projectTargetFlags } from "../../../command-internal/target/target-flag import { projectRefPicker } from "../../../config/project-ref.layer.ts"; import { linkedProjectCache } from "../../../telemetry/linked-project-cache.layer.ts"; import { withJsonErrorHandling } from "../../../shared/output/json-error-handling.ts"; -import { requireExperimental } from "../../../command-internal/experimental-gate.ts"; +import { requiredExperimentalAccess } from "../../../command-internal/experimental-gate.ts"; import { RESOURCE_OUTPUT_FORMATS } from "../../../command-internal/output-formats.ts"; import { managementApiRuntimeLayer } from "../../../command-internal/management-api-runtime.layer.ts"; import { @@ -46,12 +46,13 @@ export const networkBansGetCommand = Command.make("get", config).pipe( // managementApiRuntimeLayer eagerly resolves an access token, so it's provided here // (after the gate) rather than via Command.provide, which would build it — and fail // on a missing token — before this generator's first yield* runs. - yield* requireExperimental; + yield* requiredExperimentalAccess.check; return yield* networkBansGet(flags).pipe( withCommandTelemetry({ flags }), Effect.provide(managementApiRuntimeLayer(["network-bans", "get"])), ); }).pipe(withJsonErrorHandling), ), + requiredExperimentalAccess.annotate, withTargetPolicy({ group: "hosted", consent: "none" }), ); diff --git a/apps/cli/src/commands/network-bans/remove/remove.command.ts b/apps/cli/src/commands/network-bans/remove/remove.command.ts index cd6019a9ac..888fd6a2ce 100644 --- a/apps/cli/src/commands/network-bans/remove/remove.command.ts +++ b/apps/cli/src/commands/network-bans/remove/remove.command.ts @@ -9,7 +9,7 @@ import { projectTargetFlags } from "../../../command-internal/target/target-flag import { projectRefPicker } from "../../../config/project-ref.layer.ts"; import { linkedProjectCache } from "../../../telemetry/linked-project-cache.layer.ts"; import { withJsonErrorHandling } from "../../../shared/output/json-error-handling.ts"; -import { requireExperimental } from "../../../command-internal/experimental-gate.ts"; +import { requiredExperimentalAccess } from "../../../command-internal/experimental-gate.ts"; import { RESOURCE_OUTPUT_FORMATS } from "../../../command-internal/output-formats.ts"; import { managementApiRuntimeLayer } from "../../../command-internal/management-api-runtime.layer.ts"; import { stringSliceFlag } from "../../../command-internal/string-slice-flag.ts"; @@ -59,12 +59,13 @@ export const networkBansRemoveCommand = Command.make("remove", config).pipe( // managementApiRuntimeLayer eagerly resolves an access token, so it's provided here // (after the gate) rather than via Command.provide, which would build it — and fail // on a missing token — before this generator's first yield* runs. - yield* requireExperimental; + yield* requiredExperimentalAccess.check; return yield* networkBansRemove(flags).pipe( withCommandTelemetry({ flags }), Effect.provide(managementApiRuntimeLayer(["network-bans", "remove"])), ); }).pipe(withJsonErrorHandling), ), + requiredExperimentalAccess.annotate, withTargetPolicy({ group: "hosted", consent: "no" }), ); diff --git a/apps/cli/src/commands/network-restrictions/get/get.command.ts b/apps/cli/src/commands/network-restrictions/get/get.command.ts index 1d975c1575..076835b031 100644 --- a/apps/cli/src/commands/network-restrictions/get/get.command.ts +++ b/apps/cli/src/commands/network-restrictions/get/get.command.ts @@ -9,7 +9,7 @@ import { projectTargetFlags } from "../../../command-internal/target/target-flag import { projectRefPicker } from "../../../config/project-ref.layer.ts"; import { linkedProjectCache } from "../../../telemetry/linked-project-cache.layer.ts"; import { withJsonErrorHandling } from "../../../shared/output/json-error-handling.ts"; -import { requireExperimental } from "../../../command-internal/experimental-gate.ts"; +import { requiredExperimentalAccess } from "../../../command-internal/experimental-gate.ts"; import { RESOURCE_OUTPUT_FORMATS } from "../../../command-internal/output-formats.ts"; import { managementApiRuntimeLayer } from "../../../command-internal/management-api-runtime.layer.ts"; import { @@ -46,12 +46,13 @@ export const networkRestrictionsGetCommand = Command.make("get", config).pipe( // managementApiRuntimeLayer eagerly resolves an access token, so it's provided here // (after the gate) rather than via Command.provide, which would build it — and fail // on a missing token — before this generator's first yield* runs. - yield* requireExperimental; + yield* requiredExperimentalAccess.check; return yield* networkRestrictionsGet(flags).pipe( withCommandTelemetry({ flags }), Effect.provide(managementApiRuntimeLayer(["network-restrictions", "get"])), ); }).pipe(withJsonErrorHandling), ), + requiredExperimentalAccess.annotate, withTargetPolicy({ group: "hosted", consent: "none" }), ); diff --git a/apps/cli/src/commands/network-restrictions/update/update.command.ts b/apps/cli/src/commands/network-restrictions/update/update.command.ts index 83b3798881..1433556c06 100644 --- a/apps/cli/src/commands/network-restrictions/update/update.command.ts +++ b/apps/cli/src/commands/network-restrictions/update/update.command.ts @@ -9,7 +9,7 @@ import { projectTargetFlags } from "../../../command-internal/target/target-flag import { projectRefPicker } from "../../../config/project-ref.layer.ts"; import { linkedProjectCache } from "../../../telemetry/linked-project-cache.layer.ts"; import { withJsonErrorHandling } from "../../../shared/output/json-error-handling.ts"; -import { requireExperimental } from "../../../command-internal/experimental-gate.ts"; +import { requiredExperimentalAccess } from "../../../command-internal/experimental-gate.ts"; import { RESOURCE_OUTPUT_FORMATS } from "../../../command-internal/output-formats.ts"; import { managementApiRuntimeLayer } from "../../../command-internal/management-api-runtime.layer.ts"; import { stringSliceFlag } from "../../../command-internal/string-slice-flag.ts"; @@ -79,12 +79,13 @@ export const networkRestrictionsUpdateCommand = Command.make("update", config).p // eagerly resolves an access token, so it's provided here (after the gate) rather than // via Command.provide, which would fail on a missing token before this generator's // first yield* runs. - yield* requireExperimental; + yield* requiredExperimentalAccess.check; return yield* networkRestrictionsUpdate(flags).pipe( withCommandTelemetry({ flags }), Effect.provide(managementApiRuntimeLayer(["network-restrictions", "update"])), ); }).pipe(withJsonErrorHandling), ), + requiredExperimentalAccess.annotate, withTargetPolicy({ group: "hosted", consent: "no" }), ); diff --git a/apps/cli/src/commands/postgres-config/delete/delete.command.ts b/apps/cli/src/commands/postgres-config/delete/delete.command.ts index 5c3fcef0e0..10988c3be9 100644 --- a/apps/cli/src/commands/postgres-config/delete/delete.command.ts +++ b/apps/cli/src/commands/postgres-config/delete/delete.command.ts @@ -10,7 +10,7 @@ import { projectRefPicker } from "../../../config/project-ref.layer.ts"; import { linkedProjectCache } from "../../../telemetry/linked-project-cache.layer.ts"; import { postgresConfigRead, postgresConfigWrite } from "../postgres-config.shared.ts"; import { withJsonErrorHandling } from "../../../shared/output/json-error-handling.ts"; -import { requireExperimental } from "../../../command-internal/experimental-gate.ts"; +import { requiredExperimentalAccess } from "../../../command-internal/experimental-gate.ts"; import { RESOURCE_OUTPUT_FORMATS } from "../../../command-internal/output-formats.ts"; import { managementApiRuntimeLayer } from "../../../command-internal/management-api-runtime.layer.ts"; import { stringSliceFlag } from "../../../command-internal/string-slice-flag.ts"; @@ -62,12 +62,13 @@ export const postgresConfigDeleteCommand = Command.make("delete", config).pipe( // managementApiRuntimeLayer eagerly resolves an access token, so it's provided here // (after the gate) rather than via Command.provide, which would build it — and fail // on a missing token — before this generator's first yield* runs. - yield* requireExperimental; + yield* requiredExperimentalAccess.check; return yield* postgresConfigDelete(flags).pipe( withCommandTelemetry({ flags }), Effect.provide(managementApiRuntimeLayer(["postgres-config", "delete"])), ); }).pipe(withJsonErrorHandling), ), + requiredExperimentalAccess.annotate, withTargetPolicy({ group: "hosted", consent: "no" }), ); diff --git a/apps/cli/src/commands/postgres-config/get/get.command.ts b/apps/cli/src/commands/postgres-config/get/get.command.ts index 7d8d173679..9353e34f8d 100644 --- a/apps/cli/src/commands/postgres-config/get/get.command.ts +++ b/apps/cli/src/commands/postgres-config/get/get.command.ts @@ -10,7 +10,7 @@ import { projectRefPicker } from "../../../config/project-ref.layer.ts"; import { linkedProjectCache } from "../../../telemetry/linked-project-cache.layer.ts"; import { postgresConfigRead } from "../postgres-config.shared.ts"; import { withJsonErrorHandling } from "../../../shared/output/json-error-handling.ts"; -import { requireExperimental } from "../../../command-internal/experimental-gate.ts"; +import { requiredExperimentalAccess } from "../../../command-internal/experimental-gate.ts"; import { RESOURCE_OUTPUT_FORMATS } from "../../../command-internal/output-formats.ts"; import { managementApiRuntimeLayer } from "../../../command-internal/management-api-runtime.layer.ts"; import { @@ -46,12 +46,13 @@ export const postgresConfigGetCommand = Command.make("get", config).pipe( // managementApiRuntimeLayer eagerly resolves an access token, so it's provided here // (after the gate) rather than via Command.provide, which would build it — and fail // on a missing token — before this generator's first yield* runs. - yield* requireExperimental; + yield* requiredExperimentalAccess.check; return yield* postgresConfigGet(flags).pipe( withCommandTelemetry({ flags }), Effect.provide(managementApiRuntimeLayer(["postgres-config", "get"])), ); }).pipe(withJsonErrorHandling), ), + requiredExperimentalAccess.annotate, withTargetPolicy({ group: "hosted", consent: "none" }), ); diff --git a/apps/cli/src/commands/postgres-config/update/update.command.ts b/apps/cli/src/commands/postgres-config/update/update.command.ts index 72671a8af6..2c696fa05a 100644 --- a/apps/cli/src/commands/postgres-config/update/update.command.ts +++ b/apps/cli/src/commands/postgres-config/update/update.command.ts @@ -10,7 +10,7 @@ import { projectRefPicker } from "../../../config/project-ref.layer.ts"; import { linkedProjectCache } from "../../../telemetry/linked-project-cache.layer.ts"; import { postgresConfigRead, postgresConfigWrite } from "../postgres-config.shared.ts"; import { withJsonErrorHandling } from "../../../shared/output/json-error-handling.ts"; -import { requireExperimental } from "../../../command-internal/experimental-gate.ts"; +import { requiredExperimentalAccess } from "../../../command-internal/experimental-gate.ts"; import { RESOURCE_OUTPUT_FORMATS } from "../../../command-internal/output-formats.ts"; import { managementApiRuntimeLayer } from "../../../command-internal/management-api-runtime.layer.ts"; import { stringSliceFlag } from "../../../command-internal/string-slice-flag.ts"; @@ -68,12 +68,13 @@ export const postgresConfigUpdateCommand = Command.make("update", config).pipe( // managementApiRuntimeLayer eagerly resolves an access token, so it's provided here // (after the gate) rather than via Command.provide, which would build it — and fail // on a missing token — before this generator's first yield* runs. - yield* requireExperimental; + yield* requiredExperimentalAccess.check; return yield* postgresConfigUpdate(flags).pipe( withCommandTelemetry({ flags }), Effect.provide(managementApiRuntimeLayer(["postgres-config", "update"])), ); }).pipe(withJsonErrorHandling), ), + requiredExperimentalAccess.annotate, withTargetPolicy({ group: "hosted", consent: "no" }), ); diff --git a/apps/cli/src/commands/ssl-enforcement/get/get.command.ts b/apps/cli/src/commands/ssl-enforcement/get/get.command.ts index ee509eeb2c..d662c5e97c 100644 --- a/apps/cli/src/commands/ssl-enforcement/get/get.command.ts +++ b/apps/cli/src/commands/ssl-enforcement/get/get.command.ts @@ -9,7 +9,7 @@ import { projectTargetFlags } from "../../../command-internal/target/target-flag import { projectRefPicker } from "../../../config/project-ref.layer.ts"; import { linkedProjectCache } from "../../../telemetry/linked-project-cache.layer.ts"; import { withJsonErrorHandling } from "../../../shared/output/json-error-handling.ts"; -import { requireExperimental } from "../../../command-internal/experimental-gate.ts"; +import { requiredExperimentalAccess } from "../../../command-internal/experimental-gate.ts"; import { RESOURCE_OUTPUT_FORMATS } from "../../../command-internal/output-formats.ts"; import { managementApiRuntimeLayer } from "../../../command-internal/management-api-runtime.layer.ts"; import { @@ -46,12 +46,13 @@ export const sslEnforcementGetCommand = Command.make("get", config).pipe( // The --experimental gate must run before `managementApiRuntimeLayer` is // provided (inline here, not via `Command.provide`) — that layer eagerly // resolves an access token and would fail on a missing one first. - yield* requireExperimental; + yield* requiredExperimentalAccess.check; return yield* sslEnforcementGet(flags).pipe( withCommandTelemetry({ flags }), Effect.provide(managementApiRuntimeLayer(["ssl-enforcement", "get"])), ); }).pipe(withJsonErrorHandling), ), + requiredExperimentalAccess.annotate, withTargetPolicy({ group: "hosted", consent: "none" }), ); diff --git a/apps/cli/src/commands/ssl-enforcement/update/update.command.ts b/apps/cli/src/commands/ssl-enforcement/update/update.command.ts index 31e2058686..873fc66c6e 100644 --- a/apps/cli/src/commands/ssl-enforcement/update/update.command.ts +++ b/apps/cli/src/commands/ssl-enforcement/update/update.command.ts @@ -9,7 +9,7 @@ import { projectTargetFlags } from "../../../command-internal/target/target-flag import { projectRefPicker } from "../../../config/project-ref.layer.ts"; import { linkedProjectCache } from "../../../telemetry/linked-project-cache.layer.ts"; import { withJsonErrorHandling } from "../../../shared/output/json-error-handling.ts"; -import { requireExperimental } from "../../../command-internal/experimental-gate.ts"; +import { requiredExperimentalAccess } from "../../../command-internal/experimental-gate.ts"; import { RESOURCE_OUTPUT_FORMATS } from "../../../command-internal/output-formats.ts"; import { managementApiRuntimeLayer } from "../../../command-internal/management-api-runtime.layer.ts"; import { @@ -69,12 +69,13 @@ export const sslEnforcementUpdateCommand = Command.make("update", config).pipe( // The --experimental gate must run before `managementApiRuntimeLayer` is // provided (inline here, not via `Command.provide`) — that layer eagerly // resolves an access token and would fail on a missing one first. - yield* requireExperimental; + yield* requiredExperimentalAccess.check; return yield* sslEnforcementUpdate(flags).pipe( withCommandTelemetry({ flags }), Effect.provide(managementApiRuntimeLayer(["ssl-enforcement", "update"])), ); }).pipe(withJsonErrorHandling), ), + requiredExperimentalAccess.annotate, withTargetPolicy({ group: "hosted", consent: "no" }), ); diff --git a/apps/cli/src/commands/storage/cp/cp.command.ts b/apps/cli/src/commands/storage/cp/cp.command.ts index b78ebb93dd..57d078890a 100644 --- a/apps/cli/src/commands/storage/cp/cp.command.ts +++ b/apps/cli/src/commands/storage/cp/cp.command.ts @@ -8,7 +8,7 @@ import { withPermissions } from "../../../command-internal/command-permissions/c import { compose } from "../../../command-internal/command-permissions/model.ts"; import { withJsonErrorHandling } from "../../../shared/output/json-error-handling.ts"; import { withCommandTelemetry } from "../../../telemetry/command-telemetry.ts"; -import { requireExperimental } from "../../../command-internal/experimental-gate.ts"; +import { requiredExperimentalAccess } from "../../../command-internal/experimental-gate.ts"; import { storageGatewayRuntimeLayer } from "../../../command-internal/storage-runtime.layer.ts"; import { storageInvalidJobsMessage } from "../storage.errors.ts"; import { parseUintBase0 } from "../../../shared/config/parse-uint.ts"; @@ -91,7 +91,7 @@ export const storageCpCommand = Command.make("cp", config).pipe( Command.withHandler((flags) => Effect.gen(function* () { // A non-uint `--jobs` never reaches here: `Flag.mapTryCatch` rejects it at parse time. - yield* requireExperimental; + yield* requiredExperimentalAccess.check; const telemetryFlags = { recursive: flags.recursive, cacheControl: flags.cacheControl, @@ -104,5 +104,6 @@ export const storageCpCommand = Command.make("cp", config).pipe( Command.provide(storageGatewayRuntimeLayer(["storage", "cp"])), Command.provide(cliConfigValuesLayer), withCliConfigFlags(config), + requiredExperimentalAccess.annotate, withTargetPolicy({ group: "selectable", consent: "no" }), ); diff --git a/apps/cli/src/commands/storage/ls/ls.command.ts b/apps/cli/src/commands/storage/ls/ls.command.ts index 0668d57a4c..32b6dc4e65 100644 --- a/apps/cli/src/commands/storage/ls/ls.command.ts +++ b/apps/cli/src/commands/storage/ls/ls.command.ts @@ -7,7 +7,7 @@ import { cliConfigValuesLayer } from "../../../config/cli-config-values.layer.ts import { withPermissions } from "../../../command-internal/command-permissions/command-permissions.annotation.ts"; import { withJsonErrorHandling } from "../../../shared/output/json-error-handling.ts"; import { withCommandTelemetry } from "../../../telemetry/command-telemetry.ts"; -import { requireExperimental } from "../../../command-internal/experimental-gate.ts"; +import { requiredExperimentalAccess } from "../../../command-internal/experimental-gate.ts"; import { storageGatewayRuntimeLayer } from "../../../command-internal/storage-runtime.layer.ts"; import { STORAGE_PERMISSIONS, storageTargetFlags } from "../storage.flags.ts"; import { storageLs } from "./ls.handler.ts"; @@ -40,7 +40,7 @@ export const storageLsCommand = Command.make("ls", config).pipe( withPermissions(STORAGE_PERMISSIONS), Command.withHandler((flags) => Effect.gen(function* () { - yield* requireExperimental; + yield* requiredExperimentalAccess.check; const telemetryFlags = { recursive: flags.recursive, }; @@ -50,5 +50,6 @@ export const storageLsCommand = Command.make("ls", config).pipe( Command.provide(storageGatewayRuntimeLayer(["storage", "ls"])), Command.provide(cliConfigValuesLayer), withCliConfigFlags(config), + requiredExperimentalAccess.annotate, withTargetPolicy({ group: "selectable", consent: "none", consentExemptReason: "read-only" }), ); diff --git a/apps/cli/src/commands/storage/mv/mv.command.ts b/apps/cli/src/commands/storage/mv/mv.command.ts index d8253023dc..3abe76b1cc 100644 --- a/apps/cli/src/commands/storage/mv/mv.command.ts +++ b/apps/cli/src/commands/storage/mv/mv.command.ts @@ -7,7 +7,7 @@ import { cliConfigValuesLayer } from "../../../config/cli-config-values.layer.ts import { withPermissions } from "../../../command-internal/command-permissions/command-permissions.annotation.ts"; import { withJsonErrorHandling } from "../../../shared/output/json-error-handling.ts"; import { withCommandTelemetry } from "../../../telemetry/command-telemetry.ts"; -import { requireExperimental } from "../../../command-internal/experimental-gate.ts"; +import { requiredExperimentalAccess } from "../../../command-internal/experimental-gate.ts"; import { storageGatewayRuntimeLayer } from "../../../command-internal/storage-runtime.layer.ts"; import { STORAGE_PERMISSIONS, storageTargetFlags } from "../storage.flags.ts"; import { storageMv } from "./mv.handler.ts"; @@ -38,7 +38,7 @@ export const storageMvCommand = Command.make("mv", config).pipe( withPermissions(STORAGE_PERMISSIONS), Command.withHandler((flags) => Effect.gen(function* () { - yield* requireExperimental; + yield* requiredExperimentalAccess.check; const telemetryFlags = { recursive: flags.recursive, }; @@ -48,5 +48,6 @@ export const storageMvCommand = Command.make("mv", config).pipe( Command.provide(storageGatewayRuntimeLayer(["storage", "mv"])), Command.provide(cliConfigValuesLayer), withCliConfigFlags(config), + requiredExperimentalAccess.annotate, withTargetPolicy({ group: "selectable", consent: "no" }), ); diff --git a/apps/cli/src/commands/storage/rm/rm.command.ts b/apps/cli/src/commands/storage/rm/rm.command.ts index ce48466392..c8b5a1ccbf 100644 --- a/apps/cli/src/commands/storage/rm/rm.command.ts +++ b/apps/cli/src/commands/storage/rm/rm.command.ts @@ -7,7 +7,7 @@ import { withPermissions } from "../../../command-internal/command-permissions/c import { withJsonErrorHandling } from "../../../shared/output/json-error-handling.ts"; import { withCommandTelemetry } from "../../../telemetry/command-telemetry.ts"; import { stdinLayer } from "../../../shared/runtime/stdin.layer.ts"; -import { requireExperimental } from "../../../command-internal/experimental-gate.ts"; +import { requiredExperimentalAccess } from "../../../command-internal/experimental-gate.ts"; import { storageGatewayRuntimeLayer } from "../../../command-internal/storage-runtime.layer.ts"; import { STORAGE_PERMISSIONS, storageTargetFlags } from "../storage.flags.ts"; import { storageRm } from "./rm.handler.ts"; @@ -42,7 +42,7 @@ export const storageRmCommand = Command.make("rm", config).pipe( withPermissions(STORAGE_PERMISSIONS), Command.withHandler((flags) => Effect.gen(function* () { - yield* requireExperimental; + yield* requiredExperimentalAccess.check; const telemetryFlags = { recursive: flags.recursive, }; @@ -59,5 +59,6 @@ export const storageRmCommand = Command.make("rm", config).pipe( Command.provide(Layer.mergeAll(storageGatewayRuntimeLayer(["storage", "rm"]), stdinLayer)), Command.provide(cliConfigValuesLayer), withCliConfigFlags(config), + requiredExperimentalAccess.annotate, withTargetPolicy({ group: "selectable", consent: "no" }), ); diff --git a/apps/cli/src/commands/vanity-subdomains/activate/activate.command.ts b/apps/cli/src/commands/vanity-subdomains/activate/activate.command.ts index dfe369822f..ba57022d04 100644 --- a/apps/cli/src/commands/vanity-subdomains/activate/activate.command.ts +++ b/apps/cli/src/commands/vanity-subdomains/activate/activate.command.ts @@ -9,7 +9,7 @@ import { projectTargetFlags } from "../../../command-internal/target/target-flag import { projectRefPicker } from "../../../config/project-ref.layer.ts"; import { linkedProjectCache } from "../../../telemetry/linked-project-cache.layer.ts"; import { withJsonErrorHandling } from "../../../shared/output/json-error-handling.ts"; -import { requireExperimental } from "../../../command-internal/experimental-gate.ts"; +import { requiredExperimentalAccess } from "../../../command-internal/experimental-gate.ts"; import { RESOURCE_OUTPUT_FORMATS } from "../../../command-internal/output-formats.ts"; import { managementApiRuntimeLayer } from "../../../command-internal/management-api-runtime.layer.ts"; import { @@ -67,12 +67,13 @@ export const vanitySubdomainsActivateCommand = Command.make("activate", config). // inline after the experimental gate rather than via `Command.provide` on the // whole command — `Command.provide` would build the layer, and fail on a missing // token, before the gate ever runs. - yield* requireExperimental; + yield* requiredExperimentalAccess.check; return yield* vanitySubdomainsActivate(flags).pipe( withCommandTelemetry({ flags }), Effect.provide(managementApiRuntimeLayer(["vanity-subdomains", "activate"])), ); }).pipe(withJsonErrorHandling), ), + requiredExperimentalAccess.annotate, withTargetPolicy({ group: "hosted", consent: "no" }), ); diff --git a/apps/cli/src/commands/vanity-subdomains/check-availability/check-availability.command.ts b/apps/cli/src/commands/vanity-subdomains/check-availability/check-availability.command.ts index 2e21251ac1..203862ece0 100644 --- a/apps/cli/src/commands/vanity-subdomains/check-availability/check-availability.command.ts +++ b/apps/cli/src/commands/vanity-subdomains/check-availability/check-availability.command.ts @@ -9,7 +9,7 @@ import { projectTargetFlags } from "../../../command-internal/target/target-flag import { projectRefPicker } from "../../../config/project-ref.layer.ts"; import { linkedProjectCache } from "../../../telemetry/linked-project-cache.layer.ts"; import { withJsonErrorHandling } from "../../../shared/output/json-error-handling.ts"; -import { requireExperimental } from "../../../command-internal/experimental-gate.ts"; +import { requiredExperimentalAccess } from "../../../command-internal/experimental-gate.ts"; import { RESOURCE_OUTPUT_FORMATS } from "../../../command-internal/output-formats.ts"; import { managementApiRuntimeLayer } from "../../../command-internal/management-api-runtime.layer.ts"; import { @@ -68,12 +68,13 @@ export const vanitySubdomainsCheckAvailabilityCommand = Command.make( // inline after the experimental gate rather than via `Command.provide` on the // whole command — `Command.provide` would build the layer, and fail on a missing // token, before the gate ever runs. - yield* requireExperimental; + yield* requiredExperimentalAccess.check; return yield* vanitySubdomainsCheckAvailability(flags).pipe( withCommandTelemetry({ flags }), Effect.provide(managementApiRuntimeLayer(["vanity-subdomains", "check-availability"])), ); }).pipe(withJsonErrorHandling), ), + requiredExperimentalAccess.annotate, withTargetPolicy({ group: "hosted", consent: "none" }), ); diff --git a/apps/cli/src/commands/vanity-subdomains/delete/delete.command.ts b/apps/cli/src/commands/vanity-subdomains/delete/delete.command.ts index e777a8c069..cdb209622d 100644 --- a/apps/cli/src/commands/vanity-subdomains/delete/delete.command.ts +++ b/apps/cli/src/commands/vanity-subdomains/delete/delete.command.ts @@ -9,7 +9,7 @@ import { projectTargetFlags } from "../../../command-internal/target/target-flag import { projectRefPicker } from "../../../config/project-ref.layer.ts"; import { linkedProjectCache } from "../../../telemetry/linked-project-cache.layer.ts"; import { withJsonErrorHandling } from "../../../shared/output/json-error-handling.ts"; -import { requireExperimental } from "../../../command-internal/experimental-gate.ts"; +import { requiredExperimentalAccess } from "../../../command-internal/experimental-gate.ts"; import { RESOURCE_OUTPUT_FORMATS } from "../../../command-internal/output-formats.ts"; import { managementApiRuntimeLayer } from "../../../command-internal/management-api-runtime.layer.ts"; import { @@ -49,12 +49,13 @@ export const vanitySubdomainsDeleteCommand = Command.make("delete", config).pipe // inline after the experimental gate rather than via `Command.provide` on the // whole command — `Command.provide` would build the layer, and fail on a missing // token, before the gate ever runs. - yield* requireExperimental; + yield* requiredExperimentalAccess.check; return yield* vanitySubdomainsDelete(flags).pipe( withCommandTelemetry({ flags }), Effect.provide(managementApiRuntimeLayer(["vanity-subdomains", "delete"])), ); }).pipe(withJsonErrorHandling), ), + requiredExperimentalAccess.annotate, withTargetPolicy({ group: "hosted", consent: "no" }), ); diff --git a/apps/cli/src/commands/vanity-subdomains/get/get.command.ts b/apps/cli/src/commands/vanity-subdomains/get/get.command.ts index 4772f9da26..933b3e4d95 100644 --- a/apps/cli/src/commands/vanity-subdomains/get/get.command.ts +++ b/apps/cli/src/commands/vanity-subdomains/get/get.command.ts @@ -9,7 +9,7 @@ import { projectTargetFlags } from "../../../command-internal/target/target-flag import { projectRefPicker } from "../../../config/project-ref.layer.ts"; import { linkedProjectCache } from "../../../telemetry/linked-project-cache.layer.ts"; import { withJsonErrorHandling } from "../../../shared/output/json-error-handling.ts"; -import { requireExperimental } from "../../../command-internal/experimental-gate.ts"; +import { requiredExperimentalAccess } from "../../../command-internal/experimental-gate.ts"; import { RESOURCE_OUTPUT_FORMATS } from "../../../command-internal/output-formats.ts"; import { managementApiRuntimeLayer } from "../../../command-internal/management-api-runtime.layer.ts"; import { @@ -47,12 +47,13 @@ export const vanitySubdomainsGetCommand = Command.make("get", config).pipe( // inline after the experimental gate rather than via `Command.provide` on the // whole command — `Command.provide` would build the layer, and fail on a missing // token, before the gate ever runs. - yield* requireExperimental; + yield* requiredExperimentalAccess.check; return yield* vanitySubdomainsGet(flags).pipe( withCommandTelemetry({ flags }), Effect.provide(managementApiRuntimeLayer(["vanity-subdomains", "get"])), ); }).pipe(withJsonErrorHandling), ), + requiredExperimentalAccess.annotate, withTargetPolicy({ group: "hosted", consent: "none" }), ); diff --git a/apps/cli/src/docs/docs-spec.tables.ts b/apps/cli/src/docs/docs-spec.tables.ts index 905ca8f7d3..2070ff94af 100644 --- a/apps/cli/src/docs/docs-spec.tables.ts +++ b/apps/cli/src/docs/docs-spec.tables.ts @@ -2,8 +2,8 @@ import type { DocsFlag } from "./docs-spec.ts"; import { genTypesLanguageFlagDefaults } from "../commands/gen/types/types.languages.ts"; /** - * Static data the Effect command tree cannot express structurally: docs-site section tags, - * `--experimental`-required leaves, deprecated commands, and flag defaults that + * Static data the Effect command tree cannot express structurally: docs-site section tags + * and flag defaults that * `Flag.withDefault` only captures in a closure. `buildDocsSpec` fails the build on stale keys. */ @@ -64,53 +64,6 @@ export const DOCS_TAGS: Readonly>> = { "supabase-whoami": ["management-api"], }; -/** Leaves that require `--experimental`. */ -export const DOCS_EXPERIMENTAL: ReadonlySet = new Set([ - "supabase-network-bans-get", - "supabase-network-bans-remove", - "supabase-network-restrictions-get", - "supabase-network-restrictions-update", - "supabase-postgres-config-delete", - "supabase-postgres-config-get", - "supabase-postgres-config-update", - "supabase-ssl-enforcement-get", - "supabase-ssl-enforcement-update", - "supabase-storage-cp", - "supabase-storage-ls", - "supabase-storage-mv", - "supabase-storage-rm", - "supabase-vanity-subdomains-activate", - "supabase-vanity-subdomains-check-availability", - "supabase-vanity-subdomains-delete", - "supabase-vanity-subdomains-get", -]); - -/** - * Leaves gated on `--experimental` OR `[experimental.pgdelta] enabled` (default true) - * in config.toml — the flag is documented but not marked required, since the gate - * is open unless config sets `enabled = false`. - */ -export const DOCS_EXPERIMENTAL_OPTIONAL: ReadonlySet = new Set([ - "supabase-db-schema-declarative-generate", - "supabase-db-schema-declarative-sync", -]); - -/** - * Deprecated commands: kept visible in `--help` (with a "(deprecated)" - * suffix) but excluded from the published reference. - */ -export const DOCS_EXCLUDED: ReadonlySet = new Set([ - "supabase-inspect-db-cache-hit", - "supabase-inspect-db-index-sizes", - "supabase-inspect-db-index-usage", - "supabase-inspect-db-role-configs", - "supabase-inspect-db-role-connections", - "supabase-inspect-db-seq-scans", - "supabase-inspect-db-table-record-counts", - "supabase-inspect-db-table-sizes", - "supabase-inspect-db-unused-indexes", -]); - /** * Flag defaults that differ from the primitive type's zero value, keyed * `" "` (root global flags use doc id `supabase`). TS-only diff --git a/apps/cli/src/docs/docs-spec.ts b/apps/cli/src/docs/docs-spec.ts index e3b440da07..cf648a72d9 100644 --- a/apps/cli/src/docs/docs-spec.ts +++ b/apps/cli/src/docs/docs-spec.ts @@ -1,3 +1,4 @@ +import { isDeprecated, readExperimentalAccess } from "../command-internal/command-access-policy.ts"; import { hasOptionalSubcommand } from "../shared/output/optional-subcommand-usage.ts"; import { Option } from "effect"; import { stringify } from "yaml"; @@ -16,10 +17,7 @@ import { DOCS_ARG_OVERRIDES, DOCS_CHOICE_OVERRIDES, DOCS_DEFAULT_OVERRIDES, - DOCS_EXCLUDED, DOCS_EXCLUDED_FLAGS, - DOCS_EXPERIMENTAL, - DOCS_EXPERIMENTAL_OPTIONAL, DOCS_EXTRA_FLAGS, DOCS_INFO_DESCRIPTION, DOCS_INFO_TAGS, @@ -264,14 +262,12 @@ function walkDocsCommands( path: ReadonlyArray, inheritedParams: ReadonlyArray, ): void => { - if (DOCS_EXCLUDED.has(path.join("-"))) { + if (isDeprecated(command)) { onExcluded?.(path); return; } const children = docsVisibleChildren(command); - const publishedChildren = children.filter( - (child) => !DOCS_EXCLUDED.has([...path, child.name].join("-")), - ); + const publishedChildren = children.filter((child) => !isDeprecated(child)); onCommand(command, path, inheritedParams, children, publishedChildren); const childInherited = [ ...inheritedParams, @@ -342,12 +338,10 @@ export function buildDocsSpec(input: DocsSpecInput): DocsSpec { const commands: Array = []; const emittedIds = new Set(); - const skippedExcludedIds = new Set(); const seenFlagKeys = new Set(rootFlags.map((flag) => `supabase ${flag.id}`)); const consumedExcludedFlagKeys = new Set(); const consumedArgOverrideIds = new Set(); const consumedExtraFlagIds = new Set(); - const consumedExperimentalIds = new Set(); const consumedOverlayPaths = new Set(); const allowedOrphanOverlayPaths = new Set(); @@ -416,13 +410,9 @@ export function buildDocsSpec(input: DocsSpecInput): DocsSpec { const own = [...declared, ...(extraFlags ?? [])].toSorted((a, b) => docsCompare(a.id, b.id)); own.forEach((flag) => seenFlagKeys.add(`${docId} ${flag.id}`)); flags.push(...own); - if (DOCS_EXPERIMENTAL.has(docId)) { - consumedExperimentalIds.add(docId); - flags.push(experimentalFlag); - } - if (DOCS_EXPERIMENTAL_OPTIONAL.has(docId)) { - consumedExperimentalIds.add(docId); - flags.push(experimentalOptionalFlag); + const experimental = readExperimentalAccess(command); + if (Option.isSome(experimental)) { + flags.push(experimental.value === "required" ? experimentalFlag : experimentalOptionalFlag); } const ownIds = new Set(own.map((flag) => flag.id)); const inherited = flagDocsFor(commandPath, inheritedParams).filter( @@ -485,22 +475,17 @@ export function buildDocsSpec(input: DocsSpecInput): DocsSpec { }; walkDocsCommands(input.root, visit, (path) => { - skippedExcludedIds.add(path.join("-")); allowedOrphanOverlayPaths.add(docsOverlayPath(path)); }); validateDocsTables({ emittedIds, - skippedExcludedIds, seenFlagKeys, consumedExcludedFlagKeys, consumedArgOverrideIds, consumedExtraFlagIds, - consumedExperimentalIds, }); validateDocsContent(input, { - emittedIds, - skippedExcludedIds, consumedOverlayPaths, allowedOrphanOverlayPaths, }); @@ -545,12 +530,10 @@ export function stringifyDocsSpec(spec: DocsSpec): string { */ function validateDocsTables(seen: { readonly emittedIds: ReadonlySet; - readonly skippedExcludedIds: ReadonlySet; readonly seenFlagKeys: ReadonlySet; readonly consumedExcludedFlagKeys: ReadonlySet; readonly consumedArgOverrideIds: ReadonlySet; readonly consumedExtraFlagIds: ReadonlySet; - readonly consumedExperimentalIds: ReadonlySet; }): void { const stale: Array = []; for (const key of Object.keys(DOCS_DEFAULT_OVERRIDES)) { @@ -559,23 +542,12 @@ function validateDocsTables(seen: { for (const id of Object.keys(DOCS_TAGS)) { if (!seen.emittedIds.has(id)) stale.push(`DOCS_TAGS: "${id}"`); } - for (const id of DOCS_EXPERIMENTAL) { - if (!seen.consumedExperimentalIds.has(id)) stale.push(`DOCS_EXPERIMENTAL: "${id}"`); - } - for (const id of DOCS_EXPERIMENTAL_OPTIONAL) { - if (!seen.consumedExperimentalIds.has(id)) { - stale.push(`DOCS_EXPERIMENTAL_OPTIONAL: "${id}"`); - } - } for (const key of Object.keys(DOCS_CHOICE_OVERRIDES)) { if (!seen.seenFlagKeys.has(key)) stale.push(`DOCS_CHOICE_OVERRIDES: "${key}"`); } for (const id of Object.keys(DOCS_EXTRA_FLAGS)) { if (!seen.consumedExtraFlagIds.has(id)) stale.push(`DOCS_EXTRA_FLAGS: "${id}"`); } - for (const id of DOCS_EXCLUDED) { - if (!seen.skippedExcludedIds.has(id)) stale.push(`DOCS_EXCLUDED: "${id}"`); - } for (const key of DOCS_REQUIRED) { if (!seen.seenFlagKeys.has(key)) stale.push(`DOCS_REQUIRED: "${key}"`); } @@ -593,14 +565,12 @@ function validateDocsTables(seen: { } /** - * Rejects overlays matching no emitted command, except pages belonging to `DOCS_EXCLUDED` + * Rejects overlays matching no emitted command, except pages belonging to deprecated * commands, which remain allowed until their pages are removed. */ function validateDocsContent( input: DocsSpecInput, seen: { - readonly emittedIds: ReadonlySet; - readonly skippedExcludedIds: ReadonlySet; readonly consumedOverlayPaths: ReadonlySet; readonly allowedOrphanOverlayPaths: ReadonlySet; }, diff --git a/apps/cli/src/docs/docs-spec.unit.test.ts b/apps/cli/src/docs/docs-spec.unit.test.ts index edc43983c6..4b7d6b9b20 100644 --- a/apps/cli/src/docs/docs-spec.unit.test.ts +++ b/apps/cli/src/docs/docs-spec.unit.test.ts @@ -2,7 +2,6 @@ import { BunServices } from "@effect/platform-bun"; import { beforeAll, describe, expect, it } from "@effect/vitest"; import { Effect, FileSystem, Path } from "effect"; import { Command, Flag } from "effect/cli"; -import type { PlatformError } from "effect/PlatformError"; import { ExperimentalFlag } from "../command-internal/global-flags.ts"; import { hostedRemoteFlag, remoteFlag } from "../../tests/helpers/remote-flag-fixture.ts"; @@ -17,7 +16,6 @@ import { stringifyDocsSpec, } from "./docs-spec.ts"; import type { DocsCommand } from "./docs-spec.ts"; -import { DOCS_EXCLUDED, DOCS_EXPERIMENTAL } from "./docs-spec.tables.ts"; interface BuiltSpecFixture { readonly content: DocsContent; @@ -179,7 +177,17 @@ describe("buildDocsSpec", () => { it("excludes deprecated commands from the spec and from subcommand lists", () => { const { byId } = builtSpec(); - for (const excluded of DOCS_EXCLUDED) { + for (const excluded of [ + "supabase-inspect-db-cache-hit", + "supabase-inspect-db-index-sizes", + "supabase-inspect-db-index-usage", + "supabase-inspect-db-role-configs", + "supabase-inspect-db-role-connections", + "supabase-inspect-db-seq-scans", + "supabase-inspect-db-table-record-counts", + "supabase-inspect-db-table-sizes", + "supabase-inspect-db-unused-indexes", + ]) { expect(byId.has(excluded)).toBe(false); } expect(byId.get("supabase-gen")?.subcommands).not.toContain("supabase-gen-keys"); @@ -229,8 +237,33 @@ describe("buildDocsSpec", () => { it("injects the required --experimental flag into experimental leaves only", () => { const { byId } = builtSpec(); - const storageLs = byId.get("supabase-storage-ls"); - const experimental = storageLs?.flags.find((flag) => flag.id === "experimental"); + const requiredCommands = [ + "network-bans-get", + "network-bans-remove", + "network-restrictions-get", + "network-restrictions-update", + "postgres-config-delete", + "postgres-config-get", + "postgres-config-update", + "ssl-enforcement-get", + "ssl-enforcement-update", + "storage-cp", + "storage-ls", + "storage-mv", + "storage-rm", + "vanity-subdomains-activate", + "vanity-subdomains-check-availability", + "vanity-subdomains-delete", + "vanity-subdomains-get", + ]; + for (const command of requiredCommands) { + expect( + byId.get(`supabase-${command}`)?.flags.find((flag) => flag.id === "experimental"), + ).toMatchObject({ required: true, default_value: "false" }); + } + const experimental = byId + .get("supabase-storage-ls") + ?.flags.find((flag) => flag.id === "experimental"); expect(experimental).toMatchObject({ required: true, default_value: "false" }); expect(Object.keys(experimental ?? {})).toEqual([ "id", @@ -242,11 +275,16 @@ describe("buildDocsSpec", () => { expect(byId.get("supabase-db-push")?.flags.some((flag) => flag.id === "experimental")).toBe( false, ); - const declarativeSync = byId - .get("supabase-db-schema-declarative-sync") - ?.flags.find((flag) => flag.id === "experimental"); - expect(declarativeSync).toBeDefined(); - expect(declarativeSync?.required).toBeUndefined(); + for (const leaf of ["generate", "sync"]) { + const experimental = byId + .get(`supabase-db-schema-declarative-${leaf}`) + ?.flags.find((flag) => flag.id === "experimental"); + expect(experimental).toMatchObject({ default_value: "false" }); + expect(experimental?.required).toBeUndefined(); + } + expect( + byId.get("supabase-projects-create")?.flags.some((flag) => flag.id === "experimental"), + ).toBe(false); }); it("emits enum flags with accepted_values and defaults", () => { @@ -448,7 +486,7 @@ describe("build guards fail loudly", () => { Command.withGlobalFlags([ExperimentalFlag]), ); expect(() => buildDocsSpec({ root, ...emptyInput })).toThrow( - /stale static-table entries[^]*DOCS_EXPERIMENTAL[^]*DOCS_EXTRA_FLAGS/, + /stale static-table entries[^]*DOCS_EXTRA_FLAGS/, ); }); @@ -495,38 +533,3 @@ describe("readDocsContent walk", () => { }).pipe(Effect.scoped, Effect.provide(BunServices.layer)), ); }); - -describe("DOCS_EXPERIMENTAL mirrors the runtime gate", () => { - it.effect("matches the requireExperimental call sites exactly", () => - Effect.gen(function* () { - const fs = yield* FileSystem.FileSystem; - const path = yield* Path.Path; - const commandsDir = path.resolve(import.meta.dirname, "../commands"); - const gated = new Set(); - const isSymlinkOrDenied = (entryPath: string) => - fs.readLink(entryPath).pipe( - Effect.catchReason("PlatformError", "PermissionDenied", () => Effect.void), - Effect.isSuccess, - ); - const walk = (dir: string): Effect.Effect => - Effect.gen(function* () { - for (const name of yield* fs.readDirectory(dir)) { - const entryPath = path.join(dir, name); - if ( - !(yield* isSymlinkOrDenied(entryPath)) && - (yield* fs.stat(entryPath)).type === "Directory" - ) - yield* walk(entryPath); - else if (name.endsWith(".command.ts")) { - if ((yield* fs.readFileString(entryPath)).includes("yield* requireExperimental")) { - const relative = path.relative(commandsDir, path.dirname(entryPath)); - gated.add(`supabase-${relative.split(path.sep).join("-")}`); - } - } - } - }); - yield* walk(commandsDir); - expect([...gated].sort()).toEqual([...DOCS_EXPERIMENTAL].sort()); - }).pipe(Effect.provide(BunServices.layer)), - ); -}); diff --git a/apps/cli/src/shared/output/json-formatter.ts b/apps/cli/src/shared/output/json-formatter.ts index d28ea05044..6f427c6f5f 100644 --- a/apps/cli/src/shared/output/json-formatter.ts +++ b/apps/cli/src/shared/output/json-formatter.ts @@ -1,4 +1,5 @@ import type { CliOutput, HelpDoc } from "effect/cli"; +import { withDeprecatedDescriptions } from "./subcommand-help.ts"; import { withOptionalSubcommandUsage } from "./optional-subcommand-usage.ts"; import { permissionSectionForHelp } from "../../command-internal/command-permissions/help-section.ts"; import type { CliErrorSuggestionContext } from "../cli/subcommand-flag-suggestions.ts"; @@ -12,7 +13,7 @@ export function jsonCliOutputFormatter(context?: CliErrorSuggestionContext): Cli const target = targetHelpFor(doc); const permissions = permissionSectionForHelp(doc); const { annotations: _annotations, ...serializable } = withOptionalSubcommandUsage( - withRemoteFlagValue(doc), + withRemoteFlagValue(withDeprecatedDescriptions(doc, context?.rootCommand)), ); return JSON.stringify({ _tag: "Help", diff --git a/apps/cli/src/shared/output/subcommand-help.ts b/apps/cli/src/shared/output/subcommand-help.ts new file mode 100644 index 0000000000..5709acfd21 --- /dev/null +++ b/apps/cli/src/shared/output/subcommand-help.ts @@ -0,0 +1,46 @@ +import { Array as Arr } from "effect"; +import type { Command, HelpDoc } from "effect/cli"; +import { deprecatedShortDescription } from "../../command-internal/command-access-policy.ts"; + +/** The usage starts with the command path, root first, followed by placeholders. */ +export function commandForDoc( + root: Command.Command.Any, + doc: HelpDoc.HelpDoc, +): Command.Command.Any | undefined { + let current = root; + for (const token of doc.usage.split(" ").slice(1)) { + if (token.startsWith("<") || token.startsWith("[")) break; + const next = current.subcommands + .flatMap((group) => group.commands) + .find((command) => command.name === token || command.alias === token); + if (next === undefined) return undefined; + current = next; + } + return current; +} + +/** Effect omits child annotations from help rows, so resolve their labels from the command tree. */ +export function withDeprecatedDescriptions( + doc: HelpDoc.HelpDoc, + root: Command.Command.Any | undefined, +): HelpDoc.HelpDoc { + if (!root || !doc.subcommands) return doc; + const parent = commandForDoc(root, doc); + if (!parent) return doc; + const labels = new Map(); + for (const child of parent.subcommands.flatMap((group) => group.commands)) { + const label = deprecatedShortDescription(child); + if (label !== undefined) labels.set(child.name, label); + } + if (!labels.size) return doc; + return { + ...doc, + subcommands: doc.subcommands.map((group) => ({ + ...group, + commands: Arr.map(group.commands, (row) => { + const shortDescription = labels.get(row.name); + return shortDescription === undefined ? row : { ...row, shortDescription }; + }), + })), + }; +} diff --git a/apps/cli/src/shared/output/target-help.ts b/apps/cli/src/shared/output/target-help.ts index 938e6d1276..f30ba18918 100644 --- a/apps/cli/src/shared/output/target-help.ts +++ b/apps/cli/src/shared/output/target-help.ts @@ -1,5 +1,6 @@ import { Array as Arr, Context, Option } from "effect"; import type { Command, HelpDoc } from "effect/cli"; +import { commandForDoc } from "./subcommand-help.ts"; import { REMOTE_FLAG_NAME } from "../../command-internal/target/remote-vocabulary.ts"; import { TargetPolicyAnnotation } from "../../command-internal/target/target-policy.ts"; @@ -92,34 +93,6 @@ export function withRemoteFlagValue(doc: HelpDoc.HelpDoc): HelpDoc.HelpDoc { })); } -function findCommand( - root: Command.Command.Any, - path: ReadonlyArray, -): Command.Command.Any | undefined { - let current = root; - for (const segment of path) { - const next = current.subcommands - .flatMap((group) => group.commands) - .find((command) => command.name === segment || command.alias === segment); - if (next === undefined) return undefined; - current = next; - } - return current; -} - -/** The command a help doc describes: its usage line starts with the command path, root first. */ -function commandForDoc( - root: Command.Command.Any, - doc: HelpDoc.HelpDoc, -): Command.Command.Any | undefined { - const path: Array = []; - for (const token of doc.usage.split(" ")) { - if (token.startsWith("<") || token.startsWith("[")) break; - path.push(token); - } - return findCommand(root, path.slice(1)); -} - /** Scope label per subcommand row of a group's help, keyed by subcommand name. */ export function subcommandScopes( doc: HelpDoc.HelpDoc, diff --git a/apps/cli/src/shared/output/text-formatter.ts b/apps/cli/src/shared/output/text-formatter.ts index e3527a0da6..945b6a7efb 100644 --- a/apps/cli/src/shared/output/text-formatter.ts +++ b/apps/cli/src/shared/output/text-formatter.ts @@ -1,4 +1,5 @@ import { CliOutput } from "effect/cli"; +import { withDeprecatedDescriptions } from "./subcommand-help.ts"; import { withOptionalSubcommandUsage } from "./optional-subcommand-usage.ts"; import { permissionSectionForHelp, @@ -29,9 +30,10 @@ export function textCliOutputFormatter(context?: CliErrorSuggestionContext): Cli return { ...base, formatHelpDoc: (doc) => { + const labeled = withDeprecatedDescriptions(doc, context?.rootCommand); const text = base.formatHelpDoc( withOptionalSubcommandUsage( - withRemoteFlagUsage(labelSubcommands(doc, context?.rootCommand)), + withRemoteFlagUsage(labelSubcommands(labeled, context?.rootCommand)), ), ); const target = targetHelpFor(doc); From 9e6c1fe5f08af6c5ed5d20939fd44ebe23c2c084 Mon Sep 17 00:00:00 2001 From: Mike Donnalley Date: Wed, 18 Nov 2026 13:14:46 -0700 Subject: [PATCH 2/3] test(cli): check experimental policy pairing --- .../experimental-pairing.unit.test.ts | 120 ++++++++++++++++++ 1 file changed, 120 insertions(+) create mode 100644 apps/cli/src/command-internal/experimental-pairing.unit.test.ts diff --git a/apps/cli/src/command-internal/experimental-pairing.unit.test.ts b/apps/cli/src/command-internal/experimental-pairing.unit.test.ts new file mode 100644 index 0000000000..9590d54202 --- /dev/null +++ b/apps/cli/src/command-internal/experimental-pairing.unit.test.ts @@ -0,0 +1,120 @@ +import { expect, it } from "@effect/vitest"; +import { Effect } from "effect"; +import { fileURLToPath } from "node:url"; +import * as ts from "typescript/unstable/ast"; +import { API, type Checker, SymbolFlags } from "typescript/unstable/async"; + +function* nodes(root: ts.Node): Generator { + yield root; + const children: ts.Node[] = []; + root.forEachChild((child) => { + children.push(child); + }); + for (const child of children) yield* nodes(child); +} + +const declaration = Effect.fnUntraced(function* (checker: Checker, ref: ts.Node) { + const symbol = yield* Effect.promise(() => checker.getSymbolAtLocation(ref)); + if (!symbol) return undefined; + const target = + symbol.flags & SymbolFlags.Alias + ? yield* Effect.promise(() => checker.getAliasedSymbol(symbol)) + : symbol; + const handle = target.valueDeclaration; + return handle && (yield* Effect.promise(() => handle.resolve())); +}); + +const policy = Effect.fnUntraced(function* (checker: Checker, member: ts.PropertyAccessExpression) { + const decl = yield* declaration(checker, member.expression); + if ( + decl && + ts.isVariableDeclaration(decl) && + decl.initializer && + ts.isCallExpression(decl.initializer) && + decl.initializer.expression.getText() === "defineExperimentalAccess" + ) { + return `${decl.getSourceFile().fileName.split("/src/").pop()}:${decl.name.getText()}`; + } + return undefined; +}); + +function checksIn( + handler: ts.Node, + checker: Checker, + checks: Set, + followHandler: boolean, +): Effect.Effect { + return Effect.gen(function* () { + for (const node of nodes(handler)) { + if (ts.isYieldExpression(node) && node.asteriskToken && node.expression) { + const member = ts.isCallExpression(node.expression) + ? node.expression.expression + : node.expression; + if (ts.isPropertyAccessExpression(member) && member.name.getText() === "check") { + const key = yield* policy(checker, member); + if (key) checks.add(key); + } + } + if (followHandler && ts.isCallExpression(node) && ts.isIdentifier(node.expression)) { + const decl = yield* declaration(checker, node.expression); + if (decl?.getSourceFile().fileName.endsWith(".handler.ts")) + yield* checksIn(decl, checker, checks, false); + } + } + }); +} + +it.effect( + "pairs each command's experimental annotations with checks in its own handler", + Effect.fn("ExperimentalAccess.inspectPairing")(function* () { + const config = fileURLToPath(new URL("../../tsconfig.json", import.meta.url)); + const api = yield* Effect.acquireRelease( + Effect.sync(() => new API()), + (api) => Effect.promise(() => api.close()), + ); + const snapshot = yield* Effect.promise(() => api.updateSnapshot({ openProjects: [config] })); + const project = snapshot.getProject(config)!; + const files = project.rootFiles.filter((file) => file.endsWith(".command.ts")); + expect(files.length).toBeGreaterThan(0); + const failures: string[] = []; + const recognizedPolicies = new Set(); + for (const file of files) { + const source = (yield* Effect.promise(() => project.program.getSourceFile(file)))!; + for (const pipe of nodes(source)) { + if ( + !ts.isCallExpression(pipe) || + !ts.isPropertyAccessExpression(pipe.expression) || + pipe.expression.name.getText() !== "pipe" + ) + continue; + const annotated = new Set(); + const checked = new Set(); + for (const arg of pipe.arguments) { + if (ts.isPropertyAccessExpression(arg) && arg.name.getText() === "annotate") { + const key = yield* policy(project.checker, arg); + if (key) annotated.add(key); + } + if ( + ts.isCallExpression(arg) && + arg.expression.getText() === "Command.withHandler" && + arg.arguments[0] + ) { + yield* checksIn(arg.arguments[0], project.checker, checked, true); + } + } + for (const key of new Set([...annotated, ...checked])) { + recognizedPolicies.add(key); + if (annotated.has(key) !== checked.has(key)) + failures.push( + `${file}: missing ${annotated.has(key) ? "check" : "annotation"} for ${key}`, + ); + } + } + } + expect(failures).toEqual([]); + expect( + recognizedPolicies.size, + "Recognized experimental policies in the command scan", + ).toBeGreaterThan(0); + }), +); From c77c5b2422a6d13cc03d4bd3203b2ad5bc8042f2 Mon Sep 17 00:00:00 2001 From: Mike Donnalley Date: Wed, 18 Nov 2026 14:56:21 -0700 Subject: [PATCH 3/3] test(cli): mark docs validation fixture command as deprecated --- apps/cli/scripts/docs-spec-validation.unit.test.ts | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/apps/cli/scripts/docs-spec-validation.unit.test.ts b/apps/cli/scripts/docs-spec-validation.unit.test.ts index 9481efe512..e852a3d1bd 100644 --- a/apps/cli/scripts/docs-spec-validation.unit.test.ts +++ b/apps/cli/scripts/docs-spec-validation.unit.test.ts @@ -2,6 +2,7 @@ import { expect, it } from "@effect/vitest"; import { Effect } from "effect"; import { Command } from "effect/cli"; import { stringify } from "yaml"; +import { withDeprecated } from "../src/command-internal/command-access-policy.ts"; import { validateDocsSpec } from "./docs-spec-validation.ts"; const root = Command.make("supabase").pipe( @@ -57,7 +58,9 @@ const inspectRoot = Command.make("supabase").pipe( Command.withSubcommands([ Command.make("inspect").pipe( Command.withSubcommands([ - Command.make("db").pipe(Command.withSubcommands([Command.make("cache-hit")])), + Command.make("db").pipe( + Command.withSubcommands([Command.make("cache-hit").pipe(withDeprecated)]), + ), ]), ), ]),