Migrate DIY Feature Flags

You are working in REPLACE_WITH_REPOSITORY.

Your task is to migrate this application's DIY feature flags toward GrowthBook
through an inventory, typed provider boundary, and shadow comparison without
changing production behavior or deleting the legacy fallback.

Read REPLACE_WITH_GUIDE_URL in full before editing. Also read the repository's
local agent instructions. Treat the operator's instructions, repository truth,
and current official product/framework documentation as authoritative when they
conflict with the guide. Revalidate the guide's tested versions and volatile
surfaces before copying an executable step.

Inventory every current flag source and preserve its actual semantics. Do not
reclassify authorization, entitlement, secrets, or permanent configuration as
ordinary flags. Adapt the reference implementation to the repository; do not
invent cohort behavior or silently accept mismatches. Complete phase 0 and the
safe, non-production parts of phase 1. Do not serve GrowthBook decisions in
production, stop legacy mutations, delete fallback reads or data, or make another
external write unless I explicitly authorize that exact action.

Return: your fit or reject decision; inventory and classification; assumptions;
files changed; commands and tests run; parity, mismatch, serving-mode, failure,
and rollback receipts; deviations from the guide; and the remaining cutover and
cleanup steps. If you cannot fetch the guide URL, stop and ask me for its Markdown
version. Do not proceed from the TL;DR alone.

scripts/
  inventory-feature-flags.mjs
src/
  feature-flags/
    app-features.ts
    context.ts
    provider.ts
    legacy-loader.ts
    legacy-provider.ts
    feature-refresh.ts
    growthbook-provider.ts
    decision-telemetry.ts
    migrating-provider.ts
    bootstrap.ts
tests/
  feature-flags/
    growthbook-provider.test.ts
    migrating-provider.test.ts
    parity-contract.test.ts
.github/
  workflows/
    feature-flag-contract.yml

const checkoutV2 = process.env.FEATURE_CHECKOUT_V2 === "true";

git status --short
git rev-parse HEAD
git grep -n -E 'FEATURE_|FLAG_|feature[_-]?flag|isFeatureEnabled|rollout|kill[_-]?switch'

rg -n --hidden \
  --glob '!node_modules/**' \
  --glob '!dist/**' \
  --glob '!build/**' \
  --glob '!.git/**' \
  '(FEATURE_|FLAG_|FF_|KILL_SWITCH|ENABLE_[A-Z0-9_]+)'

rg -n --hidden \
  --glob '!node_modules/**' \
  --glob '!dist/**' \
  --glob '!build/**' \
  --glob '!.git/**' \
  '(isFeatureEnabled|featureFlags?|flagProvider|percentageRollout|rolloutPercent|variant|treatment)'

rg -n --hidden \
  --glob '*.{ts,tsx,js,jsx,json,yaml,yml,toml,env,sql}' \
  '(process\.env\.|import\.meta\.env\.|getenv\(|config\.(get|has)\(|SELECT.+feature|feature_flags)'

rg -n --hidden \
  --glob '*.{yaml,yml,json,toml,tf,tfvars,Dockerfile}' \
  '(FEATURE_|FLAG_|ENABLE_|KILL_SWITCH|feature.flag)'

import { readdir, readFile, stat } from "node:fs/promises";
import { relative, resolve } from "node:path";

const root = resolve(process.argv[2] ?? process.cwd());
const ignoredDirectories = new Set([
  ".git",
  ".next",
  "build",
  "coverage",
  "dist",
  "node_modules",
  "vendor",
]);

const allowedExtensions = new Set([
  ".cjs",
  ".env",
  ".js",
  ".json",
  ".jsx",
  ".mjs",
  ".sql",
  ".tf",
  ".toml",
  ".ts",
  ".tsx",
  ".yaml",
  ".yml",
]);

const patterns = [
  ["environment-key", /\b(?:FEATURE|FLAG|FF|ENABLE|KILL_SWITCH)_[A-Z0-9_]+\b/g],
  ["environment-read", /\b(?:process\.env|import\.meta\.env)\.[A-Z0-9_]+\b/g],
  [
    "flag-api",
    /\b(?:isFeatureEnabled|featureFlags?|flagProvider|getFeatureValue|evalFeature)\b/g,
  ],
  [
    "rollout",
    /\b(?:percentageRollout|rolloutPercent|hashAttribute|variation|treatment)\b/g,
  ],
  ["flag-table", /\b(?:feature_flags?|flag_overrides?|account_flags?)\b/gi],
];

function extension(path) {
  const name = path.split(/[\\/]/).at(-1) ?? "";
  if (name.startsWith(".env")) return ".env";
  const dot = name.lastIndexOf(".");
  return dot === -1 ? "" : name.slice(dot).toLowerCase();
}

async function* walk(directory) {
  for (const entry of await readdir(directory, { withFileTypes: true })) {
    if (entry.isDirectory() && ignoredDirectories.has(entry.name)) continue;
    const path = resolve(directory, entry.name);
    if (entry.isDirectory()) {
      yield* walk(path);
      continue;
    }
    if (!entry.isFile() || !allowedExtensions.has(extension(path))) continue;
    const details = await stat(path);
    if (details.size > 2_000_000) continue;
    yield path;
  }
}

for await (const path of walk(root)) {
  const lines = (await readFile(path, "utf8")).split(/\r?\n/);
  for (let index = 0; index < lines.length; index += 1) {
    for (const [kind, pattern] of patterns) {
      pattern.lastIndex = 0;
      const matches = [...lines[index].matchAll(pattern)].map(
        (match) => match[0],
      );
      if (matches.length === 0) continue;
      process.stdout.write(
        `${JSON.stringify({
          kind,
          path: relative(root, path).replaceAll("\\", "/"),
          line: index + 1,
          matches: [...new Set(matches)],
          preview: lines[index].trim().slice(0, 240),
        })}\n`,
      );
    }
  }
}

node scripts/inventory-feature-flags.mjs . > feature-flag-inventory.jsonl
wc -l feature-flag-inventory.jsonl

47 feature-flag-inventory.jsonl

SELECT
  flag_key,
  value_type,
  default_value,
  environment,
  rollout_percent,
  updated_at,
  updated_by
FROM feature_flags
ORDER BY flag_key, environment;

SELECT
  flag_key,
  scope_type,
  COUNT(*) AS override_count,
  MIN(updated_at) AS oldest_update,
  MAX(updated_at) AS newest_update
FROM feature_flag_overrides
GROUP BY flag_key, scope_type
ORDER BY flag_key, scope_type;

- legacy_key: FEATURE_CHECKOUT_V2
  growthbook_key: checkout-v2
  class: release
  owner: checkout-team
  source: environment
  value_type: boolean
  code_fallback: false
  legacy_default: false
  environments: [dev, staging, production]
  hash_attribute: null
  update_latency: deployment
  risk: high
  migration_state: inventory
  removal_condition: 100-percent-on-for-14-days-and-no-control-code-needed

- legacy_key: invoice_preview_rollout
  growthbook_key: invoice-preview
  class: release
  owner: billing-team
  source: database
  value_type: boolean
  code_fallback: false
  legacy_default: false
  environments: [staging, production]
  hash_attribute: account_id
  update_latency: 60-second-cache
  risk: medium
  migration_state: inventory
  removal_condition: rollout-complete-and-legacy-overrides-empty

export function parseBoolean(name: string, raw: string | undefined): boolean {
  if (raw === undefined) return false;
  if (raw === "true") return true;
  if (raw === "false") return false;
  throw new Error(`${name} must be exactly "true" or "false"`);
}

npm install @growthbook/growthbook@1.7.0
npm install --save-dev typescript@5.7.3 jest@29.7.0 ts-jest@29.4.11 @types/jest@29.5.14

export interface RecommendationConfig {
  algorithm: "baseline" | "hybrid-v2";
  maxItems: number;
}

export interface AppFeatures {
  "checkout-v2": boolean;
  "invoice-preview": boolean;
  "search-page-size": number;
  "recommendation-config": RecommendationConfig;
}

export type FeatureKey = keyof AppFeatures & string;

export const CODE_FALLBACKS = {
  "checkout-v2": false,
  "invoice-preview": false,
  "search-page-size": 25,
  "recommendation-config": {
    algorithm: "baseline",
    maxItems: 10,
  },
} satisfies { [K in FeatureKey]: AppFeatures[K] };

export const FEATURE_KEYS = Object.freeze(
  Object.keys(CODE_FALLBACKS) as FeatureKey[],
);

const FEATURE_VALIDATORS: {
  [K in FeatureKey]: (value: unknown) => value is AppFeatures[K];
} = {
  "checkout-v2": (value): value is boolean => typeof value === "boolean",
  "invoice-preview": (value): value is boolean => typeof value === "boolean",
  "search-page-size": (value): value is number =>
    value === 25 || value === 50 || value === 100,
  "recommendation-config": (value): value is RecommendationConfig => {
    if (!value || typeof value !== "object" || Array.isArray(value)) return false;
    const config = value as Record<string, unknown>;
    return (
      (config.algorithm === "baseline" || config.algorithm === "hybrid-v2") &&
      typeof config.maxItems === "number" &&
      Number.isSafeInteger(config.maxItems) &&
      config.maxItems > 0
    );
  },
};

export function isFeatureValue<K extends FeatureKey>(
  key: K,
  value: unknown,
): value is AppFeatures[K] {
  return FEATURE_VALIDATORS[key](value);
}

import type { Attributes } from "@growthbook/growthbook";

export interface FlagContext {
  userId?: string;
  anonymousId?: string;
  accountId?: string;
  plan?: "free" | "pro" | "enterprise";
  country?: string;
  roles?: string[];
  requestId?: string;
}

export function toGrowthBookAttributes(context: FlagContext): Attributes {
  const stablePersonId = context.userId ?? context.anonymousId;

  return {
    ...(stablePersonId ? { id: stablePersonId } : {}),
    ...(context.userId ? { logged_in: true } : { logged_in: false }),
    ...(context.accountId ? { account_id: context.accountId } : {}),
    ...(context.plan ? { plan: context.plan } : {}),
    ...(context.country ? { country: context.country } : {}),
    ...(context.roles ? { roles: context.roles } : {}),
  };
}

import type { AppFeatures, FeatureKey } from "./app-features.js";
import type { FlagContext } from "./context.js";

export type ProviderName = "legacy" | "growthbook";
export type ServedBy = ProviderName | "code-fallback";

export interface ProviderDecision<K extends FeatureKey> {
  key: K;
  value: AppFeatures[K];
  evaluatedBy: ProviderName;
  reason: string;
  ruleId?: string;
  usable: boolean;
  usedCodeFallback: boolean;
}

export interface ServedDecision<K extends FeatureKey> {
  key: K;
  value: AppFeatures[K];
  mode: FlagProviderMode;
  servedBy: ServedBy;
  primary: ProviderDecision<K>;
  comparison?: ProviderDecision<K>;
  match?: boolean;
}

export interface FlagScope {
  decide<K extends FeatureKey>(
    key: K,
    fallback: AppFeatures[K],
  ): ServedDecision<K>;

  get<K extends FeatureKey>(key: K, fallback: AppFeatures[K]): AppFeatures[K];
}

export interface FeatureProvider {
  scope(context: FlagContext): ProviderScope;
  close(): void;
}

export interface ProviderScope {
  evaluate<K extends FeatureKey>(
    key: K,
    fallback: AppFeatures[K],
  ): ProviderDecision<K>;
}

export type FlagProviderMode =
  | "legacy"
  | "shadow"
  | "growthbook-preferred"
  | "growthbook-only";

legacy               evaluate and serve legacy only
shadow               serve legacy; evaluate GrowthBook; compare
growthbook-preferred serve GrowthBook when usable; otherwise serve legacy
growthbook-only      serve GrowthBook; use the call-site fallback if unavailable

import { readFile } from "node:fs/promises";
import type { RecommendationConfig } from "./app-features.js";

export interface LegacyFlagRow {
  flagKey: string;
  accountId: string;
  enabled: boolean;
}

export interface LegacySnapshot {
  checkoutV2: boolean;
  invoicePreviewAccounts: ReadonlySet<string>;
  invoicePreviewRollout: number;
  searchPageSize: number;
  recommendationConfig: RecommendationConfig;
}

export interface LegacyLoadOptions {
  env: NodeJS.ProcessEnv;
  configPath: string;
  loadRows: () => Promise<LegacyFlagRow[]>;
}

function exactBoolean(name: string, raw: string | undefined): boolean {
  if (raw === undefined) return false;
  if (raw === "true") return true;
  if (raw === "false") return false;
  throw new Error(`${name} must be exactly "true" or "false"`);
}

function percent(name: string, raw: string | undefined): number {
  const value = raw === undefined ? 0 : Number(raw);
  if (!Number.isFinite(value) || value < 0 || value > 100) {
    throw new Error(`${name} must be between 0 and 100`);
  }
  return value;
}

function pageSize(raw: unknown): number {
  if (raw === 25 || raw === 50 || raw === 100) return raw;
  throw new Error("searchPageSize must be 25, 50, or 100");
}

function recommendationConfig(raw: unknown): RecommendationConfig {
  if (!raw || typeof raw !== "object") {
    throw new Error("recommendationConfig must be an object");
  }
  const value = raw as Record<string, unknown>;
  if (value.algorithm !== "baseline" && value.algorithm !== "hybrid-v2") {
    throw new Error("recommendationConfig.algorithm is invalid");
  }
  if (!Number.isInteger(value.maxItems) || Number(value.maxItems) < 1) {
    throw new Error("recommendationConfig.maxItems must be a positive integer");
  }
  return {
    algorithm: value.algorithm,
    maxItems: Number(value.maxItems),
  };
}

export async function loadLegacySnapshot(
  options: LegacyLoadOptions,
): Promise<LegacySnapshot> {
  const file = JSON.parse(await readFile(options.configPath, "utf8")) as {
    searchPageSize?: unknown;
    recommendationConfig?: unknown;
  };
  const rows = await options.loadRows();

  return Object.freeze({
    checkoutV2: exactBoolean(
      "FEATURE_CHECKOUT_V2",
      options.env.FEATURE_CHECKOUT_V2,
    ),
    invoicePreviewAccounts: new Set(
      rows
        .filter((row) => row.flagKey === "invoice-preview" && row.enabled)
        .map((row) => row.accountId),
    ),
    invoicePreviewRollout: percent(
      "INVOICE_PREVIEW_ROLLOUT_PERCENT",
      options.env.INVOICE_PREVIEW_ROLLOUT_PERCENT,
    ),
    searchPageSize: pageSize(file.searchPageSize),
    recommendationConfig: recommendationConfig(file.recommendationConfig),
  });
}

import { createHash } from "node:crypto";
import type { AppFeatures, FeatureKey } from "./app-features.js";
import type { FlagContext } from "./context.js";
import type {
  FeatureProvider,
  ProviderDecision,
  ProviderScope,
} from "./provider.js";
import type { LegacySnapshot } from "./legacy-loader.js";

function legacyBucket(seed: string, value: string): number {
  const hex = createHash("sha256").update(`${seed}:${value}`).digest("hex");
  const first48Bits = Number.parseInt(hex.slice(0, 12), 16);
  return first48Bits / 0x1000000000000;
}

type Resolver<K extends FeatureKey> = (
  snapshot: LegacySnapshot,
  context: FlagContext,
) => AppFeatures[K];

type ResolverMap = { [K in FeatureKey]: Resolver<K> };

const resolvers = {
  "checkout-v2": (snapshot) => snapshot.checkoutV2,
  "invoice-preview": (snapshot, context) => {
    if (!context.accountId) return false;
    if (snapshot.invoicePreviewAccounts.has(context.accountId)) return true;
    return (
      legacyBucket("invoice-preview-v1", context.accountId) <
      snapshot.invoicePreviewRollout / 100
    );
  },
  "search-page-size": (snapshot) => snapshot.searchPageSize,
  "recommendation-config": (snapshot) => snapshot.recommendationConfig,
} satisfies ResolverMap;

export class LegacyFlagProvider implements FeatureProvider {
  public constructor(private readonly snapshot: LegacySnapshot) {}

  public scope(context: FlagContext): ProviderScope {
    return {
      evaluate: <K extends FeatureKey>(
        key: K,
        _fallback: AppFeatures[K],
      ): ProviderDecision<K> => {
        const resolver = resolvers[key] as Resolver<K>;
        return {
          key,
          value: resolver(this.snapshot, context),
          evaluatedBy: "legacy",
          reason: "legacy-resolver",
          usable: true,
          usedCodeFallback: false,
        };
      },
    };
  }

  public close(): void {}
}

import {
  GrowthBookClient,
  type FeatureApiResponse,
} from "@growthbook/growthbook";
import { isFeatureValue, type AppFeatures, type FeatureKey } from "./app-features.js";
import { startFeaturePolling } from "./feature-refresh.js";
import { toGrowthBookAttributes, type FlagContext } from "./context.js";
import type {
  FeatureProvider,
  ProviderDecision,
  ProviderScope,
} from "./provider.js";

export interface GrowthBookConnectOptions {
  apiHost: string;
  clientKey: string;
  timeoutMs: number;
}

export interface GrowthBookStartupReceipt {
  success: boolean;
  source: "network" | "cache" | "init" | "error" | "timeout";
  error?: string;
}

export class GrowthBookFlagProvider implements FeatureProvider {
  private constructor(
    private readonly client: GrowthBookClient<AppFeatures>,
    private readonly stopPolling: () => void = () => {},
  ) {}

  public static async connect(options: GrowthBookConnectOptions): Promise<{
    provider: GrowthBookFlagProvider;
    receipt: GrowthBookStartupReceipt;
  }> {
    if (!options.clientKey) {
      throw new Error("GROWTHBOOK_CLIENT_KEY is required");
    }

    const client = new GrowthBookClient<AppFeatures>({
      apiHost: options.apiHost,
      clientKey: options.clientKey,
    });

    const result = await client.init({ timeout: options.timeoutMs });
    const receipt: GrowthBookStartupReceipt = {
      success: result.success,
      source: result.source,
      ...(result.error ? { error: result.error.message } : {}),
    };

    return {
      provider: new GrowthBookFlagProvider(client, startFeaturePolling(client)),
      receipt,
    };
  }

  public static fromPayload(
    payload: FeatureApiResponse,
  ): GrowthBookFlagProvider {
    const client = new GrowthBookClient<AppFeatures>().initSync({ payload });
    return new GrowthBookFlagProvider(client);
  }

  public scope(context: FlagContext): ProviderScope {
    const scoped = this.client.createScopedInstance({
      attributes: toGrowthBookAttributes(context),
    });

    return {
      evaluate: <K extends FeatureKey>(
        key: K,
        fallback: AppFeatures[K],
      ): ProviderDecision<K> => {
        const result = scoped.evalFeature(key);
        const usable = isFeatureValue(key, result.value);

        return {
          key,
          value: usable ? (result.value as AppFeatures[K]) : fallback,
          evaluatedBy: "growthbook",
          reason: usable || result.value === null ? result.source : "invalid-value",
          ...(result.ruleId ? { ruleId: result.ruleId } : {}),
          usable,
          usedCodeFallback: !usable,
        };
      },
    };
  }

  public close(): void {
    this.stopPolling();
    this.client.destroy({ destroyAllStreams: true });
  }
}

import { createHash } from "node:crypto";
import type { FeatureKey } from "./app-features.js";
import type { FlagContext } from "./context.js";
import type { ServedDecision } from "./provider.js";

function stableValue(value: unknown): string {
  if (Array.isArray(value)) {
    return `[${value.map(stableValue).join(",")}]`;
  }
  if (value && typeof value === "object") {
    const object = value as Record<string, unknown>;
    return `{${Object.keys(object)
      .sort()
      .map((key) => `${JSON.stringify(key)}:${stableValue(object[key])}`)
      .join(",")}}`;
  }
  return JSON.stringify(value) ?? "undefined";
}

function digest(salt: string, value: string): string {
  return createHash("sha256")
    .update(salt)
    .update("\0")
    .update(value)
    .digest("hex")
    .slice(0, 16);
}

export function decisionsMatch(a: unknown, b: unknown): boolean {
  return stableValue(a) === stableValue(b);
}

export interface DecisionTelemetry {
  record<K extends FeatureKey>(
    context: FlagContext,
    decision: ServedDecision<K>,
  ): void;
}

export class NoopDecisionTelemetry implements DecisionTelemetry {
  public record(): void {}
}

export class ConsoleDecisionTelemetry implements DecisionTelemetry {
  public constructor(
    private readonly salt: string,
    private readonly matchingSampleRate = 0.01,
  ) {
    if (!salt) throw new Error("FLAG_TELEMETRY_SALT is required");
  }

  public record<K extends FeatureKey>(
    context: FlagContext,
    decision: ServedDecision<K>,
  ): void {
    const subject =
      context.accountId ??
      context.userId ??
      context.anonymousId ??
      "unidentified";
    const sample =
      Number.parseInt(
        digest(this.salt, `${decision.key}:${subject}`).slice(0, 8),
        16,
      ) / 0xffffffff;

    if (decision.match === true && sample > this.matchingSampleRate) return;

    process.stdout.write(
      `${JSON.stringify({
        event: "feature_flag_decision",
        timestamp: new Date().toISOString(),
        key: decision.key,
        mode: decision.mode,
        servedBy: decision.servedBy,
        match: decision.match,
        primaryReason: decision.primary.reason,
        comparisonReason: decision.comparison?.reason,
        primaryValueDigest: digest(
          this.salt,
          stableValue(decision.primary.value),
        ),
        comparisonValueDigest: decision.comparison
          ? digest(this.salt, stableValue(decision.comparison.value))
          : undefined,
        subjectHash: digest(this.salt, subject),
        attributesPresent: [
          context.userId ? "user_id" : null,
          context.anonymousId ? "anonymous_id" : null,
          context.accountId ? "account_id" : null,
          context.plan ? "plan" : null,
          context.country ? "country" : null,
          context.roles ? "roles" : null,
        ].filter(Boolean),
      })}\n`,
    );
  }
}

import type { AppFeatures, FeatureKey } from "./app-features.js";
import type { FlagContext } from "./context.js";
import {
  decisionsMatch,
  type DecisionTelemetry,
} from "./decision-telemetry.js";
import type {
  FeatureProvider,
  FlagProviderMode,
  FlagScope,
  ProviderDecision,
  ServedDecision,
} from "./provider.js";

export class MigratingFlagProvider {
  public constructor(
    private readonly legacy: FeatureProvider,
    private readonly growthbook: FeatureProvider | undefined,
    private readonly mode: FlagProviderMode,
    private readonly telemetry: DecisionTelemetry,
    private readonly growthbookServeKeys: ReadonlySet<FeatureKey> = new Set(),
  ) {
    if (mode !== "legacy" && !growthbook) {
      throw new Error(`${mode} requires a GrowthBook provider`);
    }
  }

  public scope(context: FlagContext): FlagScope {
    const legacy = this.legacy.scope(context);
    const growthbook = this.growthbook?.scope(context);

    const decide = <K extends FeatureKey>(
      key: K,
      fallback: AppFeatures[K],
    ): ServedDecision<K> => {
      let decision: ServedDecision<K>;

      if (this.mode === "legacy") {
        const primary = legacy.evaluate(key, fallback);
        decision = {
          key,
          value: primary.value,
          mode: this.mode,
          servedBy: "legacy",
          primary,
        };
      } else if (this.mode === "shadow") {
        const primary = legacy.evaluate(key, fallback);
        const comparison = growthbook!.evaluate(key, fallback);
        decision = {
          key,
          value: primary.value,
          mode: this.mode,
          servedBy: "legacy",
          primary,
          comparison,
          match:
            comparison.usable &&
            decisionsMatch(primary.value, comparison.value),
        };
      } else if (this.mode === "growthbook-preferred") {
        const growthbookDecision = growthbook!.evaluate(key, fallback);
        const legacyDecision = legacy.evaluate(key, fallback);
        const selected = this.growthbookServeKeys.has(key);
        const primary = selected ? growthbookDecision : legacyDecision;
        const comparison = selected ? legacyDecision : growthbookDecision;
        const useGrowthBook = selected && growthbookDecision.usable;
        decision = {
          key,
          value: useGrowthBook
            ? growthbookDecision.value
            : legacyDecision.value,
          mode: this.mode,
          servedBy: useGrowthBook ? "growthbook" : "legacy",
          primary,
          comparison,
          match:
            growthbookDecision.usable &&
            decisionsMatch(growthbookDecision.value, legacyDecision.value),
        };
      } else {
        const primary = growthbook!.evaluate(key, fallback);
        decision = {
          key,
          value: primary.value,
          mode: this.mode,
          servedBy: primary.usable ? "growthbook" : "code-fallback",
          primary,
        };
      }

      this.telemetry.record(context, decision);
      return decision;
    };

    return {
      decide,
      get: <K extends FeatureKey>(key: K, fallback: AppFeatures[K]) =>
        decide(key, fallback).value,
    };
  }

  public close(): void {
    this.legacy.close();
    this.growthbook?.close();
  }
}

import { CODE_FALLBACKS, type FeatureKey } from "./app-features.js";
import {
  ConsoleDecisionTelemetry,
  NoopDecisionTelemetry,
} from "./decision-telemetry.js";
import { GrowthBookFlagProvider } from "./growthbook-provider.js";
import { loadLegacySnapshot, type LegacyFlagRow } from "./legacy-loader.js";
import { LegacyFlagProvider } from "./legacy-provider.js";
import { MigratingFlagProvider } from "./migrating-provider.js";
import type { FlagProviderMode } from "./provider.js";

const modes = new Set<FlagProviderMode>([
  "legacy",
  "shadow",
  "growthbook-preferred",
  "growthbook-only",
]);

function providerMode(raw: string | undefined): FlagProviderMode {
  const value = raw ?? "legacy";
  if (!modes.has(value as FlagProviderMode)) {
    throw new Error(`Invalid FLAG_PROVIDER_MODE: ${value}`);
  }
  return value as FlagProviderMode;
}

function serveKeys(raw: string | undefined): ReadonlySet<FeatureKey> {
  if (!raw?.trim()) return new Set();
  const known = new Set(Object.keys(CODE_FALLBACKS));
  const requested = raw
    .split(",")
    .map((key) => key.trim())
    .filter(Boolean);
  const unknown = requested.filter((key) => !known.has(key));
  if (unknown.length > 0) {
    throw new Error(`Unknown GROWTHBOOK_SERVE_KEYS: ${unknown.join(",")}`);
  }
  return new Set(requested as FeatureKey[]);
}

export async function buildFeatureFlags(options: {
  legacyConfigPath: string;
  loadLegacyRows: () => Promise<LegacyFlagRow[]>;
}): Promise<MigratingFlagProvider> {
  const mode = providerMode(process.env.FLAG_PROVIDER_MODE);
  const selectedKeys = serveKeys(process.env.GROWTHBOOK_SERVE_KEYS);
  const snapshot = await loadLegacySnapshot({
    env: process.env,
    configPath: options.legacyConfigPath,
    loadRows: options.loadLegacyRows,
  });
  const legacy = new LegacyFlagProvider(snapshot);

  if (mode === "legacy") {
    process.stdout.write(
      `${JSON.stringify({
        event: "feature_flag_startup",
        mode,
        growthbookLoaded: false,
      })}\n`,
    );
    return new MigratingFlagProvider(
      legacy,
      undefined,
      mode,
      new NoopDecisionTelemetry(),
      selectedKeys,
    );
  }

  const { provider: growthbook, receipt } =
    await GrowthBookFlagProvider.connect({
      apiHost: process.env.GROWTHBOOK_API_HOST ?? "https://cdn.growthbook.io",
      clientKey: process.env.GROWTHBOOK_CLIENT_KEY ?? "",
      timeoutMs: Number(process.env.GROWTHBOOK_TIMEOUT_MS ?? 2000),
    });

  process.stdout.write(
    `${JSON.stringify({
      event: "feature_flag_startup",
      mode,
      growthbookLoaded: receipt.success,
      source: receipt.source,
      error: receipt.error,
    })}\n`,
  );

  return new MigratingFlagProvider(
    legacy,
    growthbook,
    mode,
    new ConsoleDecisionTelemetry(process.env.FLAG_TELEMETRY_SALT ?? ""),
    selectedKeys,
  );
}

export function canUseCheckoutV2(): boolean {
  return process.env.FEATURE_CHECKOUT_V2 === "true";
}

import { CODE_FALLBACKS } from "./feature-flags/app-features.js";
import type { FlagContext } from "./feature-flags/context.js";
import type { MigratingFlagProvider } from "./feature-flags/migrating-provider.js";

export function canUseCheckoutV2(
  featureFlags: MigratingFlagProvider,
  context: FlagContext,
): boolean {
  const flags = featureFlags.scope(context);
  return flags.get("checkout-v2", CODE_FALLBACKS["checkout-v2"]);
}

app.get("/checkout", async (request, response) => {
  const flags = featureFlags.scope({
    userId: request.user?.id,
    anonymousId: request.cookies.anonymous_id,
    accountId: request.user?.accountId,
    plan: request.user?.plan,
    country: request.geo?.country,
    roles: request.user?.roles,
    requestId: request.id,
  });

  const checkoutV2 = flags.get("checkout-v2", CODE_FALLBACKS["checkout-v2"]);

  response.render(checkoutV2 ? "checkout-v2" : "checkout-v1");
});

FLAG_PROVIDER_MODE=legacy
GROWTHBOOK_SERVE_KEYS=

FLAG_PROVIDER_MODE=shadow
GROWTHBOOK_SERVE_KEYS=
GROWTHBOOK_API_HOST=https://cdn.growthbook.io
GROWTHBOOK_CLIENT_KEY=<ENVIRONMENT_SCOPED_SDK_CLIENT_KEY>
GROWTHBOOK_TIMEOUT_MS=2000
FLAG_TELEMETRY_SALT=<SECRET_RANDOM_VALUE>

{
  "event": "feature_flag_decision",
  "key": "checkout-v2",
  "mode": "shadow",
  "servedBy": "legacy",
  "match": true,
  "primaryReason": "legacy-resolver",
  "comparisonReason": "defaultValue",
  "primaryValueDigest": "5df6e0e2761359d3",
  "comparisonValueDigest": "5df6e0e2761359d3",
  "subjectHash": "73ca8591bd4a1ab7",
  "attributesPresent": ["user_id", "account_id", "plan"]
}

{
  "event": "feature_flag_decision",
  "key": "invoice-preview",
  "mode": "shadow",
  "servedBy": "legacy",
  "match": false,
  "primaryReason": "legacy-resolver",
  "comparisonReason": "defaultValue",
  "primaryValueDigest": "b5bea41b6c623f7c",
  "comparisonValueDigest": "5df6e0e2761359d3",
  "subjectHash": "d9011ad70dcac48b",
  "attributesPresent": ["user_id", "account_id"]
}

FLAG_PROVIDER_MODE=growthbook-preferred
GROWTHBOOK_SERVE_KEYS=search-page-size

GROWTHBOOK_SERVE_KEYS=search-page-size,checkout-v2

FLAG_PROVIDER_MODE=growthbook-only
GROWTHBOOK_SERVE_KEYS=

Key: invoice-preview
Window: 2026-08-13T00:00Z to 2026-08-15T00:00Z
Total compared decisions: 183,240
Unexplained mismatches: 0
Expected mismatches: 2,941
Expected cause: legacy SHA-256 cohort differs from GrowthBook cohort
Resolution: preserve current 50-account allowlist; wait for legacy percentage to reach 100%
Missing account_id: 18 requests, all health checks
GrowthBook fallbacks: 0
Approved by: <ENGINEERING_OWNER>, <PRODUCT_OWNER>

import { CODE_FALLBACKS } from "../../src/feature-flags/app-features.js";
import { GrowthBookFlagProvider } from "../../src/feature-flags/growthbook-provider.js";

describe("GrowthBookFlagProvider", () => {
  test("uses a matching account rule and exposes its rule id", () => {
    const provider = GrowthBookFlagProvider.fromPayload({
      features: {
        "invoice-preview": {
          defaultValue: false,
          rules: [
            {
              id: "allow-acme",
              condition: { account_id: "acct-acme" },
              force: true,
            },
          ],
        },
      },
    });

    const included = provider
      .scope({ accountId: "acct-acme" })
      .evaluate("invoice-preview", CODE_FALLBACKS["invoice-preview"]);
    const excluded = provider
      .scope({ accountId: "acct-other" })
      .evaluate("invoice-preview", CODE_FALLBACKS["invoice-preview"]);

    expect(included).toMatchObject({
      value: true,
      reason: "force",
      ruleId: "allow-acme",
      usable: true,
    });
    expect(excluded).toMatchObject({
      value: false,
      reason: "defaultValue",
      usable: true,
    });
    provider.close();
  });

  test("uses the code fallback when a typed key is absent from the payload", () => {
    const provider = GrowthBookFlagProvider.fromPayload({ features: {} });
    const decision = provider
      .scope({ userId: "user-1" })
      .evaluate("checkout-v2", CODE_FALLBACKS["checkout-v2"]);

    expect(decision).toMatchObject({
      value: false,
      reason: "unknownFeature",
      usable: false,
      usedCodeFallback: true,
    });
    provider.close();
  });

  test("keeps account targeting isolated between request scopes", () => {
    const provider = GrowthBookFlagProvider.fromPayload({
      features: {
        "checkout-v2": {
          defaultValue: false,
          rules: [{ condition: { plan: "enterprise" }, force: true }],
        },
      },
    });

    expect(
      provider.scope({ plan: "enterprise" }).evaluate("checkout-v2", false)
        .value,
    ).toBe(true);
    expect(
      provider.scope({ plan: "free" }).evaluate("checkout-v2", false).value,
    ).toBe(false);
    provider.close();
  });

  test.each(["false", 0, {}, undefined])(
    "rejects a non-Boolean payload value: %p",
    (value) => {
      const provider = GrowthBookFlagProvider.fromPayload({
        features: { "checkout-v2": { defaultValue: value } },
      });
      expect(provider.scope({}).evaluate("checkout-v2", false)).toMatchObject({
        value: false,
        usable: false,
        usedCodeFallback: true,
      });
      provider.close();
    },
  );

  test("rejects invalid numeric and JSON values", () => {
    const provider = GrowthBookFlagProvider.fromPayload({
      features: {
        "search-page-size": { defaultValue: "50" },
        "recommendation-config": {
          defaultValue: { algorithm: "hybrid-v2", maxItems: -1 },
        },
      },
    });
    expect(provider.scope({}).evaluate("search-page-size", 25)).toMatchObject({
      value: 25, usable: false, reason: "invalid-value",
    });
    expect(
      provider.scope({}).evaluate("recommendation-config", CODE_FALLBACKS["recommendation-config"]),
    ).toMatchObject({
      value: CODE_FALLBACKS["recommendation-config"], usable: false,
    });
    provider.close();
  });
});

import { CODE_FALLBACKS } from "../../src/feature-flags/app-features.js";
import type { DecisionTelemetry } from "../../src/feature-flags/decision-telemetry.js";
import { GrowthBookFlagProvider } from "../../src/feature-flags/growthbook-provider.js";
import type { LegacySnapshot } from "../../src/feature-flags/legacy-loader.js";
import { LegacyFlagProvider } from "../../src/feature-flags/legacy-provider.js";
import { MigratingFlagProvider } from "../../src/feature-flags/migrating-provider.js";

const snapshot: LegacySnapshot = {
  checkoutV2: false,
  invoicePreviewAccounts: new Set(),
  invoicePreviewRollout: 0,
  searchPageSize: 25,
  recommendationConfig: { algorithm: "baseline", maxItems: 10 },
};

class MemoryTelemetry implements DecisionTelemetry {
  public readonly decisions: unknown[] = [];
  public record(_context: unknown, decision: unknown): void {
    this.decisions.push(decision);
  }
}

function providers() {
  return {
    legacy: new LegacyFlagProvider(snapshot),
    growthbook: GrowthBookFlagProvider.fromPayload({
      features: {
        "checkout-v2": { defaultValue: true },
        "search-page-size": { defaultValue: 50 },
      },
    }),
  };
}

describe("MigratingFlagProvider", () => {
  test("shadow compares GrowthBook but serves legacy", () => {
    const { legacy, growthbook } = providers();
    const telemetry = new MemoryTelemetry();
    const provider = new MigratingFlagProvider(
      legacy,
      growthbook,
      "shadow",
      telemetry,
    );

    const decision = provider
      .scope({ userId: "user-1" })
      .decide("checkout-v2", CODE_FALLBACKS["checkout-v2"]);

    expect(decision.value).toBe(false);
    expect(decision.servedBy).toBe("legacy");
    expect(decision.match).toBe(false);
    expect(telemetry.decisions).toHaveLength(1);
    provider.close();
  });

  test("growthbook-preferred serves only selected keys", () => {
    const { legacy, growthbook } = providers();
    const provider = new MigratingFlagProvider(
      legacy,
      growthbook,
      "growthbook-preferred",
      new MemoryTelemetry(),
      new Set(["checkout-v2"]),
    );
    const scope = provider.scope({ userId: "user-1" });

    expect(scope.decide("checkout-v2", false)).toMatchObject({
      value: true,
      servedBy: "growthbook",
    });
    expect(scope.decide("search-page-size", 25)).toMatchObject({
      value: 25,
      servedBy: "legacy",
    });
    provider.close();
  });

  test("selected missing keys temporarily fall back to legacy", () => {
    const { legacy, growthbook } = providers();
    const provider = new MigratingFlagProvider(
      legacy,
      growthbook,
      "growthbook-preferred",
      new MemoryTelemetry(),
      new Set(["invoice-preview"]),
    );

    expect(
      provider.scope({ accountId: "acct-1" }).decide("invoice-preview", false),
    ).toMatchObject({ value: false, servedBy: "legacy" });
    provider.close();
  });
});