improvement(feature-flags): single FEATURE_FLAGS registry — each entry defines name, description, and fallback in one place

Author: TheodoreSpeaks

.claude/commands/add-feature-flag.md

@@ -31,15 +31,18 @@ Critically, **none of this is expressible in code** — gating (especially `admi
 
 ## Steps
 
-1. **Register the flag.** Add an entry to `FEATURE_FLAG_FALLBACKS` in `apps/sim/lib/core/config/feature-flags.ts`, mapping the flag name (kebab-case) to the secret consulted when AppConfig isn't the source of truth. A truthy secret turns the flag on globally:
+1. **Define the flag.** Add one entry to the `FEATURE_FLAGS` registry in `apps/sim/lib/core/config/feature-flags.ts`. Each entry is the flag's whole definition — name (kebab-case key), `description`, and the `fallback` secret consulted when AppConfig isn't the source of truth (truthy ⇒ on globally):
 
    ```ts
-   const FEATURE_FLAG_FALLBACKS = {
-     '<flag-name>': () => env.<FLAG_SECRET>,
+   const FEATURE_FLAGS = {
+     '<flag-name>': {
+       description: '<what this gates>',
+       fallback: () => env.<FLAG_SECRET>,
+     },
    }
    ```
 
-   Add `<FLAG_SECRET>` to `apps/sim/lib/core/config/env.ts` (and the deployment's secret store). Do **not** add any org/user/admin defaults here — that gating exists only in AppConfig.
+   Add `<FLAG_SECRET>` to `apps/sim/lib/core/config/env.ts` (and the deployment's secret store). Do **not** add org/user/admin defaults here — that gating exists only in AppConfig. Adding the entry makes `<flag-name>` a valid `FeatureFlagName`.
 
 2. **Gate the call site.** Call `isFeatureEnabled` with whatever ids you have — admin status is resolved internally, so callers never pass it:
 
@@ -59,7 +62,7 @@ Critically, **none of this is expressible in code** — gating (especially `admi
 
 4. **Test.** Add a case to `apps/sim/lib/core/config/feature-flags.test.ts`: use `withAppConfig({ flags: { ... } })` to cover the gating rule (mock `isPlatformAdmin` for the `admins` clause), and toggle the fallback secret to cover the off-AppConfig path.
 
-5. **Clean up after rollout.** When the feature ships to everyone, delete the flag from `FEATURE_FLAG_FALLBACKS`, the `<FLAG_SECRET>` env entry, the AppConfig document, the call sites, and the test. Leaving dead flags around is the main failure mode of flag systems.
+5. **Clean up after rollout.** When the feature ships to everyone, delete the flag's entry from `FEATURE_FLAGS`, the `<FLAG_SECRET>` env entry, the AppConfig document, the call sites, and the test. Leaving dead flags around is the main failure mode of flag systems.
 
 ## Notes
 

.cursor/commands/add-feature-flag.md

@@ -26,15 +26,18 @@ Critically, **none of this is expressible in code** — gating (especially `admi
 
 ## Steps
 
-1. **Register the flag.** Add an entry to `FEATURE_FLAG_FALLBACKS` in `apps/sim/lib/core/config/feature-flags.ts`, mapping the flag name (kebab-case) to the secret consulted when AppConfig isn't the source of truth. A truthy secret turns the flag on globally:
+1. **Define the flag.** Add one entry to the `FEATURE_FLAGS` registry in `apps/sim/lib/core/config/feature-flags.ts`. Each entry is the flag's whole definition — name (kebab-case key), `description`, and the `fallback` secret consulted when AppConfig isn't the source of truth (truthy ⇒ on globally):
 
    ```ts
-   const FEATURE_FLAG_FALLBACKS = {
-     '<flag-name>': () => env.<FLAG_SECRET>,
+   const FEATURE_FLAGS = {
+     '<flag-name>': {
+       description: '<what this gates>',
+       fallback: () => env.<FLAG_SECRET>,
+     },
    }
    ```
 
-   Add `<FLAG_SECRET>` to `apps/sim/lib/core/config/env.ts` (and the deployment's secret store). Do **not** add any org/user/admin defaults here — that gating exists only in AppConfig.
+   Add `<FLAG_SECRET>` to `apps/sim/lib/core/config/env.ts` (and the deployment's secret store). Do **not** add org/user/admin defaults here — that gating exists only in AppConfig. Adding the entry makes `<flag-name>` a valid `FeatureFlagName`.
 
 2. **Gate the call site.** Call `isFeatureEnabled` with whatever ids you have — admin status is resolved internally, so callers never pass it:
 
@@ -54,7 +57,7 @@ Critically, **none of this is expressible in code** — gating (especially `admi
 
 4. **Test.** Add a case to `apps/sim/lib/core/config/feature-flags.test.ts`: use `withAppConfig({ flags: { ... } })` to cover the gating rule (mock `isPlatformAdmin` for the `admins` clause), and toggle the fallback secret to cover the off-AppConfig path.
 
-5. **Clean up after rollout.** When the feature ships to everyone, delete the flag from `FEATURE_FLAG_FALLBACKS`, the `<FLAG_SECRET>` env entry, the AppConfig document, the call sites, and the test. Leaving dead flags around is the main failure mode of flag systems.
+5. **Clean up after rollout.** When the feature ships to everyone, delete the flag's entry from `FEATURE_FLAGS`, the `<FLAG_SECRET>` env entry, the AppConfig document, the call sites, and the test. Leaving dead flags around is the main failure mode of flag systems.
 
 ## Notes
 

apps/sim/lib/core/config/feature-flags.ts

@@ -46,25 +46,42 @@ export interface FeatureFlagContext {
  * admin access from a code literal. To add a flag, register its name and the secret
  * to fall back on.
  */
-type FallbackSecret = () => string | boolean | number | undefined
+/**
+ * The single definition of a feature flag. Everything about a flag lives in one
+ * place: its name (the registry key), a human-readable `description`, and the
+ * `fallback` secret consulted when AppConfig isn't the source of truth (truthy ⇒ on
+ * globally).
+ *
+ * Gating by org/user/admin is deliberately NOT part of a definition — it lives only
+ * in the hosted AppConfig document, so no environment can grant access from a code
+ * literal.
+ */
+interface FeatureFlagDefinition {
+  description: string
+  fallback: () => string | boolean | number | undefined
+}
 
-const FEATURE_FLAG_FALLBACKS = {
-  // 'new-canvas': () => env.NEW_CANVAS_ENABLED,
-} satisfies Record<string, FallbackSecret>
+/** The single registry of known flags. To add a flag, add one entry here. */
+const FEATURE_FLAGS = {
+  // 'new-canvas': {
+  //   description: 'New canvas renderer',
+  //   fallback: () => env.NEW_CANVAS_ENABLED,
+  // },
+} satisfies Record<string, FeatureFlagDefinition>
 
 /**
- * The closed set of known feature flags. Derived from the fallback registry, so a
- * flag cannot exist — or be checked — without a mandatory fallback secret.
+ * The closed set of known feature flags. Derived from the registry, so a flag
+ * cannot exist — or be checked — without a definition (and its mandatory fallback).
  */
-export type FeatureFlagName = keyof typeof FEATURE_FLAG_FALLBACKS
+export type FeatureFlagName = keyof typeof FEATURE_FLAGS
 
 /** Build the fallback document from each flag's secret. Truthy secret ⇒ enabled. */
 function fallbackFlags(): FeatureFlagsConfig {
   const flags: Record<string, FeatureFlagRule> = {}
-  for (const [name, readSecret] of Object.entries(FEATURE_FLAG_FALLBACKS) as Array<
-    [string, FallbackSecret]
+  for (const [name, def] of Object.entries(FEATURE_FLAGS) as Array<
+    [string, FeatureFlagDefinition]
   >) {
-    flags[name] = { enabled: isTruthy(readSecret()) }
+    flags[name] = { enabled: isTruthy(def.fallback()) }
   }
   return { flags }
 }