@mergedapp/feature-flags 0.1.0

package/dist/cli.js

@@ -0,0 +1,578 @@
+#!/usr/bin/env node
+var __defProp = Object.defineProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+
+// src/cli/generate.ts
+import { mkdir, writeFile } from "fs/promises";
+import { dirname as dirname2, resolve as resolve2 } from "path";
+
+// src/cli/config-loader.ts
+import { existsSync } from "fs";
+import { readFile } from "fs/promises";
+import { dirname, isAbsolute, resolve } from "path";
+import { pathToFileURL } from "url";
+var CONFIG_FILE_NAMES = [
+  "featureflags.config.json",
+  "featureflags.config.js",
+  "featureflags.config.mjs",
+  "featureflags.config.cjs"
+];
+async function load(params) {
+  const cwd = params.cwd ?? process.cwd();
+  if (params.configPath) {
+    const explicitPath = isAbsolute(params.configPath) ? params.configPath : resolve(cwd, params.configPath);
+    return loadFile({
+      configPath: explicitPath
+    });
+  }
+  const discoveredConfigPath = await findNearestConfigPath({
+    cwd
+  });
+  if (!discoveredConfigPath) {
+    return {
+      config: {},
+      configPath: null
+    };
+  }
+  return loadFile({
+    configPath: discoveredConfigPath
+  });
+}
+__name(load, "load");
+function resolveConfigRelativePath(params) {
+  if (!params.value) {
+    return void 0;
+  }
+  if (isAbsolute(params.value) || !params.configPath) {
+    return params.value;
+  }
+  return resolve(dirname(params.configPath), params.value);
+}
+__name(resolveConfigRelativePath, "resolveConfigRelativePath");
+async function findNearestConfigPath(params) {
+  let currentDirectory = resolve(params.cwd);
+  while (true) {
+    for (const fileName of CONFIG_FILE_NAMES) {
+      const candidatePath = resolve(currentDirectory, fileName);
+      if (existsSync(candidatePath)) {
+        return candidatePath;
+      }
+    }
+    const parentDirectory = dirname(currentDirectory);
+    if (parentDirectory === currentDirectory) {
+      return null;
+    }
+    currentDirectory = parentDirectory;
+  }
+}
+__name(findNearestConfigPath, "findNearestConfigPath");
+async function loadFile(params) {
+  if (params.configPath.endsWith(".json")) {
+    const content = await readFile(params.configPath, "utf-8");
+    return {
+      config: JSON.parse(content),
+      configPath: params.configPath
+    };
+  }
+  const imported = await import(pathToFileURL(params.configPath).href);
+  const config = imported.default ?? imported;
+  if (!config || typeof config !== "object") {
+    return {
+      config: {},
+      configPath: params.configPath
+    };
+  }
+  return {
+    config,
+    configPath: params.configPath
+  };
+}
+__name(loadFile, "loadFile");
+var FeatureFlagCliConfigLoader = {
+  load,
+  resolveConfigRelativePath
+};
+
+// src/cli/generate.ts
+function assertValidCodeKey(codeKey) {
+  if (!/^[a-z][A-Za-z0-9]*$/.test(codeKey)) {
+    throw new Error(`Invalid feature flag codeKey "${codeKey}". Code keys must be lowerCamelCase alphanumeric identifiers.`);
+  }
+}
+__name(assertValidCodeKey, "assertValidCodeKey");
+function flagTypeToTsType(flagType) {
+  switch (flagType) {
+    case "BOOLEAN":
+      return "boolean";
+    case "STRING":
+      return "string";
+    case "NUMBER":
+      return "number";
+    case "JSON":
+      return "Record<string, unknown>";
+    case "ARRAY":
+      return "unknown[]";
+    default:
+      return "unknown";
+  }
+}
+__name(flagTypeToTsType, "flagTypeToTsType");
+function escapeJsDoc(str) {
+  return str.replace(/\*\//g, "*\\/").replace(/\n/g, " ");
+}
+__name(escapeJsDoc, "escapeJsDoc");
+async function fetchDefinitions(params) {
+  const url = new URL("/api/feature-flags/definitions", params.apiUrl);
+  url.searchParams.set("organizationId", params.organizationId);
+  if (params.teamId) {
+    url.searchParams.set("teamId", params.teamId);
+  }
+  const response = await fetch(url.toString(), {
+    headers: {
+      Authorization: `Bearer ${params.clientKey}`
+    }
+  });
+  if (!response.ok) {
+    throw new Error(`Failed to fetch definitions: ${response.status} ${response.statusText}`);
+  }
+  const body = await response.json();
+  return body.definitions;
+}
+__name(fetchDefinitions, "fetchDefinitions");
+function generateCode(definitions) {
+  const activeFlags = definitions.filter((d) => !d.isArchived);
+  if (activeFlags.length === 0) {
+    return `// Auto-generated by @mergedapp/feature-flags. Do not edit.
+// Generated at: ${(/* @__PURE__ */ new Date()).toISOString()}
+// No active feature flags found.
+
+import { MergedFeatureFlags } from "@mergedapp/feature-flags"
+import { createTypedHooks } from "@mergedapp/feature-flags/react"
+import type { FeatureFlagClientConfig } from "@mergedapp/feature-flags"
+
+export const FLAGS = {} as const
+
+export interface FlagValues {}
+
+export type FlagName = keyof typeof FLAGS
+
+export function createClient(config: FeatureFlagClientConfig) {
+  return new MergedFeatureFlags<FlagValues>({ ...config, flagIds: FLAGS })
+}
+
+export const { FeatureFlagProvider, FeatureFlag, useFeatureFlag, useFeatureFlags, useFeatureFlagClient, useFeatureFlagStatus } =
+  createTypedHooks<FlagValues>()
+`;
+  }
+  const flagEntries = activeFlags.map((flag) => {
+    assertValidCodeKey(flag.codeKey);
+    const doc = flag.description ? `  /** ${escapeJsDoc(flag.description)} */
+` : "";
+    return {
+      key: flag.codeKey,
+      id: flag.id,
+      type: flag.type,
+      doc
+    };
+  });
+  const flagsConst = flagEntries.map((e) => `${e.doc}  ${e.key}: "${e.id}",`).join("\n");
+  const flagValuesEntries = flagEntries.map((e) => `  ${e.key}: ${flagTypeToTsType(e.type)}`).join("\n");
+  return `// Auto-generated by @mergedapp/feature-flags. Do not edit.
+// Generated at: ${(/* @__PURE__ */ new Date()).toISOString()}
+
+import { MergedFeatureFlags } from "@mergedapp/feature-flags"
+import { createTypedHooks } from "@mergedapp/feature-flags/react"
+import type { FeatureFlagClientConfig } from "@mergedapp/feature-flags"
+
+/** Stable flag ID mapping. Names are for readability; IDs are used at runtime. */
+export const FLAGS = {
+${flagsConst}
+} as const
+
+/** Type-safe flag value types inferred from flag definitions. */
+export interface FlagValues {
+${flagValuesEntries}
+}
+
+export type FlagName = keyof typeof FLAGS
+
+/** Create a type-safe client bound to this flag registry. */
+export function createClient(config: FeatureFlagClientConfig) {
+  return new MergedFeatureFlags<FlagValues>({ ...config, flagIds: FLAGS })
+}
+
+/** Pre-typed React hooks, provider, and JSX wrapper bound to this flag registry. */
+export const { FeatureFlagProvider, FeatureFlag, useFeatureFlag, useFeatureFlags, useFeatureFlagClient, useFeatureFlagStatus } =
+  createTypedHooks<FlagValues>()
+`;
+}
+__name(generateCode, "generateCode");
+async function generate(args2) {
+  const loadedConfig = await FeatureFlagCliConfigLoader.load({
+    configPath: args2.config
+  });
+  const config = loadedConfig.config;
+  const apiUrl = args2["api-url"] ?? config.apiUrl ?? process.env.FEATURE_FLAG_API_URL;
+  const clientKey = args2["client-key"] ?? config.clientKey ?? process.env.FEATURE_FLAG_CLIENT_KEY;
+  const outputPath = args2.output ?? FeatureFlagCliConfigLoader.resolveConfigRelativePath({
+    value: config.outputPath,
+    configPath: loadedConfig.configPath
+  }) ?? "./src/generated/feature-flags.ts";
+  const teamId = args2["team-id"] ?? config.teamId;
+  const organizationId = args2["organization-id"] ?? config.organizationId ?? process.env.FEATURE_FLAG_ORGANIZATION_ID;
+  if (!apiUrl) {
+    throw new Error("Missing --api-url or FEATURE_FLAG_API_URL env var.");
+  }
+  if (!clientKey) {
+    throw new Error("Missing --client-key or FEATURE_FLAG_CLIENT_KEY env var.");
+  }
+  if (!organizationId) {
+    throw new Error("Missing --organization-id, FEATURE_FLAG_ORGANIZATION_ID, or config.organizationId.");
+  }
+  console.log(`Fetching flag definitions from ${apiUrl}...`);
+  const definitions = await fetchDefinitions({
+    apiUrl,
+    clientKey,
+    organizationId,
+    teamId
+  });
+  console.log(`Found ${definitions.length} flag definitions.`);
+  const code = generateCode(definitions);
+  const resolvedPath = resolve2(outputPath);
+  await mkdir(dirname2(resolvedPath), {
+    recursive: true
+  });
+  await writeFile(resolvedPath, code, "utf-8");
+  console.log(`Generated typed flags at ${resolvedPath}`);
+}
+__name(generate, "generate");
+
+// src/cli/audit.ts
+import { readFile as readFile2, readdir } from "fs/promises";
+import { resolve as resolve3, join, extname } from "path";
+var CODE_EXTENSIONS = /* @__PURE__ */ new Set([
+  ".ts",
+  ".tsx",
+  ".js",
+  ".jsx",
+  ".mjs",
+  ".cjs"
+]);
+async function collectFiles(dir) {
+  const files = [];
+  const entries = await readdir(dir, {
+    withFileTypes: true
+  });
+  for (const entry of entries) {
+    const fullPath = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      if (entry.name === "node_modules" || entry.name === ".git" || entry.name === "dist") {
+        continue;
+      }
+      files.push(...await collectFiles(fullPath));
+    } else if (CODE_EXTENSIONS.has(extname(entry.name))) {
+      files.push(fullPath);
+    }
+  }
+  return files;
+}
+__name(collectFiles, "collectFiles");
+async function fetchDefinitions2(params) {
+  const url = new URL("/api/feature-flags/definitions", params.apiUrl);
+  url.searchParams.set("organizationId", params.organizationId);
+  const response = await fetch(url.toString(), {
+    headers: {
+      Authorization: `Bearer ${params.clientKey}`
+    }
+  });
+  if (!response.ok) {
+    throw new Error(`Failed to fetch definitions: ${response.status} ${response.statusText}`);
+  }
+  const body = await response.json();
+  return body.definitions;
+}
+__name(fetchDefinitions2, "fetchDefinitions");
+async function audit(args2) {
+  const dir = resolve3(args2.dir ?? "./src");
+  const loadedConfig = await FeatureFlagCliConfigLoader.load({
+    configPath: args2.config
+  });
+  const config = loadedConfig.config;
+  const apiUrl = args2["api-url"] ?? config.apiUrl ?? process.env.FEATURE_FLAG_API_URL;
+  const clientKey = args2["client-key"] ?? config.clientKey ?? process.env.FEATURE_FLAG_CLIENT_KEY;
+  const organizationId = args2["organization-id"] ?? config.organizationId ?? process.env.FEATURE_FLAG_ORGANIZATION_ID;
+  if (!apiUrl || !clientKey || !organizationId) {
+    throw new Error("Missing --api-url, --client-key, --organization-id, or a discoverable featureflags config.");
+  }
+  console.log(`Fetching flag definitions from ${apiUrl}...`);
+  const definitions = await fetchDefinitions2({
+    apiUrl,
+    clientKey,
+    organizationId
+  });
+  console.log(`Scanning ${dir} for flag references...`);
+  const files = await collectFiles(dir);
+  const flagIdSet = new Set(definitions.map((d) => d.id));
+  const flagCodeKeySet = new Set(definitions.map((d) => d.codeKey));
+  const archivedIds = new Set(definitions.filter((d) => d.isArchived).map((d) => d.id));
+  const referencedIds = /* @__PURE__ */ new Set();
+  const referencedCodeKeys = /* @__PURE__ */ new Set();
+  for (const file of files) {
+    const content = await readFile2(file, "utf-8");
+    for (const id of flagIdSet) {
+      if (content.includes(id)) {
+        referencedIds.add(id);
+      }
+    }
+    for (const codeKey of flagCodeKeySet) {
+      if (content.includes(`"${codeKey}"`) || content.includes(`'${codeKey}'`)) {
+        referencedCodeKeys.add(codeKey);
+      }
+    }
+  }
+  const codeKeyToDefinition = new Map(definitions.map((d) => [
+    d.codeKey,
+    d
+  ]));
+  const allReferenced = /* @__PURE__ */ new Set();
+  for (const id of referencedIds) allReferenced.add(id);
+  for (const codeKey of referencedCodeKeys) {
+    const def = codeKeyToDefinition.get(codeKey);
+    if (def) allReferenced.add(def.id);
+  }
+  const used = [];
+  const unused = [];
+  const archivedButReferenced = [];
+  for (const def of definitions) {
+    if (allReferenced.has(def.id)) {
+      if (archivedIds.has(def.id)) {
+        archivedButReferenced.push(def);
+      } else {
+        used.push(def);
+      }
+    } else if (!def.isArchived) {
+      unused.push(def);
+    }
+  }
+  console.log("\n--- Feature Flag Audit Report ---\n");
+  if (used.length > 0) {
+    console.log(`Active and referenced (${used.length}):`);
+    for (const d of used) {
+      console.log(`  [OK] ${d.codeKey} (${d.id})`);
+    }
+  }
+  if (unused.length > 0) {
+    console.log(`
+Defined in API but not referenced in code (${unused.length}):`);
+    for (const d of unused) {
+      console.log(`  [UNUSED] ${d.codeKey} (${d.id})`);
+    }
+  }
+  if (archivedButReferenced.length > 0) {
+    console.log(`
+Archived but still referenced in code (${archivedButReferenced.length}):`);
+    for (const d of archivedButReferenced) {
+      console.log(`  [STALE] ${d.codeKey} (${d.id}) \u2014 archived, needs cleanup`);
+    }
+  }
+  if (unused.length === 0 && archivedButReferenced.length === 0) {
+    console.log("\nAll flags are clean.");
+  }
+  console.log(`
+Scanned ${files.length} files in ${dir}.`);
+}
+__name(audit, "audit");
+
+// src/cli/cleanup.ts
+import { readFile as readFile3, writeFile as writeFile2, readdir as readdir2 } from "fs/promises";
+import { resolve as resolve4, join as join2, extname as extname2 } from "path";
+var CODE_EXTENSIONS2 = /* @__PURE__ */ new Set([
+  ".ts",
+  ".tsx",
+  ".js",
+  ".jsx",
+  ".mjs",
+  ".cjs"
+]);
+async function collectFiles2(dir) {
+  const files = [];
+  const entries = await readdir2(dir, {
+    withFileTypes: true
+  });
+  for (const entry of entries) {
+    const fullPath = join2(dir, entry.name);
+    if (entry.isDirectory()) {
+      if (entry.name === "node_modules" || entry.name === ".git" || entry.name === "dist") {
+        continue;
+      }
+      files.push(...await collectFiles2(fullPath));
+    } else if (CODE_EXTENSIONS2.has(extname2(entry.name))) {
+      files.push(fullPath);
+    }
+  }
+  return files;
+}
+__name(collectFiles2, "collectFiles");
+async function fetchDefinitions3(params) {
+  const url = new URL("/api/feature-flags/definitions", params.apiUrl);
+  url.searchParams.set("organizationId", params.organizationId);
+  const response = await fetch(url.toString(), {
+    headers: {
+      Authorization: `Bearer ${params.clientKey}`
+    }
+  });
+  if (!response.ok) {
+    throw new Error(`Failed to fetch definitions: ${response.status} ${response.statusText}`);
+  }
+  const body = await response.json();
+  return body.definitions;
+}
+__name(fetchDefinitions3, "fetchDefinitions");
+async function cleanup(args2) {
+  const dir = resolve4(args2.dir ?? "./src");
+  const dryRun = "dry-run" in args2;
+  const apiUrl = args2["api-url"] ?? process.env.FEATURE_FLAG_API_URL;
+  const clientKey = args2["client-key"] ?? process.env.FEATURE_FLAG_CLIENT_KEY;
+  const organizationId = args2["organization-id"];
+  if (!apiUrl || !clientKey || !organizationId) {
+    throw new Error("Missing --api-url, --client-key, or --organization-id.");
+  }
+  console.log(`Fetching flag definitions from ${apiUrl}...`);
+  const definitions = await fetchDefinitions3({
+    apiUrl,
+    clientKey,
+    organizationId
+  });
+  const archivedFlags = definitions.filter((d) => d.isArchived && d.type === "BOOLEAN");
+  if (archivedFlags.length === 0) {
+    console.log("No archived boolean flags to clean up.");
+    return;
+  }
+  console.log(`Found ${archivedFlags.length} archived boolean flags to scan for.`);
+  console.log(`Scanning ${dir}...`);
+  const files = await collectFiles2(dir);
+  let totalReplacements = 0;
+  for (const filePath of files) {
+    let content = await readFile3(filePath, "utf-8");
+    let modified = false;
+    for (const flag of archivedFlags) {
+      const result = replaceArchivedFlagChecks({
+        content,
+        dryRun,
+        filePath,
+        flag
+      });
+      content = result.content;
+      modified ||= result.replacements > 0;
+      totalReplacements += result.replacements;
+    }
+    if (modified && !dryRun) {
+      await writeFile2(filePath, content, "utf-8");
+      console.log(`  Updated: ${filePath}`);
+    }
+  }
+  if (totalReplacements === 0) {
+    console.log("No archived flag references found in code.");
+  } else if (dryRun) {
+    console.log(`
+${totalReplacements} replacement(s) would be made. Re-run without --dry-run to apply.`);
+  } else {
+    console.log(`
+${totalReplacements} replacement(s) applied. Run 'merged-ff generate' to update the generated file.`);
+  }
+}
+__name(cleanup, "cleanup");
+function escapeRegex(str) {
+  return str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+__name(escapeRegex, "escapeRegex");
+function createIsEnabledCallPattern(value) {
+  const target = escapeRegex(value);
+  return new RegExp(String.raw`(?:\b(?:this|[A-Za-z_$][\w$]*)(?:(?:\?\.|\.)[A-Za-z_$][\w$]*)*(?:\?\.|\.))?isEnabled\(["']${target}["']\)`, "g");
+}
+__name(createIsEnabledCallPattern, "createIsEnabledCallPattern");
+function replaceArchivedFlagChecks(params) {
+  const patterns = [
+    createIsEnabledCallPattern(params.flag.id),
+    createIsEnabledCallPattern(params.flag.codeKey)
+  ];
+  let nextContent = params.content;
+  let replacements = 0;
+  for (const pattern of patterns) {
+    nextContent = nextContent.replace(pattern, (match) => {
+      replacements++;
+      if (params.dryRun) {
+        console.log(`  [DRY RUN] ${params.filePath}: ${match} \u2192 false`);
+        return match;
+      }
+      return "false";
+    });
+  }
+  return {
+    content: nextContent,
+    replacements
+  };
+}
+__name(replaceArchivedFlagChecks, "replaceArchivedFlagChecks");
+
+// src/cli/parse-args.ts
+function parseArgs(args2) {
+  const result = {};
+  for (const arg of args2) {
+    const keyValueMatch = arg.match(/^--([^=]+)=(.+)$/);
+    if (keyValueMatch) {
+      result[keyValueMatch[1]] = keyValueMatch[2];
+      continue;
+    }
+    const flagMatch = arg.match(/^--(.+)$/);
+    if (flagMatch) {
+      result[flagMatch[1]] = "true";
+    }
+  }
+  return result;
+}
+__name(parseArgs, "parseArgs");
+
+// src/cli.ts
+var [command, ...args] = process.argv.slice(2);
+async function main() {
+  const parsed = parseArgs(args);
+  switch (command) {
+    case "generate":
+      await generate(parsed);
+      break;
+    case "audit":
+      await audit(parsed);
+      break;
+    case "cleanup":
+      await cleanup(parsed);
+      break;
+    default:
+      console.log(`@mergedapp/feature-flags CLI
+
+Usage:
+  merged-ff generate  Generate typed SDK from flag definitions
+  merged-ff audit     Scan codebase for unused/stale flags
+  merged-ff cleanup   Remove stale flag references (interactive)
+
+Options:
+  --api-url=<url>       API base URL
+  --client-key=<key>    API key (or set FEATURE_FLAG_CLIENT_KEY env var)
+  --output=<path>       Output path for generated file (default: ./src/generated/feature-flags.ts)
+  --dir=<path>          Directory to scan (audit/cleanup, default: ./src)
+  --config=<path>       Config file path for generate/audit (default: auto-discover featureflags.config.{json,js,mjs,cjs} from cwd upward)
+  --dry-run             Preview changes without applying (cleanup)
+  --organization-id=<id>  Organization ID (required)
+  --team-id=<id>        Team ID scope`);
+      if (command) {
+        console.error(`
+Unknown command: ${command}`);
+        process.exit(1);
+      }
+  }
+}
+__name(main, "main");
+main().catch((error) => {
+  console.error(error instanceof Error ? error.message : error);
+  process.exit(1);
+});