@quonfig/cli 0.0.46 → 0.0.48

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

@@ -0,0 +1,172 @@
+/**
+ * LaunchDarkly REST API client — Phase-2 history backfill (`--full-summary`).
+ *
+ * Phase 1 (`api.ts`) is a fast current-state snapshot. Phase 2 is the slow,
+ * resumable audit-log walk that reifies every historical flag change into its
+ * own git commit with the original author, date and message.
+ *
+ * Hard constraints, straight from `project/plans/migrator-launch-darkly.md`
+ * §4.1 / §4.1.1 — all surfaced to the user, none worked around silently:
+ *
+ * - The audit log is a *forward event stream*, not a versioned object store.
+ *   There is no point-in-time endpoint; each `/auditlog/{id}` entry carries the
+ *   full `currentVersion` of the resource as of that change, which is exactly
+ *   what we need to reify a commit.
+ * - `/auditlog` caps `limit` at 20 and is account-wide. A large account is tens
+ *   of thousands of events → 10k–50k+ calls → hours. The walk MUST be
+ *   checkpointed/resumable — `walkAuditLog` cursors on `before` and emits an
+ *   `onCheckpoint` after every page so a crashed run resumes where it stopped.
+ * - Retention is plan-gated: LD Developer plans retain only the last 30 days.
+ *   `probeRetentionHorizon` is the up-front pre-flight — it tells the user the
+ *   real horizon BEFORE the slow phase starts, so nobody waits hours expecting
+ *   two years and silently gets thirty days.
+ * - `delta` is null for semantic-patch updates, so we rely on `currentVersion`,
+ *   never `delta`.
+ */
+import { apiFetch } from './api.js';
+const SOURCE_NAME = 'launchdarkly';
+/** `/auditlog` hard-caps `limit` at 20 — see plan §4.1. */
+const AUDIT_PAGE_LIMIT = 20;
+const DAY_MS = 86_400_000;
+/**
+ * Retention boundaries the pre-flight probe brackets against, in days. The
+ * 30-day mark is the LD Developer-plan retention ceiling; the rest bracket the
+ * "how far does this account actually retain" question cheaply (one `limit=1`
+ * call each) instead of walking the whole log just to find its floor.
+ */
+const RETENTION_PROBE_DAYS = [30, 90, 180, 365, 730];
+/** The LD audit-log resource spec that scopes the walk to every flag in a project. */
+export function buildFlagAuditSpec(projectKey) {
+    return `proj/${projectKey}:env/*:flag/*`;
+}
+/** One page of the `/auditlog` listing. `limit` is pinned to the API's max of 20. */
+export async function fetchAuditLogPage(apiKey, opts = {}) {
+    const params = new URLSearchParams({ limit: String(AUDIT_PAGE_LIMIT) });
+    if (opts.before !== undefined)
+        params.set('before', String(opts.before));
+    if (opts.after !== undefined)
+        params.set('after', String(opts.after));
+    if (opts.spec)
+        params.set('spec', opts.spec);
+    const data = (await apiFetch(`/auditlog?${params}`, apiKey));
+    return { _links: data._links, items: Array.isArray(data.items) ? data.items : [] };
+}
+/** Hydrate one listing row into a full entry — this is the call that carries `currentVersion`. */
+export async function fetchAuditLogEntry(apiKey, id) {
+    return (await apiFetch(`/auditlog/${encodeURIComponent(id)}`, apiKey));
+}
+/**
+ * Walk the audit log newest-to-oldest, hydrating every listing row. Pages on
+ * the `before` cursor (the oldest `date` seen so far) so the walk is resumable:
+ * pass `startBefore` to resume, and persist each `onCheckpoint(before)` value.
+ *
+ * Terminates on the first empty page; an `after` floor stops it early. A
+ * non-decreasing cursor (a misbehaving API or a same-ms tie at a page edge)
+ * also terminates the walk rather than looping forever.
+ */
+export async function* walkAuditLog(apiKey, opts = {}) {
+    let before = opts.startBefore;
+    const seenCursors = new Set();
+    while (true) {
+        // eslint-disable-next-line no-await-in-loop
+        const page = await fetchAuditLogPage(apiKey, {
+            ...(opts.after === undefined ? {} : { after: opts.after }),
+            ...(before === undefined ? {} : { before }),
+            ...(opts.spec ? { spec: opts.spec } : {}),
+        });
+        if (page.items.length === 0)
+            break;
+        let crossedFloor = false;
+        for (const item of page.items) {
+            if (opts.after !== undefined && item.date <= opts.after) {
+                crossedFloor = true;
+                break;
+            }
+            // eslint-disable-next-line no-await-in-loop
+            yield await fetchAuditLogEntry(apiKey, item._id);
+        }
+        if (crossedFloor)
+            break;
+        // The oldest entry on the page is the cursor for the next (older) page.
+        // Empty-page guard above (line 161) means at(-1) is defined here; bang for TS.
+        const nextBefore = page.items.at(-1).date;
+        // eslint-disable-next-line no-await-in-loop
+        if (opts.onCheckpoint)
+            await opts.onCheckpoint(nextBefore);
+        if ((before !== undefined && nextBefore >= before) || seenCursors.has(nextBefore))
+            break;
+        seenCursors.add(nextBefore);
+        before = nextBefore;
+    }
+}
+/**
+ * Up-front retention pre-flight (plan §4.1.1). Brackets the account's retention
+ * window with one cheap `limit=1` probe per boundary instead of walking the
+ * whole log. An empty 30-day probe means the account retains ≤ 30 days — almost
+ * certainly an LD Developer plan, and pre-window history is permanently gone.
+ */
+export async function probeRetentionHorizon(apiKey, opts = {}) {
+    const now = opts.now ?? Date.now();
+    let oldestReachableMs = null;
+    for (const days of RETENTION_PROBE_DAYS) {
+        // eslint-disable-next-line no-await-in-loop
+        const page = await fetchAuditLogPage(apiKey, {
+            before: now - days * DAY_MS,
+            ...(opts.spec ? { spec: opts.spec } : {}),
+        });
+        // First empty boundary is the retention floor — stop bracketing deeper.
+        if (page.items.length === 0)
+            break;
+        oldestReachableMs = page.items[0].date;
+    }
+    const label = oldestReachableMs === null
+        ? 'LaunchDarkly retained ≤ 30 days of audit history (likely a Developer plan) — pre-window history is permanently gone.'
+        : `LaunchDarkly audit history reaches back to at least ${new Date(oldestReachableMs).toISOString().slice(0, 10)}.`;
+    return { developerPlanLikely: oldestReachableMs === null, label, oldestReachableMs };
+}
+/** True when an audit entry's `currentVersion` is shaped like an `LDFlag`. */
+function isFlagVersion(version) {
+    return (typeof version === 'object' &&
+        version !== null &&
+        typeof version.key === 'string' &&
+        Array.isArray(version.variations));
+}
+/**
+ * Map a hydrated audit entry to a `LegacyChange`. The `currentVersion` flag
+ * snapshot is carried as the `{kind: 'flag', data}` payload `translate()`
+ * already understands, so Phase-2 history reuses the Phase-1 converter
+ * unchanged. Returns null for entries that carry no flag `currentVersion`
+ * (deleted resources, non-flag audit rows) — those are skipped, not crashed.
+ */
+export function auditEntryToLegacyChange(entry) {
+    if (!isFlagVersion(entry.currentVersion))
+        return null;
+    return {
+        changedAt: entry.date,
+        key: entry.currentVersion.key,
+        raw: { auditEntry: entry, data: entry.currentVersion, kind: 'flag' },
+        source: SOURCE_NAME,
+    };
+}
+function actorName(member) {
+    const full = [member.firstName, member.lastName].filter(Boolean).join(' ').trim();
+    return full.length > 0 ? full : (member.email ?? 'LaunchDarkly user');
+}
+/**
+ * Reify an audit entry's original author, timestamp and description into commit
+ * metadata for `--full-summary` (plan §7). Returns null when the entry has no
+ * human member (token / integration actors) so the caller falls back to the
+ * migrator identity rather than inventing an author.
+ */
+export function getCommitMetaForAuditEntry(entry) {
+    const member = entry.member;
+    if (!member || !member.email)
+        return null;
+    const described = entry.shortDescription?.trim() || entry.description?.trim();
+    // Empirically many LD audit entries carry no human description; fall back to
+    // a stable, key-aware message so `git log` stays readable.
+    const message = described && described.length > 0
+        ? described
+        : `migrator: update ${entry.currentVersion?.key ?? entry.name ?? 'flag'}`;
+    return { author: { email: member.email, name: actorName(member) }, date: entry.date, message };
+}

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

@@ -0,0 +1,39 @@
+/**
+ * LaunchDarkly converter — LaunchDarkly flag/segment JSON → `QuonfigFile[]`.
+ *
+ * This is the provider-specific topology collapse (plan §3.1, Epic 3). It calls
+ * the shared `quonfig-target/` verb library for the parts that are not
+ * LaunchDarkly-specific (operator mapping, value coercion, ordered-ruleset
+ * collapse) and handles the LaunchDarkly-shaped structure here: variations →
+ * variants, per-environment state → `environments[]`, the gap dispositions of
+ * plan §5.4.
+ */
+import { ConversionReport } from '../../quonfig-target/report.js';
+import type { LDFlag, LDSegment } from './types.js';
+export declare function flagOutputPath(key: string): string;
+export declare function segmentOutputPath(key: string): string;
+/**
+ * Translate one LaunchDarkly flag into a Quonfig feature-flag file.
+ *
+ * Structure:
+ *  - `variations[]` → typed `variants[]`
+ *  - per-environment state → `environments[]` (each collapsed via the verb lib)
+ *  - `default.rules` → a baseline ALWAYS_TRUE rule serving variation 0; any
+ *    environment LaunchDarkly did not define falls back to this.
+ *
+ * Gap dispositions (plan §5.4) are recorded on `report` — nothing silent.
+ */
+export declare function translateFlag(flag: LDFlag, report: ConversionReport): Record<string, unknown>;
+/**
+ * Translate one LaunchDarkly segment into a Quonfig segment file.
+ *
+ * Quonfig segments are boolean ("is the context in the segment?") and have no
+ * per-environment state, so everything collapses into `default.rules`,
+ * first-match-wins, matching LaunchDarkly's evaluation precedence:
+ * excluded → included → rules → (not in segment).
+ *
+ * Big/synced segments (`unbounded: true`) cannot have their membership
+ * exported via the REST API — the shell + rules are emitted and the loss is
+ * reported (plan §5.4).
+ */
+export declare function translateSegment(segment: LDSegment, report: ConversionReport): Record<string, unknown>;

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

@@ -0,0 +1,209 @@
+/**
+ * LaunchDarkly converter — LaunchDarkly flag/segment JSON → `QuonfigFile[]`.
+ *
+ * This is the provider-specific topology collapse (plan §3.1, Epic 3). It calls
+ * the shared `quonfig-target/` verb library for the parts that are not
+ * LaunchDarkly-specific (operator mapping, value coercion, ordered-ruleset
+ * collapse) and handles the LaunchDarkly-shaped structure here: variations →
+ * variants, per-environment state → `environments[]`, the gap dispositions of
+ * plan §5.4.
+ */
+import { clauseToCriterion, collapseEnvironment, } from '../../quonfig-target/ruleset.js';
+import { inferFlagValueType, toQuonfigValue } from '../../quonfig-target/values.js';
+const ALWAYS_TRUE = { operator: 'ALWAYS_TRUE' };
+/**
+ * LaunchDarkly keys are already flat and URL-safe, but normalize `/` → `.`
+ * defensively so a key can never create a nested directory tree (matches the
+ * flat-path contract `local-write.ts` enforces).
+ */
+function normalizeKey(key) {
+    return key.replaceAll('/', '.');
+}
+/** Environment keys are LD slugs already; lowercase + hyphenate to be safe. */
+function slugifyEnvKey(key) {
+    return key
+        .toLowerCase()
+        .replaceAll(/[^\da-z]+/g, '-')
+        .replaceAll(/^-+|-+$/g, '');
+}
+export function flagOutputPath(key) {
+    return `feature-flags/${normalizeKey(key)}.json`;
+}
+export function segmentOutputPath(key) {
+    return `segments/${normalizeKey(key)}.json`;
+}
+/**
+ * Translate one LaunchDarkly flag into a Quonfig feature-flag file.
+ *
+ * Structure:
+ *  - `variations[]` → typed `variants[]`
+ *  - per-environment state → `environments[]` (each collapsed via the verb lib)
+ *  - `default.rules` → a baseline ALWAYS_TRUE rule serving variation 0; any
+ *    environment LaunchDarkly did not define falls back to this.
+ *
+ * Gap dispositions (plan §5.4) are recorded on `report` — nothing silent.
+ */
+export function translateFlag(flag, report) {
+    const variationValues = flag.variations.map((v) => v.value);
+    const valueType = inferFlagValueType(flag.kind, variationValues);
+    const ctx = {
+        report,
+        sourceKey: flag.key,
+        valueType,
+        variationValues,
+    };
+    // clientSideAvailability: feature flags are always client-visible in Quonfig,
+    // so `sendToClientSdk` is invalid on them — we cannot carry the dimension.
+    // Report the mobile-key drop rather than silently losing it.
+    if (flag.clientSideAvailability?.usingMobileKey) {
+        report.add('dropped-mobile-key-availability', flag.key, `clientSideAvailability.usingMobileKey was true — Quonfig has one client-visibility bool, the mobile-key dimension is dropped`);
+    }
+    if (flag.maintainerId || flag.maintainerTeamKey) {
+        report.add('dropped-maintainer', flag.key, `maintainer ${flag.maintainerId ?? flag.maintainerTeamKey} dropped — Quonfig authorship lives in git history`);
+    }
+    if (flag.customProperties && Object.keys(flag.customProperties).length > 0) {
+        report.add('dropped-custom-properties', flag.key, `customProperties (${Object.keys(flag.customProperties).join(', ')}) dropped — report-only in v1 (D6)`);
+    }
+    const variants = flag.variations.map((v) => {
+        const variant = {
+            value: toQuonfigValue(v.value, valueType),
+        };
+        if (v.name !== undefined)
+            variant.name = v.name;
+        if (v.description !== undefined)
+            variant.description = v.description;
+        return variant;
+    });
+    const environments = Object.entries(flag.environments)
+        .map(([envKey, envState]) => ({
+        id: slugifyEnvKey(envKey),
+        rules: collapseEnvironment(envState, ctx),
+    }))
+        // Stable output order regardless of JSON key iteration order.
+        .sort((a, b) => a.id.localeCompare(b.id));
+    // Baseline default: any environment LaunchDarkly did not define serves
+    // variation 0. LaunchDarkly state is entirely per-environment, so there is
+    // no source-side "default" — this is a documented, conservative choice.
+    const out = {
+        key: normalizeKey(flag.key),
+        type: 'feature_flag',
+        valueType,
+        default: {
+            rules: [{ criteria: [ALWAYS_TRUE], value: toQuonfigValue(variationValues[0], valueType) }],
+        },
+        environments,
+        variants,
+    };
+    if (flag.name !== undefined)
+        out.name = flag.name;
+    if (flag.description !== undefined)
+        out.description = flag.description;
+    if (flag.tags && flag.tags.length > 0)
+        out.tags = [...flag.tags];
+    return out;
+}
+/**
+ * Translate one LaunchDarkly segment into a Quonfig segment file.
+ *
+ * Quonfig segments are boolean ("is the context in the segment?") and have no
+ * per-environment state, so everything collapses into `default.rules`,
+ * first-match-wins, matching LaunchDarkly's evaluation precedence:
+ * excluded → included → rules → (not in segment).
+ *
+ * Big/synced segments (`unbounded: true`) cannot have their membership
+ * exported via the REST API — the shell + rules are emitted and the loss is
+ * reported (plan §5.4).
+ */
+export function translateSegment(segment, report) {
+    const ctx = {
+        report,
+        sourceKey: segment.key,
+        valueType: 'bool',
+        variationValues: [],
+    };
+    const rules = [];
+    if (segment.unbounded) {
+        report.add('unexportable-segment-membership', segment.key, `big/synced segment (unbounded) — membership is not exportable via the LaunchDarkly REST API; only the rule shell is imported`);
+    }
+    const keyListRule = (kind, values, inSegment) => ({
+        criteria: [
+            {
+                operator: 'PROP_IS_ONE_OF',
+                propertyName: `${kind}.key`,
+                valueToMatch: { type: 'string_list', value: [...values] },
+            },
+        ],
+        value: { type: 'bool', value: inSegment },
+    });
+    // Excluded contexts win over included — match LaunchDarkly precedence.
+    if (segment.excluded && segment.excluded.length > 0)
+        rules.push(keyListRule('user', segment.excluded, false));
+    for (const ec of segment.excludedContexts ?? []) {
+        if (ec.values.length > 0)
+            rules.push(keyListRule(ec.contextKind, ec.values, false));
+    }
+    if (segment.included && segment.included.length > 0)
+        rules.push(keyListRule('user', segment.included, true));
+    for (const ic of segment.includedContexts ?? []) {
+        if (ic.values.length > 0)
+            rules.push(keyListRule(ic.contextKind, ic.values, true));
+    }
+    for (const rule of segment.rules ?? []) {
+        const built = buildSegmentRule(rule, ctx);
+        if (built !== null)
+            rules.push(built);
+    }
+    // Trailing catch-all: anyone not matched above is not in the segment.
+    rules.push({ criteria: [ALWAYS_TRUE], value: { type: 'bool', value: false } });
+    const out = {
+        key: normalizeKey(segment.key),
+        type: 'segment',
+        valueType: 'bool',
+        default: { rules },
+        environments: [],
+        variants: [],
+    };
+    if (segment.name !== undefined)
+        out.name = segment.name;
+    if (segment.description !== undefined)
+        out.description = segment.description;
+    if (segment.tags && segment.tags.length > 0)
+        out.tags = [...segment.tags];
+    return out;
+}
+/**
+ * Build a Quonfig rule from a LaunchDarkly segment rule. A segment rule's
+ * clauses AND together and the rule means "in the segment". A rule-level
+ * `weight` is a percentage of matching contexts — converted to a
+ * `weighted_values` bool split (and reported as re-bucketing). Returns `null`
+ * when a clause cannot be mapped (the whole rule is dropped — see `buildRule`).
+ */
+function buildSegmentRule(rule, ctx) {
+    // Reuse the clause-mapping verb via a tiny inline AND loop so segment rules
+    // get the exact same operator handling (and whole-rule-drop) as flag rules.
+    const criteria = [];
+    for (const clause of rule.clauses) {
+        const criterion = clauseToCriterion(clause, ctx);
+        if (criterion === null)
+            return null;
+        criteria.push(criterion);
+    }
+    const value = rule.weight === undefined
+        ? { type: 'bool', value: true }
+        : {
+            type: 'weighted_values',
+            value: {
+                hashByPropertyName: rule.bucketBy
+                    ? `user.${rule.bucketBy.replace(/^\//, '').replaceAll('/', '.')}`
+                    : 'user.key',
+                weightedValues: [
+                    { value: { type: 'bool', value: true }, weight: rule.weight },
+                    { value: { type: 'bool', value: false }, weight: Math.max(0, 100_000 - rule.weight) },
+                ],
+            },
+        };
+    if (rule.weight !== undefined) {
+        ctx.report.add('rebucketed-rollout', ctx.sourceKey, `segment rule has a ${rule.weight / 1000}% weight — converted to a weighted bool split; users will be re-bucketed`);
+    }
+    return { criteria: criteria.length > 0 ? criteria : [ALWAYS_TRUE], value };
+}

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

@@ -0,0 +1,187 @@
+/**
+ * Clean typed structs for the slice of the LaunchDarkly REST API the
+ * Phase-1 config-snapshot fetcher walks. Field names mirror LaunchDarkly's
+ * JSON exactly; optional fields are the ones LD omits when unset.
+ *
+ * Reference: https://apidocs.launchdarkly.com/ — `GET /flags/{proj}?env=`,
+ * `GET /segments/{proj}/{env}`, `GET /projects/{proj}/environments`,
+ * `GET /projects/{proj}/context-kinds`.
+ */
+/** A LaunchDarkly clause — one predicate inside a rule (rule clauses AND together). */
+export interface LDClause {
+    _id?: string;
+    /** JSON-pointer-or-bare attribute name, e.g. "email" or "/address/city". */
+    attribute: string;
+    /** Context kind the attribute belongs to. Absent ⇒ "user". */
+    contextKind?: string;
+    negate?: boolean;
+    /** LaunchDarkly operator name, e.g. "in", "segmentMatch", "semVerLessThan". */
+    op: string;
+    values: unknown[];
+}
+/** One weighted variation inside a rollout. */
+export interface LDWeightedVariation {
+    untracked?: boolean;
+    /** 0-based index into the flag's variations[]. */
+    variation: number;
+    /** Integer weight; weights in a rollout sum to 100000 (= 100%). */
+    weight: number;
+}
+/** A percentage rollout — served by a rule or by the fallthrough. */
+export interface LDRollout {
+    /** Attribute to hash on. Absent ⇒ the context key. May be a JSON pointer. */
+    bucketBy?: string;
+    contextKind?: string;
+    /** "experiment" marks an experiment rollout; v1 drops the experiment framing. */
+    kind?: string;
+    seed?: number;
+    variations: LDWeightedVariation[];
+}
+/** A targeting rule inside a per-environment flag state. */
+export interface LDRule {
+    _id?: string;
+    clauses: LDClause[];
+    description?: string;
+    /** Exactly one of `variation` / `rollout` is set. */
+    rollout?: LDRollout;
+    trackEvents?: boolean;
+    variation?: number;
+}
+/** Individual-target list — specific context keys pinned to one variation. */
+export interface LDTarget {
+    /** Absent on the legacy user-only `targets` array ⇒ "user". */
+    contextKind?: string;
+    values: string[];
+    variation: number;
+}
+/** Single variation/default pointer or a rollout. */
+export interface LDVariationOrRollout {
+    rollout?: LDRollout;
+    variation?: number;
+}
+/** Per-environment flag state, keyed by environment key in `flag.environments`. */
+export interface LDFlagEnvironment {
+    archived?: boolean;
+    contextTargets?: LDTarget[];
+    fallthrough?: LDVariationOrRollout;
+    /** Index into variations[] served when `on` is false. */
+    offVariation?: number;
+    /** The `on` toggle that sits above the rule engine. */
+    on: boolean;
+    prerequisites?: Array<{
+        key: string;
+        variation: number;
+    }>;
+    rules?: LDRule[];
+    salt?: string;
+    targets?: LDTarget[];
+    version?: number;
+}
+/** A flag variation — one of the typed values the flag can serve. */
+export interface LDVariation {
+    _id?: string;
+    description?: string;
+    name?: string;
+    value: unknown;
+}
+/** A LaunchDarkly feature flag as returned by `GET /flags/{proj}?env=...`. */
+export interface LDFlag {
+    clientSideAvailability?: {
+        usingEnvironmentId?: boolean;
+        usingMobileKey?: boolean;
+    };
+    customProperties?: Record<string, {
+        name?: string;
+        value: string[];
+    }>;
+    description?: string;
+    /** Map of environment key → per-environment state. */
+    environments: Record<string, LDFlagEnvironment>;
+    key: string;
+    /** "boolean" or "multivariate". */
+    kind: string;
+    maintainerId?: string;
+    maintainerTeamKey?: string;
+    name?: string;
+    tags?: string[];
+    temporary?: boolean;
+    variations: LDVariation[];
+}
+/** A LaunchDarkly segment as returned by `GET /segments/{proj}/{env}`. */
+export interface LDSegment {
+    description?: string;
+    excluded?: string[];
+    excludedContexts?: Array<{
+        contextKind: string;
+        values: string[];
+    }>;
+    included?: string[];
+    includedContexts?: Array<{
+        contextKind: string;
+        values: string[];
+    }>;
+    key: string;
+    name?: string;
+    rules?: Array<{
+        _id?: string;
+        bucketBy?: string;
+        clauses: LDClause[];
+        weight?: number;
+    }>;
+    tags?: string[];
+    /** Big/synced segment — membership is not exportable via the REST API. */
+    unbounded?: boolean;
+    unboundedContextKind?: string;
+}
+/** `GET /projects/{proj}/environments` — offset-paginated. */
+export interface LDEnvironmentsResponse {
+    _links?: {
+        next?: {
+            href: string;
+        };
+    };
+    items: Array<{
+        key: string;
+        name: string;
+    }>;
+    totalCount?: number;
+}
+/** `GET /flags/{proj}?env=...` — offset-paginated. */
+export interface LDFlagsResponse {
+    _links?: {
+        next?: {
+            href: string;
+        };
+    };
+    items: LDFlag[];
+    totalCount?: number;
+}
+/** `GET /segments/{proj}/{env}` — offset-paginated. */
+export interface LDSegmentsResponse {
+    _links?: {
+        next?: {
+            href: string;
+        };
+    };
+    items: LDSegment[];
+    totalCount?: number;
+}
+/** `GET /projects/{proj}/context-kinds`. */
+export interface LDContextKindsResponse {
+    items: Array<{
+        key: string;
+        name?: string;
+    }>;
+}
+/**
+ * The full Phase-1 config snapshot — what the fetcher stitches together and
+ * what `translate()` consumes. One of these is produced per migration run.
+ */
+export interface LDSnapshot {
+    contextKinds: string[];
+    /** Environment keys, in API order. */
+    environments: string[];
+    flags: LDFlag[];
+    /** Segments de-duplicated by key across environments. */
+    segments: LDSegment[];
+}

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

@@ -0,0 +1,10 @@
+/**
+ * Clean typed structs for the slice of the LaunchDarkly REST API the
+ * Phase-1 config-snapshot fetcher walks. Field names mirror LaunchDarkly's
+ * JSON exactly; optional fields are the ones LD omits when unset.
+ *
+ * Reference: https://apidocs.launchdarkly.com/ — `GET /flags/{proj}?env=`,
+ * `GET /segments/{proj}/{env}`, `GET /projects/{proj}/environments`,
+ * `GET /projects/{proj}/context-kinds`.
+ */
+export {};

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

@@ -1,2 +1,37 @@
+/**
+ * `qfg migrate --from launchdarkly` — the MigrationSource implementation.
+ *
+ * Wires the LaunchDarkly fetcher (`launchdarkly/api.ts`) and converter
+ * (`launchdarkly/translate.ts`) into the source-agnostic migration framework.
+ * Both write modes (`--dir`, `--push`) are inherited for free — this source
+ * only has to produce `QuonfigFile[]`.
+ *
+ * Design is frozen in `launchdarkly.README.md` / `project/plans/migrator-launch-darkly.md`.
+ */
+import { ConversionReport } from '../quonfig-target/report.js';
 import { type MigrationSource } from '../source.js';
+import { type RetentionHorizon } from './launchdarkly/audit.js';
+/**
+ * Override the LaunchDarkly project key for this run. Called by the `qfg migrate`
+ * command from its `--project` flag (which itself falls back to the
+ * `LAUNCHDARKLY_PROJECT_KEY` env var). Mirrors `applyLaunchDarklyBaseUrl()` —
+ * the command layer threads run-scoped config into the source singleton.
+ */
+export declare function setLaunchDarklyProjectKey(projectKey: string): void;
+/**
+ * Enable Phase-2 history backfill for this run. When set, `fetchChanges` walks
+ * the LaunchDarkly audit log instead of taking a current-state snapshot, and
+ * `validateAuth` runs the retention pre-flight. Called by `qfg migrate` from
+ * its `--full-summary` flag.
+ */
+export declare function setLaunchDarklyFullSummary(on: boolean): void;
+/**
+ * The retention pre-flight result from the last full-summary `validateAuth`,
+ * or null. The command reads this and tells the user the real history horizon
+ * BEFORE the slow audit walk starts (plan §4.1.1).
+ */
+export declare function getLaunchDarklyRetentionHorizon(): null | RetentionHorizon;
+/** The full conversion report — every skip/drop/coerce note from this run. */
+export declare function getConversionReport(): ConversionReport;
 export declare const launchdarklySource: MigrationSource;
+export declare function __resetLaunchDarklySourceForTests(): void;