@mergedapp/feature-flags 0.1.3

package/dist/cjs/react/hooks.js

@@ -0,0 +1,86 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveFlagFromContext = resolveFlagFromContext;
+exports.useFeatureFlagStatus = useFeatureFlagStatus;
+exports.useUntypedFeatureFlag = useUntypedFeatureFlag;
+exports.useUntypedFeatureFlags = useUntypedFeatureFlags;
+exports.useUntypedFeatureFlagClient = useUntypedFeatureFlagClient;
+exports.createTypedHooks = createTypedHooks;
+const react_1 = require("react");
+const provider_js_1 = require("./provider.js");
+function useFeatureFlagContext() {
+    const context = (0, react_1.useContext)(provider_js_1.FeatureFlagContext);
+    if (!context) {
+        throw new Error("Feature flag hooks and components must be used within a <FeatureFlagProvider>.");
+    }
+    return context;
+}
+function resolveFlagFromContext(params) {
+    return (params.flags.find((flag) => flag.id === params.idOrName || flag.name === params.idOrName) ??
+        params.client.getFlag(params.idOrName));
+}
+function useFeatureFlagStatus() {
+    const { loadState } = useFeatureFlagContext();
+    return loadState;
+}
+function useUntypedFeatureFlag(idOrName) {
+    const { client, flags } = useFeatureFlagContext();
+    const flag = resolveFlagFromContext({ client, flags, idOrName });
+    return { enabled: flag?.enabled ?? false, value: flag?.value };
+}
+function useUntypedFeatureFlags() {
+    const { flags } = useFeatureFlagContext();
+    return flags;
+}
+function useUntypedFeatureFlagClient() {
+    const { client } = useFeatureFlagContext();
+    return client;
+}
+function createTypedHooks() {
+    function TypedFeatureFlagProvider(props) {
+        return (0, provider_js_1.FeatureFlagProvider)(props);
+    }
+    function typedUseFeatureFlag(name) {
+        const { client, flags } = useFeatureFlagContext();
+        const flag = resolveFlagFromContext({ client, flags, idOrName: name });
+        return {
+            enabled: flag?.enabled ?? false,
+            value: flag?.value,
+        };
+    }
+    function typedUseFeatureFlags() {
+        const { flags } = useFeatureFlagContext();
+        return flags;
+    }
+    function typedUseFeatureFlagClient() {
+        const { client } = useFeatureFlagContext();
+        return client;
+    }
+    function typedUseFeatureFlagStatus() {
+        return useFeatureFlagStatus();
+    }
+    const TypedFeatureFlag = (props) => {
+        const { children, fallback, loading, matchValue, name } = props;
+        const status = typedUseFeatureFlagStatus();
+        const { enabled, value } = typedUseFeatureFlag(name);
+        if (status.isLoading) {
+            return loading ?? fallback ?? null;
+        }
+        const shouldRenderChildren = typeof matchValue === "undefined" ? enabled : Object.is(value, matchValue);
+        if (!shouldRenderChildren) {
+            return fallback ?? null;
+        }
+        if (typeof children === "function") {
+            return children({ enabled, value, status });
+        }
+        return children;
+    };
+    return {
+        FeatureFlagProvider: TypedFeatureFlagProvider,
+        FeatureFlag: TypedFeatureFlag,
+        useFeatureFlag: typedUseFeatureFlag,
+        useFeatureFlags: typedUseFeatureFlags,
+        useFeatureFlagClient: typedUseFeatureFlagClient,
+        useFeatureFlagStatus: typedUseFeatureFlagStatus,
+    };
+}

package/dist/cjs/react/provider.js

@@ -0,0 +1,106 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FeatureFlagContext = void 0;
+exports.createFeatureFlagLoadState = createFeatureFlagLoadState;
+exports.shouldRenderFeatureFlagLoadingFallback = shouldRenderFeatureFlagLoadingFallback;
+exports.createSnapshotStore = createSnapshotStore;
+exports.FeatureFlagProvider = FeatureFlagProvider;
+const jsx_runtime_1 = require("react/jsx-runtime");
+const react_1 = require("react");
+exports.FeatureFlagContext = (0, react_1.createContext)(null);
+const EMPTY_EVALUATED_FLAGS = [];
+function createFeatureFlagLoadState(params) {
+    return {
+        status: params.status,
+        isLoading: params.status === "loading",
+        isReady: params.status === "ready",
+        error: params.error ?? params.runtimeStatus.lastError,
+        source: params.runtimeStatus.source,
+        isStale: params.runtimeStatus.isStale,
+        lastSuccessfulRefreshAt: params.runtimeStatus.lastSuccessfulRefreshAt,
+        tokenExpiresAt: params.runtimeStatus.tokenExpiresAt,
+    };
+}
+function shouldRenderFeatureFlagLoadingFallback(params) {
+    return params.blockUntilReady && params.loadState.isLoading;
+}
+function createSnapshotStore(params) {
+    let cachedFlags = params.initialFlags ?? params.client.getSnapshot();
+    let hasObservedClientUpdate = false;
+    function areSnapshotsEqual(left, right) {
+        if (left.length !== right.length) {
+            return false;
+        }
+        for (let index = 0; index < left.length; index++) {
+            const leftFlag = left[index];
+            const rightFlag = right[index];
+            if (leftFlag?.id !== rightFlag?.id ||
+                leftFlag?.name !== rightFlag?.name ||
+                leftFlag?.type !== rightFlag?.type ||
+                leftFlag?.teamId !== rightFlag?.teamId ||
+                leftFlag?.enabled !== rightFlag?.enabled ||
+                JSON.stringify(leftFlag?.value) !== JSON.stringify(rightFlag?.value)) {
+                return false;
+            }
+        }
+        return true;
+    }
+    return {
+        subscribe(onStoreChange) {
+            return params.client.subscribe(() => {
+                hasObservedClientUpdate = true;
+                onStoreChange();
+            });
+        },
+        getSnapshot() {
+            const current = params.client.getSnapshot();
+            const shouldAdoptClientSnapshot = current.length > 0 || !params.initialFlags || hasObservedClientUpdate;
+            if (shouldAdoptClientSnapshot && !areSnapshotsEqual(current, cachedFlags)) {
+                cachedFlags = current;
+            }
+            return cachedFlags;
+        },
+        getServerSnapshot() {
+            return params.initialFlags ?? EMPTY_EVALUATED_FLAGS;
+        },
+    };
+}
+function FeatureFlagProvider(props) {
+    const { client, blockUntilReady, loadingFallback, initialFlags, children } = props;
+    const [status, setStatus] = (0, react_1.useState)(initialFlags ? "ready" : "loading");
+    const [error, setError] = (0, react_1.useState)(null);
+    (0, react_1.useEffect)(() => {
+        let isDisposed = false;
+        setStatus(initialFlags ? "ready" : "loading");
+        setError(null);
+        client.initialize()
+            .then(() => {
+            if (isDisposed) {
+                return;
+            }
+            setStatus("ready");
+        })
+            .catch((initializationError) => {
+            if (isDisposed) {
+                return;
+            }
+            setStatus("error");
+            setError(initializationError instanceof Error
+                ? initializationError
+                : new Error("Unknown feature flag initialization error."));
+        });
+        return () => {
+            isDisposed = true;
+            client.destroy();
+        };
+    }, [client, initialFlags]);
+    const snapshotStore = (0, react_1.useMemo)(() => createSnapshotStore({ client, initialFlags }), [client, initialFlags]);
+    const flags = (0, react_1.useSyncExternalStore)(snapshotStore.subscribe, snapshotStore.getSnapshot, snapshotStore.getServerSnapshot);
+    const runtimeStatus = (0, react_1.useSyncExternalStore)(client.subscribe, client.getStatus.bind(client), client.getStatus.bind(client));
+    const loadState = (0, react_1.useMemo)(() => createFeatureFlagLoadState({ status, error, runtimeStatus }), [error, runtimeStatus, status]);
+    const value = (0, react_1.useMemo)(() => ({ client, flags, loadState }), [client, flags, loadState]);
+    if (shouldRenderFeatureFlagLoadingFallback({ blockUntilReady, loadState })) {
+        return (0, jsx_runtime_1.jsx)(jsx_runtime_1.Fragment, { children: loadingFallback ?? null });
+    }
+    return (0, jsx_runtime_1.jsx)(exports.FeatureFlagContext.Provider, { value: value, children: children });
+}

package/dist/cjs/react.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createTypedHooks = exports.FeatureFlagProvider = void 0;
+var provider_js_1 = require("./react/provider.js");
+Object.defineProperty(exports, "FeatureFlagProvider", { enumerable: true, get: function () { return provider_js_1.FeatureFlagProvider; } });
+var hooks_js_1 = require("./react/hooks.js");
+Object.defineProperty(exports, "createTypedHooks", { enumerable: true, get: function () { return hooks_js_1.createTypedHooks; } });

package/dist/cjs/remote-evaluator.js

@@ -0,0 +1,162 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RemoteFeatureFlagEvaluator = void 0;
+const errors_js_1 = require("./errors.js");
+const jwt_js_1 = require("./jwt.js");
+const persistence_js_1 = require("./persistence.js");
+const REMOTE_FETCH_TIMEOUT_MS = 5_000;
+class RemoteFeatureFlagEvaluator {
+    publicKeyPem;
+    publicKeyCrypto = null;
+    evaluationCache = new Map();
+    inflightEvaluations = new Map();
+    apiUrl;
+    clientKey;
+    organizationId;
+    environmentId;
+    teamId;
+    constructor(config) {
+        this.apiUrl = config.apiUrl.replace(/\/$/, "");
+        this.clientKey = config.clientKey;
+        this.organizationId = config.organizationId.trim();
+        this.environmentId = config.environmentId.trim();
+        this.teamId = config.teamId?.trim() || null;
+        this.publicKeyPem = config.publicKey ?? null;
+    }
+    async evaluate(context) {
+        const contextKey = (0, persistence_js_1.serializeCanonicalValue)(context ?? null);
+        const cached = this.evaluationCache.get(contextKey);
+        if (cached && this.isCachedEvaluationValid(cached)) {
+            return cached;
+        }
+        if (cached) {
+            this.evaluationCache.delete(contextKey);
+        }
+        const inflight = this.inflightEvaluations.get(contextKey);
+        if (inflight) {
+            return inflight;
+        }
+        const evaluationPromise = this.evaluateUncached(context).finally(() => {
+            this.inflightEvaluations.delete(contextKey);
+        });
+        this.inflightEvaluations.set(contextKey, evaluationPromise);
+        const evaluation = await evaluationPromise;
+        if (this.isCachedEvaluationValid(evaluation)) {
+            this.evaluationCache.set(contextKey, evaluation);
+        }
+        else {
+            this.evaluationCache.delete(contextKey);
+        }
+        return evaluation;
+    }
+    async evaluateUncached(context) {
+        await this.ensureVerificationKey();
+        const response = await this.fetchSignedFlags(context ?? null);
+        const verified = await this.verifyWithRetry(response.token);
+        return {
+            expiresAt: verified.expiresAt,
+            fetchedAt: new Date().toISOString(),
+            flags: verified.flags,
+        };
+    }
+    isCachedEvaluationValid(evaluation) {
+        if (!evaluation.expiresAt) {
+            return false;
+        }
+        const expiresAt = new Date(evaluation.expiresAt).getTime();
+        return Number.isFinite(expiresAt) && expiresAt > Date.now();
+    }
+    async fetchSignedFlags(context) {
+        const url = new URL("/api/feature-flags/evaluate/signed", this.apiUrl);
+        const payload = {
+            organizationId: this.organizationId,
+            environmentId: this.environmentId,
+            ...(this.teamId ? { teamId: this.teamId } : {}),
+            ...(context ? { context } : {}),
+        };
+        let response;
+        try {
+            response = await this.fetchWithTimeout(url, {
+                method: "POST",
+                headers: {
+                    Authorization: `Bearer ${this.clientKey}`,
+                    "Content-Type": "application/json",
+                    Accept: "application/json",
+                },
+                body: JSON.stringify(payload),
+            });
+        }
+        catch (error) {
+            if (error instanceof errors_js_1.FeatureFlagNetworkError) {
+                throw error;
+            }
+            throw new errors_js_1.FeatureFlagNetworkError("Failed to fetch feature flags.", { cause: error });
+        }
+        if (!response.ok) {
+            throw new errors_js_1.FeatureFlagNetworkError(`Feature flag API returned ${response.status}: ${response.statusText}`);
+        }
+        return (await response.json());
+    }
+    async fetchPublicKey() {
+        const url = `${this.apiUrl}/api/feature-flags/public-key`;
+        let response;
+        try {
+            response = await this.fetchWithTimeout(url);
+        }
+        catch (error) {
+            if (error instanceof errors_js_1.FeatureFlagNetworkError) {
+                throw error;
+            }
+            throw new errors_js_1.FeatureFlagNetworkError("Failed to fetch public key.", { cause: error });
+        }
+        if (!response.ok) {
+            throw new errors_js_1.FeatureFlagNetworkError(`Public key endpoint returned ${response.status}: ${response.statusText}`);
+        }
+        const body = (await response.json());
+        return body.publicKey;
+    }
+    async verifyWithRetry(token) {
+        try {
+            return await (0, jwt_js_1.verifyFeatureFlagTokenDetailed)({ token, publicKey: this.publicKeyCrypto });
+        }
+        catch (error) {
+            if (!(error instanceof errors_js_1.FeatureFlagVerificationError)) {
+                throw error;
+            }
+            (0, jwt_js_1.resetPublicKeyCache)();
+            this.publicKeyPem = await this.fetchPublicKey();
+            this.publicKeyCrypto = await (0, jwt_js_1.importPublicKey)(this.publicKeyPem);
+            return (0, jwt_js_1.verifyFeatureFlagTokenDetailed)({ token, publicKey: this.publicKeyCrypto });
+        }
+    }
+    async ensureVerificationKey() {
+        if (!this.publicKeyPem) {
+            this.publicKeyPem = await this.fetchPublicKey();
+        }
+        if (!this.publicKeyCrypto) {
+            this.publicKeyCrypto = await (0, jwt_js_1.importPublicKey)(this.publicKeyPem);
+        }
+    }
+    async fetchWithTimeout(input, init) {
+        const controller = new AbortController();
+        const timeout = setTimeout(() => {
+            controller.abort();
+        }, REMOTE_FETCH_TIMEOUT_MS);
+        try {
+            return await fetch(input, {
+                ...init,
+                signal: controller.signal,
+            });
+        }
+        catch (error) {
+            if (error instanceof Error && error.name === "AbortError") {
+                throw new errors_js_1.FeatureFlagNetworkError(`Feature flag request timed out after ${REMOTE_FETCH_TIMEOUT_MS}ms.`, { cause: error });
+            }
+            throw error;
+        }
+        finally {
+            clearTimeout(timeout);
+        }
+    }
+}
+exports.RemoteFeatureFlagEvaluator = RemoteFeatureFlagEvaluator;

package/dist/cjs/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/cli/audit.d.ts

@@ -0,0 +1,3 @@
+type AuditArgs = Record<string, string>;
+export declare function audit(args: AuditArgs): Promise<void>;
+export {};

package/dist/cli/audit.js

@@ -0,0 +1,114 @@
+import { readFile, readdir } from "node:fs/promises";
+import { resolve, join, extname } from "node:path";
+import { FeatureFlagCliConfigLoader } from "./config-loader.js";
+const CODE_EXTENSIONS = 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;
+}
+async function fetchDefinitions(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;
+}
+export async function audit(args) {
+    const dir = resolve(args.dir ?? "./src");
+    const loadedConfig = await FeatureFlagCliConfigLoader.load({ configPath: args.config });
+    const config = loadedConfig.config;
+    const apiUrl = args["api-url"] ?? config.apiUrl ?? process.env.FEATURE_FLAG_API_URL;
+    const clientKey = args["client-key"] ?? config.clientKey ?? process.env.FEATURE_FLAG_CLIENT_KEY;
+    const organizationId = args["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 fetchDefinitions({ 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 = new Set();
+    const referencedCodeKeys = new Set();
+    for (const file of files) {
+        const content = await readFile(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 = 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(`\nDefined 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(`\nArchived but still referenced in code (${archivedButReferenced.length}):`);
+        for (const d of archivedButReferenced) {
+            console.log(`  [STALE] ${d.codeKey} (${d.id}) — archived, needs cleanup`);
+        }
+    }
+    if (unused.length === 0 && archivedButReferenced.length === 0) {
+        console.log("\nAll flags are clean.");
+    }
+    console.log(`\nScanned ${files.length} files in ${dir}.`);
+}

package/dist/cli/cleanup.d.ts

@@ -0,0 +1,3 @@
+type CleanupArgs = Record<string, string>;
+export declare function cleanup(args: CleanupArgs): Promise<void>;
+export {};

package/dist/cli/cleanup.js

@@ -0,0 +1,102 @@
+import { readFile, writeFile, readdir } from "node:fs/promises";
+import { resolve, join, extname } from "node:path";
+const CODE_EXTENSIONS = 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;
+}
+async function fetchDefinitions(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;
+}
+export async function cleanup(args) {
+    const dir = resolve(args.dir ?? "./src");
+    const dryRun = "dry-run" in args;
+    const apiUrl = args["api-url"] ?? process.env.FEATURE_FLAG_API_URL;
+    const clientKey = args["client-key"] ?? process.env.FEATURE_FLAG_CLIENT_KEY;
+    const organizationId = args["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 fetchDefinitions({ 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 collectFiles(dir);
+    let totalReplacements = 0;
+    for (const filePath of files) {
+        let content = await readFile(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 writeFile(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(`\n${totalReplacements} replacement(s) would be made. Re-run without --dry-run to apply.`);
+    }
+    else {
+        console.log(`\n${totalReplacements} replacement(s) applied. Run 'merged-ff generate' to update the generated file.`);
+    }
+}
+function escapeRegex(str) {
+    return str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+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");
+}
+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} → false`);
+                return match;
+            }
+            return "false";
+        });
+    }
+    return { content: nextContent, replacements };
+}

package/dist/cli/config-loader.d.ts

@@ -0,0 +1,26 @@
+export type FeatureFlagCliConfig = {
+    $schema?: string;
+    apiUrl?: string;
+    clientKey?: string;
+    environmentId?: string;
+    outputPath?: string;
+    teamId?: string;
+    organizationId?: string;
+};
+type LoadedFeatureFlagCliConfig = {
+    config: FeatureFlagCliConfig;
+    configPath: string | null;
+};
+declare function load(params: {
+    configPath?: string;
+    cwd?: string;
+}): Promise<LoadedFeatureFlagCliConfig>;
+declare function resolveConfigRelativePath(params: {
+    value?: string;
+    configPath?: string | null;
+}): string | undefined;
+export declare const FeatureFlagCliConfigLoader: {
+    load: typeof load;
+    resolveConfigRelativePath: typeof resolveConfigRelativePath;
+};
+export {};

package/dist/cli/config-loader.js

@@ -0,0 +1,66 @@
+import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { dirname, isAbsolute, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+const 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 });
+}
+function resolveConfigRelativePath(params) {
+    if (!params.value) {
+        return undefined;
+    }
+    if (isAbsolute(params.value) || !params.configPath) {
+        return params.value;
+    }
+    return resolve(dirname(params.configPath), params.value);
+}
+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;
+    }
+}
+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 };
+}
+export const FeatureFlagCliConfigLoader = {
+    load,
+    resolveConfigRelativePath,
+};