@quonfig/cli 0.0.47 → 0.0.49

package/dist/migrate/quonfig-target/ruleset.js

@@ -0,0 +1,192 @@
+/**
+ * Shared verb: collapse a provider's targeting model into Quonfig's ordered,
+ * first-match-wins rule list.
+ *
+ * Part of the `quonfig-target/` verb library (plan §3.1, D1). The hard part of
+ * every converter is topology translation into Quonfig's specific shape — no
+ * "flag off" toggle, no individual-target primitive, no within-rule OR. These
+ * verbs do the LaunchDarkly collapse; a second provider with a different
+ * topology composes them differently.
+ */
+import { mapLaunchDarklyOperator } from './operators.js';
+import { toQuonfigValue } from './values.js';
+const ALWAYS_TRUE = { operator: 'ALWAYS_TRUE' };
+/** Operators whose `valueToMatch` is a `string_list` of every clause value. */
+const STRING_LIST_OPERATORS = new Set([
+    'PROP_CONTAINS_ONE_OF',
+    'PROP_DOES_NOT_CONTAIN_ONE_OF',
+    'PROP_DOES_NOT_END_WITH_ONE_OF',
+    'PROP_DOES_NOT_START_WITH_ONE_OF',
+    'PROP_ENDS_WITH_ONE_OF',
+    'PROP_IS_NOT_ONE_OF',
+    'PROP_IS_ONE_OF',
+    'PROP_STARTS_WITH_ONE_OF',
+]);
+const NUMERIC_OPERATORS = new Set([
+    'PROP_GREATER_THAN',
+    'PROP_GREATER_THAN_OR_EQUAL',
+    'PROP_LESS_THAN',
+    'PROP_LESS_THAN_OR_EQUAL',
+]);
+/**
+ * LaunchDarkly attribute → Quonfig property name. The context kind becomes a
+ * namespace prefix (plan §5.1: `organization` + `plan` → `organization.plan`),
+ * defaulting to `user`. A nested JSON-pointer attribute (`/address/city`)
+ * becomes a dotted path (`address.city`).
+ */
+export function normalizeAttribute(contextKind, attribute) {
+    const kind = contextKind && contextKind.length > 0 ? contextKind : 'user';
+    const dotted = attribute.replace(/^\//, '').replaceAll('/', '.');
+    return `${kind}.${dotted}`;
+}
+/** Build a `valueToMatch` typed value for a non-presence, non-segment clause. */
+function valueToMatchFor(operator, clause, ctx) {
+    if (STRING_LIST_OPERATORS.has(operator)) {
+        return { type: 'string_list', value: clause.values.map(String) };
+    }
+    if (operator === 'IN_SEG' || operator === 'NOT_IN_SEG') {
+        if (clause.values.length > 1) {
+            ctx.report.add('skipped-rule', ctx.sourceKey, `segmentMatch clause listed ${clause.values.length} segments; Quonfig IN_SEG matches one — only "${String(clause.values[0])}" kept, the rest dropped`);
+        }
+        return { type: 'string', value: String(clause.values[0] ?? '') };
+    }
+    if (operator === 'PROP_MATCHES' || operator === 'PROP_DOES_NOT_MATCH') {
+        if (clause.values.length > 1) {
+            ctx.report.add('skipped-rule', ctx.sourceKey, `regex clause listed ${clause.values.length} patterns; Quonfig PROP_MATCHES takes one — only the first kept`);
+        }
+        return { type: 'string', value: String(clause.values[0] ?? '') };
+    }
+    if (NUMERIC_OPERATORS.has(operator)) {
+        const raw = clause.values[0];
+        const num = typeof raw === 'number' ? raw : Number(raw);
+        return { type: Number.isInteger(num) ? 'int' : 'double', value: num };
+    }
+    if (operator === 'PROP_BEFORE' || operator === 'PROP_AFTER') {
+        const raw = clause.values[0];
+        // LD before/after take an epoch-ms number or an RFC3339 string; the SDK's
+        // dateToMillis accepts both, so pass the native shape straight through.
+        return typeof raw === 'number' ? { type: 'int', value: raw } : { type: 'string', value: String(raw) };
+    }
+    // Semver operators — the SDK requires a string value.
+    return { type: 'string', value: String(clause.values[0] ?? '') };
+}
+/**
+ * Map one provider clause to a Quonfig criterion, or `null` when the clause's
+ * operator has no v1 mapping (D3 — negated comparisons, applicationVersion…).
+ * A null result means the whole containing rule must be dropped: keeping a
+ * partial AND would silently broaden targeting.
+ */
+export function clauseToCriterion(clause, ctx) {
+    const mapping = mapLaunchDarklyOperator(clause.op, Boolean(clause.negate));
+    if ('skip' in mapping) {
+        ctx.report.add('skipped-rule', ctx.sourceKey, `clause on "${clause.attribute}" skipped: ${mapping.reason}`);
+        return null;
+    }
+    const { operator } = mapping;
+    const propertyName = normalizeAttribute(clause.contextKind, clause.attribute);
+    const criterion = { operator, propertyName };
+    criterion.valueToMatch = valueToMatchFor(operator, clause, ctx);
+    return criterion;
+}
+/**
+ * Build a Quonfig rule from a provider rule's clauses (AND semantics) plus its
+ * served value. Returns `null` when any clause cannot be mapped — the rule is
+ * dropped wholesale and reported, rather than silently broadened.
+ */
+export function buildRule(clauses, value, ctx) {
+    const criteria = [];
+    for (const clause of clauses) {
+        const criterion = clauseToCriterion(clause, ctx);
+        if (criterion === null)
+            return null;
+        criteria.push(criterion);
+    }
+    // A rule with no clauses matches everyone — represent that as ALWAYS_TRUE.
+    return { criteria: criteria.length > 0 ? criteria : [ALWAYS_TRUE], value };
+}
+/** Resolve a variation index to its typed Quonfig value. */
+function variationValue(index, ctx) {
+    const raw = ctx.variationValues[index];
+    return toQuonfigValue(raw, ctx.valueType);
+}
+/**
+ * Convert a provider rollout to a Quonfig `weighted_values`. The experiment
+ * framing (`kind: "experiment"` + `seed`) is dropped + reported (plan §5.4),
+ * and every rollout is recorded as re-bucketing (LD and Quonfig hash
+ * differently, so post-migration bucket assignments differ).
+ */
+export function rolloutToWeightedValues(rollout, ctx) {
+    if (rollout.kind === 'experiment') {
+        ctx.report.add('dropped-experiment-metadata', ctx.sourceKey, `experiment rollout converted to a plain weighted_values; experiment kind${rollout.seed === undefined ? '' : ` and seed ${rollout.seed}`} dropped`);
+    }
+    const hashByPropertyName = rollout.bucketBy
+        ? normalizeAttribute(rollout.contextKind, rollout.bucketBy)
+        : `${rollout.contextKind && rollout.contextKind.length > 0 ? rollout.contextKind : 'user'}.key`;
+    ctx.report.add('rebucketed-rollout', ctx.sourceKey, `percentage rollout hashed on "${hashByPropertyName}" — LaunchDarkly and Quonfig bucket differently, so users will be re-bucketed`);
+    return {
+        type: 'weighted_values',
+        value: {
+            hashByPropertyName,
+            weightedValues: rollout.variations.map((wv) => ({
+                value: variationValue(wv.variation, ctx),
+                weight: wv.weight,
+            })),
+        },
+    };
+}
+/** Resolve a `variation`-or-`rollout` pointer (rule served value / fallthrough). */
+export function servedValue(voR, ctx) {
+    if (voR.rollout)
+        return rolloutToWeightedValues(voR.rollout, ctx);
+    return variationValue(voR.variation ?? 0, ctx);
+}
+/**
+ * Collapse a single LaunchDarkly per-environment flag state into an ordered,
+ * first-match-wins Quonfig rule list.
+ *
+ *  - `on: false` → one ALWAYS_TRUE rule serving the `offVariation` value.
+ *  - `on: true`  → individual/context targets become leading PROP_IS_ONE_OF
+ *    rules; `rules[]` translate in order; `fallthrough` becomes a trailing
+ *    ALWAYS_TRUE rule. Prerequisites are dropped + reported (no Quonfig
+ *    cross-flag dependency operator in v1).
+ */
+export function collapseEnvironment(env, ctx) {
+    if (!env.on) {
+        return [{ criteria: [ALWAYS_TRUE], value: variationValue(env.offVariation ?? 0, ctx) }];
+    }
+    const rules = [];
+    if (env.prerequisites && env.prerequisites.length > 0) {
+        ctx.report.add('dropped-prerequisite', ctx.sourceKey, `${env.prerequisites.length} prerequisite(s) dropped (${env.prerequisites
+            .map((p) => p.key)
+            .join(', ')}) — Quonfig has no cross-flag dependency operator`);
+    }
+    // Individual + context targets evaluate before rules in LaunchDarkly, so
+    // they become leading rules. Lossy: the LD UI affordance is gone (plan §5.4).
+    const allTargets = [...(env.targets ?? []), ...(env.contextTargets ?? [])];
+    for (const target of allTargets) {
+        if (target.values.length === 0)
+            continue;
+        const kind = target.contextKind && target.contextKind.length > 0 ? target.contextKind : 'user';
+        rules.push({
+            criteria: [
+                {
+                    operator: 'PROP_IS_ONE_OF',
+                    propertyName: `${kind}.key`,
+                    valueToMatch: { type: 'string_list', value: [...target.values] },
+                },
+            ],
+            value: variationValue(target.variation, ctx),
+        });
+        ctx.report.add('individual-target-as-rule', ctx.sourceKey, `${target.values.length} ${kind} target(s) converted to a leading PROP_IS_ONE_OF rule on ${kind}.key`);
+    }
+    for (const rule of env.rules ?? []) {
+        const value = rule.rollout === undefined ? variationValue(rule.variation ?? 0, ctx) : rolloutToWeightedValues(rule.rollout, ctx);
+        const built = buildRule(rule.clauses, value, ctx);
+        if (built !== null)
+            rules.push(built);
+    }
+    if (env.fallthrough) {
+        rules.push({ criteria: [ALWAYS_TRUE], value: servedValue(env.fallthrough, ctx) });
+    }
+    return rules;
+}

package/dist/migrate/quonfig-target/values.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Shared verb: provider variation value → typed Quonfig `{type, value}`.
+ *
+ * Part of the `quonfig-target/` verb library (plan §3.1, D1). Quonfig values
+ * are a discriminated union on `type`; this verb infers the type from the raw
+ * JSON a provider hands us and the flag's declared value type.
+ */
+/** A Quonfig value type — mirrors `ValueTypeSchema` in app-quonfig's config-schemas.ts. */
+export type QuonfigValueType = 'bool' | 'double' | 'int' | 'json' | 'string' | 'string_list';
+/** A typed Quonfig value object as it appears in stored config JSON. */
+export interface QuonfigValue {
+    type: QuonfigValueType;
+    value: unknown;
+}
+/**
+ * Infer the Quonfig value type for a single raw value.
+ *  - boolean → bool
+ *  - integer number → int; non-integer number → double
+ *  - string → string
+ *  - object / array → json
+ */
+export declare function inferValueType(raw: unknown): QuonfigValueType;
+/**
+ * Infer the value type for a whole flag from its variation values.
+ *
+ * LaunchDarkly boolean flags are unambiguously `bool`. For multivariate flags
+ * the variations are homogeneous in practice; we widen `int` → `double` if any
+ * variation is fractional so a flag with `[0, 1, 2.5]` lands on `double`
+ * rather than silently truncating.
+ */
+export declare function inferFlagValueType(kind: string, variationValues: unknown[]): QuonfigValueType;
+/**
+ * Coerce a raw provider value into a typed Quonfig value object under the
+ * flag's declared value type. The declared type wins — a `double` flag whose
+ * variation happens to be `2` still serializes as `{type: 'double', value: 2}`
+ * so the stored config is internally consistent.
+ */
+export declare function toQuonfigValue(raw: unknown, valueType: QuonfigValueType): QuonfigValue;

package/dist/migrate/quonfig-target/values.js

@@ -0,0 +1,77 @@
+/**
+ * Shared verb: provider variation value → typed Quonfig `{type, value}`.
+ *
+ * Part of the `quonfig-target/` verb library (plan §3.1, D1). Quonfig values
+ * are a discriminated union on `type`; this verb infers the type from the raw
+ * JSON a provider hands us and the flag's declared value type.
+ */
+/**
+ * Infer the Quonfig value type for a single raw value.
+ *  - boolean → bool
+ *  - integer number → int; non-integer number → double
+ *  - string → string
+ *  - object / array → json
+ */
+export function inferValueType(raw) {
+    if (typeof raw === 'boolean')
+        return 'bool';
+    if (typeof raw === 'number')
+        return Number.isInteger(raw) ? 'int' : 'double';
+    if (typeof raw === 'string')
+        return 'string';
+    // null, objects, and arrays all serialize as Quonfig `json`.
+    return 'json';
+}
+/**
+ * Infer the value type for a whole flag from its variation values.
+ *
+ * LaunchDarkly boolean flags are unambiguously `bool`. For multivariate flags
+ * the variations are homogeneous in practice; we widen `int` → `double` if any
+ * variation is fractional so a flag with `[0, 1, 2.5]` lands on `double`
+ * rather than silently truncating.
+ */
+export function inferFlagValueType(kind, variationValues) {
+    if (kind === 'boolean')
+        return 'bool';
+    if (variationValues.length === 0)
+        return 'string';
+    const types = variationValues.map((v) => inferValueType(v));
+    if (types.every((t) => t === 'bool'))
+        return 'bool';
+    if (types.every((t) => t === 'int' || t === 'double')) {
+        return types.includes('double') ? 'double' : 'int';
+    }
+    if (types.every((t) => t === 'string'))
+        return 'string';
+    // Mixed or object/array variations → json (json can hold any of them).
+    return 'json';
+}
+/**
+ * Coerce a raw provider value into a typed Quonfig value object under the
+ * flag's declared value type. The declared type wins — a `double` flag whose
+ * variation happens to be `2` still serializes as `{type: 'double', value: 2}`
+ * so the stored config is internally consistent.
+ */
+export function toQuonfigValue(raw, valueType) {
+    switch (valueType) {
+        case 'bool': {
+            return { type: 'bool', value: Boolean(raw) };
+        }
+        case 'double':
+        case 'int': {
+            return { type: valueType, value: typeof raw === 'number' ? raw : Number(raw) };
+        }
+        case 'json': {
+            return { type: 'json', value: raw };
+        }
+        case 'string_list': {
+            return { type: 'string_list', value: Array.isArray(raw) ? raw.map(String) : [] };
+        }
+        case 'string': {
+            return { type: 'string', value: typeof raw === 'string' ? raw : String(raw) };
+        }
+        default: {
+            return { type: 'string', value: String(raw) };
+        }
+    }
+}

package/dist/migrate/source-api-key.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Decision D8 (project/plans/migrator-launch-darkly.md §9.1): the `qfg migrate`
+ * command's API-key flag is generalized from the launch-specific `--api-key` /
+ * `LAUNCH_API_KEY` into a provider-agnostic `--source-api-key` /
+ * `QUONFIG_MIGRATE_API_KEY`, with a per-provider env fallback. `--api-key` /
+ * `LAUNCH_API_KEY` stay as deprecated aliases for the `launch` source.
+ *
+ * Precedence (highest first):
+ *   1. `--source-api-key` flag   (oclif also fills it from QUONFIG_MIGRATE_API_KEY)
+ *   2. `--api-key` flag          (oclif also fills it from LAUNCH_API_KEY; deprecated)
+ *   3. per-provider env var      (LAUNCHDARKLY_API_KEY, FLAGSMITH_API_KEY, ...)
+ */
+/**
+ * Per-provider env-var fallback, lowest precedence. Keyed by `--from` value so
+ * every supported source has an obvious, source-named env var. `launch`'s entry
+ * is redundant with the `--api-key` flag's own `env: LAUNCH_API_KEY` binding,
+ * but is kept so the map is a complete record of every provider's env var.
+ */
+export declare const PROVIDER_API_KEY_ENV: Record<string, string>;
+export interface SourceApiKeyInput {
+    /** `--api-key` flag value (oclif also fills this from LAUNCH_API_KEY). Deprecated alias. */
+    apiKeyFlag?: string;
+    /** Process env, injectable for tests. Defaults to `process.env`. */
+    env?: NodeJS.ProcessEnv;
+    /** `--from` value — selects the per-provider env-var fallback. */
+    from: string;
+    /** `--source-api-key` flag value (oclif also fills this from QUONFIG_MIGRATE_API_KEY). */
+    sourceApiKeyFlag?: string;
+}
+/** Resolve the source API key from flags + env, or `undefined` if none is configured. */
+export declare function resolveSourceApiKey(input: SourceApiKeyInput): string | undefined;
+/** One-line guidance for the "no key configured" error, naming every accepted input. */
+export declare function missingSourceApiKeyMessage(from: string): string;

package/dist/migrate/source-api-key.js

@@ -0,0 +1,43 @@
+/**
+ * Decision D8 (project/plans/migrator-launch-darkly.md §9.1): the `qfg migrate`
+ * command's API-key flag is generalized from the launch-specific `--api-key` /
+ * `LAUNCH_API_KEY` into a provider-agnostic `--source-api-key` /
+ * `QUONFIG_MIGRATE_API_KEY`, with a per-provider env fallback. `--api-key` /
+ * `LAUNCH_API_KEY` stay as deprecated aliases for the `launch` source.
+ *
+ * Precedence (highest first):
+ *   1. `--source-api-key` flag   (oclif also fills it from QUONFIG_MIGRATE_API_KEY)
+ *   2. `--api-key` flag          (oclif also fills it from LAUNCH_API_KEY; deprecated)
+ *   3. per-provider env var      (LAUNCHDARKLY_API_KEY, FLAGSMITH_API_KEY, ...)
+ */
+/**
+ * Per-provider env-var fallback, lowest precedence. Keyed by `--from` value so
+ * every supported source has an obvious, source-named env var. `launch`'s entry
+ * is redundant with the `--api-key` flag's own `env: LAUNCH_API_KEY` binding,
+ * but is kept so the map is a complete record of every provider's env var.
+ */
+export const PROVIDER_API_KEY_ENV = {
+    flagsmith: 'FLAGSMITH_API_KEY',
+    launch: 'LAUNCH_API_KEY',
+    launchdarkly: 'LAUNCHDARKLY_API_KEY',
+};
+/** Resolve the source API key from flags + env, or `undefined` if none is configured. */
+export function resolveSourceApiKey(input) {
+    if (input.sourceApiKeyFlag)
+        return input.sourceApiKeyFlag;
+    if (input.apiKeyFlag)
+        return input.apiKeyFlag;
+    const env = input.env ?? process.env;
+    const providerEnv = PROVIDER_API_KEY_ENV[input.from];
+    if (providerEnv && env[providerEnv])
+        return env[providerEnv];
+    return undefined;
+}
+/** One-line guidance for the "no key configured" error, naming every accepted input. */
+export function missingSourceApiKeyMessage(from) {
+    const providerEnv = PROVIDER_API_KEY_ENV[from];
+    const providerHint = providerEnv ? ` For --from ${from} you can also set ${providerEnv}.` : '';
+    return ('--source-api-key is required (or set QUONFIG_MIGRATE_API_KEY).' +
+        providerHint +
+        ' The legacy --api-key / LAUNCH_API_KEY flag still works for --from launch.');
+}

package/dist/migrate/source.d.ts

@@ -1,3 +1,4 @@
+import type { ConversionNote } from './quonfig-target/report.js';
 export interface LegacyChange {
     changedAt?: number;
     key?: string;
@@ -88,6 +89,15 @@ export interface MigrationSource {
      * synthesized entries) and the caller should fall back to the migrator identity.
      */
     getCommitMeta?(change: LegacyChange): CommitMeta | null;
+    /**
+     * Optional post-translate accumulator. Returns the structured conversion notes
+     * collected during translate() — re-bucketed rollouts, dropped prerequisites,
+     * lossy individual-target conversions, etc. (the LaunchDarkly converter set).
+     * The write paths thread these into MIGRATION_REPORT.md's "Users will be
+     * re-bucketed" + "Conversion notes" sections. Null or empty when nothing
+     * notable happened during conversion.
+     */
+    getConversionNotes?(): ConversionNote[] | null;
     /**
      * Optional post-translate accumulator. Returns any override sections that were
      * dropped during translate() calls because the env.id was not present in the

package/dist/migrate/sources/launchdarkly/api.d.ts

@@ -0,0 +1,59 @@
+/**
+ * LaunchDarkly REST API client — Phase-1 config snapshot.
+ *
+ * LaunchDarkly has no bulk "export everything" endpoint, so the fetcher
+ * stitches per-resource calls: environments, context-kinds, flags (full
+ * per-env targeting via `?summary=0&env=`), and segments (per environment).
+ *
+ * Auth is a raw API token in the `Authorization` header — no `Bearer` prefix.
+ * Rate limiting is a per-account rolling 10-second window with an unpublished
+ * limit, so we program against the headers: back off on 429 using
+ * `X-Ratelimit-Reset` (epoch-ms), pre-throttle on `X-Ratelimit-Global-Remaining`.
+ */
+import type { LDFlag, LDSegment, LDSnapshot } from './types.js';
+export declare function setLaunchDarklyBaseUrl(url: string): void;
+export declare function selectLaunchDarklyBaseUrl(): string;
+export declare function applyLaunchDarklyBaseUrl(): void;
+export declare function __setSleepForTests(fn: (ms: number) => Promise<void>): void;
+export declare function __resetSleepForTests(): void;
+export declare class LaunchDarklyApiError extends Error {
+    readonly status: number;
+    constructor(status: number, statusText: string, url: string, body: string);
+}
+/**
+ * Single GET with header auth, 429 backoff against `X-Ratelimit-Reset`, and a
+ * pre-throttle when `X-Ratelimit-Global-Remaining` runs low. Non-429 errors
+ * throw immediately — only rate limiting is retried.
+ *
+ * Exported so the Phase-2 audit-log walker (`audit.ts`) reuses the exact same
+ * rate-limit handling — `/auditlog` is account-wide and the slowest endpoint,
+ * so it must not bypass the shared 429 backoff.
+ */
+export declare function apiFetch(path: string, apiKey: string): Promise<unknown>;
+/** Probe used by `validateAuth` — a cheap authenticated call that 401s on a bad token. */
+export declare function fetchProjectEnvironments(apiKey: string, projectKey: string): Promise<string[]>;
+export declare function fetchContextKinds(apiKey: string, projectKey: string): Promise<string[]>;
+/**
+ * Full per-environment flag targeting. `?summary=0` plus repeated `?env=`
+ * returns rules, clauses, targets, fallthrough, offVariation, prerequisites
+ * and rollouts for every named environment in one response — there is no
+ * "all environments" wildcard, so env keys are templated in explicitly.
+ *
+ * `opts.archived` flips the list to *only* archived flags. LaunchDarkly's flag
+ * list endpoint hides archived flags by default and has no "both" mode, so a
+ * full picture is two calls. The migration runtime does not want archived flags
+ * (`fetchSnapshot` omits this), but the fixture-corpus exporter needs them so
+ * the `state-archived` edge case is in the canonical corpus.
+ */
+export declare function fetchFlags(apiKey: string, projectKey: string, envKeys: string[], opts?: {
+    archived?: boolean;
+}): Promise<LDFlag[]>;
+/** Segments are a per-environment resource — caller loops env keys and de-dupes. */
+export declare function fetchSegmentsForEnv(apiKey: string, projectKey: string, envKey: string): Promise<LDSegment[]>;
+/**
+ * Stitches the whole Phase-1 snapshot: environments → context-kinds → flags
+ * (one call, all envs) → segments (per env, de-duplicated by key). This is the
+ * ~60-call "fast, lossless for current state" path; it always re-fetches
+ * everything (decision D2 — we do not trust the LD audit cursor for deltas).
+ */
+export declare function fetchSnapshot(apiKey: string, projectKey: string): Promise<LDSnapshot>;

package/dist/migrate/sources/launchdarkly/api.js

@@ -0,0 +1,195 @@
+/**
+ * LaunchDarkly REST API client — Phase-1 config snapshot.
+ *
+ * LaunchDarkly has no bulk "export everything" endpoint, so the fetcher
+ * stitches per-resource calls: environments, context-kinds, flags (full
+ * per-env targeting via `?summary=0&env=`), and segments (per environment).
+ *
+ * Auth is a raw API token in the `Authorization` header — no `Bearer` prefix.
+ * Rate limiting is a per-account rolling 10-second window with an unpublished
+ * limit, so we program against the headers: back off on 429 using
+ * `X-Ratelimit-Reset` (epoch-ms), pre-throttle on `X-Ratelimit-Global-Remaining`.
+ */
+const PROD_BASE_URL = 'https://app.launchdarkly.com/api/v2';
+const PAGE_LIMIT = 20;
+/** Below this many remaining requests we pre-throttle to avoid a 429 storm. */
+const RATE_LIMIT_FLOOR = 5;
+/** Fallback wait when a 429 carries no usable reset header. */
+const DEFAULT_BACKOFF_MS = 2000;
+/** Hard cap on retries for a single request before we give up. */
+const MAX_RETRIES = 6;
+let baseUrl = PROD_BASE_URL;
+export function setLaunchDarklyBaseUrl(url) {
+    baseUrl = url;
+}
+export function selectLaunchDarklyBaseUrl() {
+    return process.env.LAUNCHDARKLY_API_URL ?? PROD_BASE_URL;
+}
+export function applyLaunchDarklyBaseUrl() {
+    baseUrl = selectLaunchDarklyBaseUrl();
+}
+/** Real timer-backed sleep — swapped out in tests so MSW runs don't actually wait. */
+function timerSleep(ms) {
+    return new Promise((resolve) => {
+        setTimeout(resolve, ms);
+    });
+}
+/** Test seam: a no-op sleep is swapped in so MSW tests don't actually wait. */
+let sleepImpl = timerSleep;
+export function __setSleepForTests(fn) {
+    sleepImpl = fn;
+}
+export function __resetSleepForTests() {
+    sleepImpl = timerSleep;
+}
+export class LaunchDarklyApiError extends Error {
+    status;
+    constructor(status, statusText, url, body) {
+        super(`LaunchDarkly API request failed: ${status} ${statusText} — ${url}\n${body}`);
+        this.name = 'LaunchDarklyApiError';
+        this.status = status;
+    }
+}
+/** Wait derived from a 429 response's rate-limit headers. */
+function backoffMsFromHeaders(headers) {
+    const reset = headers.get('X-Ratelimit-Reset');
+    if (reset) {
+        const resetMs = Number(reset);
+        if (Number.isFinite(resetMs)) {
+            // Header is an absolute epoch-ms timestamp; wait until then (clamped ≥ 0).
+            return Math.max(0, resetMs - Date.now());
+        }
+    }
+    return DEFAULT_BACKOFF_MS;
+}
+/**
+ * Single GET with header auth, 429 backoff against `X-Ratelimit-Reset`, and a
+ * pre-throttle when `X-Ratelimit-Global-Remaining` runs low. Non-429 errors
+ * throw immediately — only rate limiting is retried.
+ *
+ * Exported so the Phase-2 audit-log walker (`audit.ts`) reuses the exact same
+ * rate-limit handling — `/auditlog` is account-wide and the slowest endpoint,
+ * so it must not bypass the shared 429 backoff.
+ */
+export async function apiFetch(path, apiKey) {
+    const url = path.startsWith('http') ? path : `${baseUrl}${path}`;
+    for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
+        // eslint-disable-next-line no-await-in-loop
+        const res = await fetch(url, {
+            headers: {
+                Accept: 'application/json',
+                Authorization: apiKey,
+            },
+        });
+        if (res.status === 429) {
+            if (attempt === MAX_RETRIES) {
+                // eslint-disable-next-line no-await-in-loop
+                const body = await res.text().catch(() => '(no body)');
+                throw new LaunchDarklyApiError(429, res.statusText, url, body);
+            }
+            // eslint-disable-next-line no-await-in-loop
+            await sleepImpl(backoffMsFromHeaders(res.headers));
+            continue;
+        }
+        if (!res.ok) {
+            // eslint-disable-next-line no-await-in-loop
+            const body = await res.text().catch(() => '(no body)');
+            throw new LaunchDarklyApiError(res.status, res.statusText, url, body);
+        }
+        // Pre-throttle: if the account-wide budget is nearly spent, pause briefly
+        // before the next call rather than walking straight into a 429.
+        const remaining = res.headers.get('X-Ratelimit-Global-Remaining');
+        if (remaining !== null && Number(remaining) <= RATE_LIMIT_FLOOR) {
+            // eslint-disable-next-line no-await-in-loop
+            await sleepImpl(backoffMsFromHeaders(res.headers));
+        }
+        return res.json();
+    }
+    // Unreachable — the loop either returns or throws.
+    throw new LaunchDarklyApiError(429, 'Too Many Requests', url, 'retries exhausted');
+}
+/**
+ * Walks an offset-paginated collection endpoint. LaunchDarkly returns a
+ * `_links.next.href` while more pages remain; we stop when it is absent or a
+ * short page is returned.
+ */
+async function paginate(firstPath, apiKey) {
+    const collected = [];
+    let path = firstPath;
+    const seen = new Set();
+    while (path && !seen.has(path)) {
+        seen.add(path);
+        // eslint-disable-next-line no-await-in-loop
+        const page = (await apiFetch(path, apiKey));
+        if (Array.isArray(page.items))
+            collected.push(...page.items);
+        const next = page._links?.next?.href;
+        // `next.href` is server-relative ("/api/v2/..."); strip the shared prefix
+        // so it composes with our configurable base URL.
+        path = next ? next.replace(/^\/api\/v2/, '') : undefined;
+        if (page.items.length < PAGE_LIMIT)
+            break;
+    }
+    return collected;
+}
+/** Probe used by `validateAuth` — a cheap authenticated call that 401s on a bad token. */
+export async function fetchProjectEnvironments(apiKey, projectKey) {
+    const items = await paginate(`/projects/${encodeURIComponent(projectKey)}/environments?limit=${PAGE_LIMIT}`, apiKey);
+    return items.map((e) => e.key);
+}
+export async function fetchContextKinds(apiKey, projectKey) {
+    const data = (await apiFetch(`/projects/${encodeURIComponent(projectKey)}/context-kinds`, apiKey));
+    return Array.isArray(data.items) ? data.items.map((k) => k.key) : [];
+}
+/**
+ * Full per-environment flag targeting. `?summary=0` plus repeated `?env=`
+ * returns rules, clauses, targets, fallthrough, offVariation, prerequisites
+ * and rollouts for every named environment in one response — there is no
+ * "all environments" wildcard, so env keys are templated in explicitly.
+ *
+ * `opts.archived` flips the list to *only* archived flags. LaunchDarkly's flag
+ * list endpoint hides archived flags by default and has no "both" mode, so a
+ * full picture is two calls. The migration runtime does not want archived flags
+ * (`fetchSnapshot` omits this), but the fixture-corpus exporter needs them so
+ * the `state-archived` edge case is in the canonical corpus.
+ */
+export async function fetchFlags(apiKey, projectKey, envKeys, opts = {}) {
+    const params = new URLSearchParams({ limit: String(PAGE_LIMIT), summary: '0' });
+    for (const env of envKeys)
+        params.append('env', env);
+    if (opts.archived)
+        params.set('archived', 'true');
+    return paginate(`/flags/${encodeURIComponent(projectKey)}?${params}`, apiKey);
+}
+/** Segments are a per-environment resource — caller loops env keys and de-dupes. */
+export async function fetchSegmentsForEnv(apiKey, projectKey, envKey) {
+    return paginate(`/segments/${encodeURIComponent(projectKey)}/${encodeURIComponent(envKey)}?limit=${PAGE_LIMIT}`, apiKey);
+}
+/**
+ * Stitches the whole Phase-1 snapshot: environments → context-kinds → flags
+ * (one call, all envs) → segments (per env, de-duplicated by key). This is the
+ * ~60-call "fast, lossless for current state" path; it always re-fetches
+ * everything (decision D2 — we do not trust the LD audit cursor for deltas).
+ */
+export async function fetchSnapshot(apiKey, projectKey) {
+    const environments = await fetchProjectEnvironments(apiKey, projectKey);
+    const contextKinds = await fetchContextKinds(apiKey, projectKey);
+    const flags = await fetchFlags(apiKey, projectKey, environments);
+    const segmentsByKey = new Map();
+    for (const envKey of environments) {
+        // eslint-disable-next-line no-await-in-loop
+        const segs = await fetchSegmentsForEnv(apiKey, projectKey, envKey);
+        for (const seg of segs) {
+            // First env to define a segment wins; LD segments are per-env but the
+            // key is stable, and v1 imports one shell per key (plan §5.4).
+            if (!segmentsByKey.has(seg.key))
+                segmentsByKey.set(seg.key, seg);
+        }
+    }
+    return {
+        contextKinds,
+        environments,
+        flags,
+        segments: [...segmentsByKey.values()],
+    };
+}