@quonfig/cli 0.0.49 → 0.0.51

package/dist/migrate/push-to-cloud.js

@@ -2,7 +2,7 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { removeQfFromGitignore, writeImportState } from './import-state.js';
 import { buildAuditFinalCommit, buildAuditPerChangeCommits, buildMigrationCommitMessage, buildMigrationCounts, writeQuonfigFiles, } from './local-write.js';
-import { writeMigrationReport } from './migration-report.js';
+import { deriveFollowUpFromConversionNotes, writeMigrationReport } from './migration-report.js';
 import { cloneAndStackPush, } from '../util/clone-and-stack-push.js';
 import { formatResult, validateWorkspace } from '../verify/validate.js';
 /**
@@ -95,6 +95,8 @@ export const pushMigrationToCloud = async (opts) => {
                     acc.duplicateResolutions =
                         resolutionEntries.length > 0 ? { entries: resolutionEntries, total: resolutionEntries.length } : null;
                     const conversionNotes = opts.source.getConversionNotes?.() ?? null;
+                    const environmentMap = opts.source.getEnvironmentMap?.() ?? null;
+                    const maintainerMap = opts.source.getMaintainerMap?.() ?? null;
                     const skippedTotal = (acc.skippedConfigs?.total ?? 0) + resolutionEntries.reduce((sum, r) => sum + r.deleted.length, 0);
                     const environmentsCount = opts.environments?.length ?? 0;
                     const counts = buildMigrationCounts(livePaths, environmentsCount, skippedTotal);
@@ -102,10 +104,13 @@ export const pushMigrationToCloud = async (opts) => {
                     const reportData = {
                         ...opts.reportData,
                         counts,
+                        ...(environmentMap && environmentMap.length > 0 ? { environmentMap } : {}),
+                        followUp: deriveFollowUpFromConversionNotes(opts.reportData.followUp, conversionNotes ?? undefined),
                         ...(acc.coercedSentinels ? { coercedSentinels: acc.coercedSentinels } : {}),
                         ...(conversionNotes && conversionNotes.length > 0 ? { conversionNotes } : {}),
                         ...(acc.droppedOverrides ? { droppedOverrides: acc.droppedOverrides } : {}),
                         ...(acc.duplicateResolutions ? { duplicateResolutions: acc.duplicateResolutions } : {}),
+                        ...(maintainerMap && Object.keys(maintainerMap).length > 0 ? { maintainerMap } : {}),
                         ...(acc.skippedConfigs ? { skippedConfigs: acc.skippedConfigs } : {}),
                     };
                     writeMigrationReport(dir, reportData);

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

@@ -26,20 +26,56 @@ export type ConversionNoteCategory =
  | 'dropped-maintainer'
 /** `customProperties` dropped — report-only in v1 (D6). */
  | 'dropped-custom-properties'
-/** clientSideAvailability mobile-key dimension dropped. */
- | 'dropped-mobile-key-availability'
+/**
+ * `usingMobileKey:true` collapsed into Quonfig's single client-visibility bool,
+ * but the flag is still client-visible because `usingEnvironmentId` is also true.
+ * No action required — pure rollup noise.
+ */
+ | 'dropped-mobile-key-still-visible'
+/**
+ * `usingMobileKey:true` but `usingEnvironmentId:false` — the flag was
+ * mobile-only in LD and will no longer reach mobile clients after migration.
+ * Must-fix before cutover.
+ */
+ | 'dropped-mobile-key-now-server-only'
 /** A percentage rollout that will re-bucket users post-migration (plan §5.4). */
  | 'rebucketed-rollout'
 /** A big/synced segment whose membership is not exportable via REST. */
  | 'unexportable-segment-membership'
 /** An AI Config enumerated but not emitted (out of v1 scope, D9). */
- | 'ai-config-skipped';
+ | 'ai-config-skipped'
+/**
+ * Flagsmith D-F1: a non-boolean feature was `enabled=false`. Flagsmith would have
+ * served the SDK-side default (not visible to the migrator); Quonfig will now
+ * serve the stored `feature_state_value`. The "coerced sentinel" framing in
+ * `getCoercedSentinels()` is reused so the per-env counts surface in the report.
+ */
+ | 'enabled-false-non-boolean'
+/** Flagsmith D-F5: same feature has different value types across envs. Coerced to string. */
+ | 'cross-env-value-type-coerced'
+/** Flagsmith identity override emitted as a leading PROP_IS_ONE_OF rule on the identifier attribute. */
+ | 'identity-override-as-rule'
+/**
+ * Flagsmith identity-trait extraction: a context attribute referenced by a segment rule
+ * (plan §5.5 / D-F6). Pure FYI — your SDK callers will need to send this attribute at
+ * eval time. The `key` is the trait name; `detail` lists the segments referencing it.
+ */
+ | 'identity-traits-referenced';
 export interface ConversionNote {
     category: ConversionNoteCategory;
     /** Human-readable detail — names the exact thing lost and why. */
     detail: string;
     /** Source key the note is about (flag or segment key). */
     key: string;
+    /**
+     * Structured prereq edges on `dropped-prerequisite` notes — the renderer uses
+     * this to produce the inverted "orphaned parent → downstream consumers" view
+     * (qfg-nb4n). Absent on every other category.
+     */
+    prerequisites?: Array<{
+        parentKey: string;
+        variation: number;
+    }>;
 }
 /**
  * Collects conversion notes during a migration run. A provider source holds
@@ -49,7 +85,12 @@ export interface ConversionNote {
 export declare class ConversionReport {
     private readonly notes;
     get size(): number;
-    add(category: ConversionNoteCategory, key: string, detail: string): void;
+    add(category: ConversionNoteCategory, key: string, detail: string, extras?: {
+        prerequisites?: Array<{
+            parentKey: string;
+            variation: number;
+        }>;
+    }): void;
     /** All notes, in insertion order. */
     all(): ConversionNote[];
     /** Notes of one category, in insertion order. */

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

@@ -19,8 +19,11 @@ export class ConversionReport {
     get size() {
         return this.notes.length;
     }
-    add(category, key, detail) {
-        this.notes.push({ category, detail, key });
+    add(category, key, detail, extras) {
+        const note = { category, detail, key };
+        if (extras?.prerequisites)
+            note.prerequisites = extras.prerequisites;
+        this.notes.push(note);
     }
     /** All notes, in insertion order. */
     all() {

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

@@ -155,11 +155,10 @@ export function collapseEnvironment(env, ctx) {
         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`);
-    }
+    // Prerequisites are dropped (no cross-flag dependency operator in Quonfig v1)
+    // but their reporting is owned by the caller (translateFlag), which dedupes
+    // across environments and emits one enriched note per child flag (qfg-nb4n).
+    // collapseEnvironment intentionally stays silent here.
     // 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 ?? [])];
@@ -177,7 +176,10 @@ export function collapseEnvironment(env, ctx) {
             ],
             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`);
+        ctx.report.add('individual-target-as-rule', ctx.sourceKey, `${target.values.length} ${kind} key(s) inlined into a leading PROP_IS_ONE_OF rule on ${kind}.key. ` +
+            `**Trade-off:** you lost the LD 'targets' UI pane — adding/removing an individual now requires a ` +
+            `config edit (qfg set / web UI), not a separate UI. If this was used for beta-list-style toggling, ` +
+            `consider authoring a \`beta_user\` context attribute instead.`);
     }
     for (const rule of env.rules ?? []) {
         const value = rule.rollout === undefined ? variationValue(rule.variation ?? 0, ctx) : rolloutToWeightedValues(rule.rollout, ctx);

package/dist/migrate/source.d.ts

@@ -12,6 +12,17 @@ export interface QuonfigFile {
     deleted?: boolean;
     path: string;
 }
+/**
+ * One row of the "Environment mapping table" in MIGRATION_REPORT.md. Sources
+ * implement `getEnvironmentMap()` to expose the source-name → Quonfig-name
+ * pairs they translated; the report renderer just formats the rows.
+ */
+export interface EnvironmentMapEntry {
+    /** The Quonfig-side environment name (slugified key). */
+    quonfigName: string;
+    /** The user-facing source-system name (e.g. LD env display name). */
+    sourceName: string;
+}
 export interface DroppedOverrideSummary {
     /** Per-envId → per-output-path count of dropped override sections. */
     byEnv: Record<string, Record<string, number>>;
@@ -106,6 +117,22 @@ export interface MigrationSource {
      * report so customers can review the loss.
      */
     getDroppedOverrides?(): DroppedOverrideSummary | null;
+    /**
+     * qfg-1t7m: source-name → Quonfig-name pairs for the "Environment mapping table"
+     * section of MIGRATION_REPORT.md. Returns the rows the source actually
+     * translated this run; callers thread these into report data. Sources that
+     * don't expose user-facing env names omit this and the table renders `_(none)_`.
+     */
+    getEnvironmentMap?(): EnvironmentMapEntry[] | null;
+    /**
+     * qfg-l8uz: maintainerId → email pairs for the report's "Identifier map"
+     * section. Sources that fetch a member directory (e.g. LD's /members) expose
+     * the lookup here so the report renderer can swap opaque IDs for readable
+     * emails and decorate the `dropped-maintainer` rollup. Null when the source
+     * couldn't fetch members (auth scope, hidden member data) or has none to
+     * surface — the rest of the report still renders.
+     */
+    getMaintainerMap?(): null | Record<string, string>;
     /**
      * Optional post-translate accumulator. Returns any configs that translate() soft-
      * skipped due to invalid source data (e.g. variant/valueType mismatch). Null when

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

@@ -0,0 +1,115 @@
+/**
+ * Flagsmith REST API client — Phase-1 config snapshot.
+ *
+ * Flagsmith has no bulk-export endpoint, so the fetcher stitches per-resource
+ * calls: project → environments → features → per-env featurestates → segments
+ * → feature-segments (priority) → edge identities → edge identity overrides
+ * → tags.
+ *
+ * Auth is `Authorization: Api-Key <token>` — note the `Api-Key` prefix (not
+ * `Bearer`, and not bare-token like LaunchDarkly). Rate-limiting headers are
+ * unpublished; we program against the response: back off on 429 using
+ * `Retry-After` (standard) or `X-RateLimit-Reset` (Flagsmith's variant), and
+ * step the inter-request throttle up briefly when we hit one (mirrors the
+ * Phase-2 generator's empirical backoff loop). On any non-429 error we throw
+ * immediately — only rate limiting is retried.
+ *
+ * Pagination is standard Django REST `{count, next, previous, results}` with
+ * absolute `next` URLs. Edge-identities listing is the one exception: it uses
+ * `{results, last_evaluated_key}` cursor pagination via a query-string param.
+ */
+import type { FlagsmithEdgeIdentity, FlagsmithEdgeIdentityOverride, FlagsmithEnvironment, FlagsmithFeature, FlagsmithFeatureSegment, FlagsmithFeatureState, FlagsmithProject, FlagsmithSegment, FlagsmithSnapshot, FlagsmithTag } from './types.js';
+export declare function setFlagsmithBaseUrl(url: string): void;
+export declare function selectFlagsmithBaseUrl(): string;
+export declare function applyFlagsmithBaseUrl(): void;
+export declare function __setSleepForTests(fn: (ms: number) => Promise<void>): void;
+export declare function __resetSleepForTests(): void;
+export declare class FlagsmithApiError extends Error {
+    readonly status: number;
+    constructor(status: number, statusText: string, url: string, body: string);
+}
+/**
+ * Single GET with `Api-Key` auth, 429 backoff against `Retry-After` /
+ * `X-RateLimit-Reset`, and an exponential fallback. Non-429 errors throw
+ * immediately — only rate limiting is retried.
+ */
+export declare function apiFetch(path: string, apiKey: string): Promise<unknown>;
+/** `GET /projects/{id}/` — used as the cheap auth probe AND as a source of `use_edge_identities`. */
+export declare function fetchProject(apiKey: string, projectId: number | string): Promise<FlagsmithProject>;
+/** `GET /environments/?project={id}` — paginated env list. */
+export declare function fetchEnvironments(apiKey: string, projectId: number | string): Promise<FlagsmithEnvironment[]>;
+/**
+ * `GET /projects/{pk}/features/` — paginated feature list. Each result
+ * includes inline `multivariate_options[]` which we sort ASC by id (API6) so
+ * downstream code sees variations in definition order, not the reverse order
+ * the API returns.
+ */
+export declare function fetchFeatures(apiKey: string, projectId: number | string): Promise<FlagsmithFeature[]>;
+/**
+ * `GET /features/featurestates/?environment={env_id}` — per-env featurestates.
+ *
+ * This is the unified listing that returns BOTH env-default rows
+ * (`feature_segment == null && identity == null`) AND segment-override rows
+ * (`feature_segment != null`). The plan §4.1 suggests
+ * `/environments/{api_key}/featurestates/`, but empirically on v2-versioned
+ * envs that endpoint silently omits segment-override rows. The
+ * `/features/featurestates/?environment=` path is the only read endpoint that
+ * returns both on a v2 env, so we use it uniformly across v1 and v2 envs.
+ *
+ * Identity overrides are NOT in this listing on edge-enabled projects — see
+ * `fetchEdgeIdentityOverrides`.
+ */
+export declare function fetchEnvFeatureStates(apiKey: string, envId: number): Promise<FlagsmithFeatureState[]>;
+/** `GET /projects/{pk}/segments/` — project-scoped segment pool. */
+export declare function fetchSegments(apiKey: string, projectId: number | string): Promise<FlagsmithSegment[]>;
+/**
+ * `GET /features/feature-segments/?environment={env_id}&feature={feature_id}` —
+ * the per-env, per-feature segment priority list. Required by the converter
+ * to order the segment-override rules (Quonfig is a strict first-match list).
+ *
+ * The endpoint REJECTS calls without `feature` (`{feature: ["This field is
+ * required."]}`), so we have to walk every feature × env combo. This is N×E
+ * calls in the worst case — acceptable for the corpus (~110 features × 2 envs
+ * = ~220 calls) and roughly the same order as fetchEnvFeatureStates.
+ */
+export declare function fetchFeatureSegments(apiKey: string, envId: number, featureId: number): Promise<FlagsmithFeatureSegment[]>;
+/**
+ * `GET /environments/{api_key}/edge-identities/` — paginated edge-identity
+ * listing. Pagination here is CURSOR-based (`last_evaluated_key`) not page
+ * numbers — the Flagsmith dynamo-backed edge store can't offset-paginate.
+ *
+ * The fetcher uses this only to surface identifiers for the report; the
+ * actual identity-override featurestates come from
+ * `fetchEdgeIdentityOverrides`, which is a one-call-per-env shortcut.
+ */
+export declare function fetchEdgeIdentities(apiKey: string, envApiKey: string): Promise<FlagsmithEdgeIdentity[]>;
+/**
+ * `GET /environments/{api_key}/edge-identity-overrides` — every identity
+ * override in the env, flat. Each row is `{identifier, identity_uuid,
+ * feature_state}` so we can index by feature without walking N identities.
+ *
+ * Note: the path has NO trailing slash (unlike most Flagsmith paths). This
+ * endpoint does not paginate in the verified shape — it returns
+ * `{results: [...]}` directly.
+ */
+export declare function fetchEdgeIdentityOverrides(apiKey: string, envApiKey: string): Promise<FlagsmithEdgeIdentityOverride[]>;
+/** `GET /projects/{pk}/tags/` — project-scoped tag pool. */
+export declare function fetchTags(apiKey: string, projectId: number | string): Promise<FlagsmithTag[]>;
+/**
+ * Stitch the whole Phase-1 snapshot: project → environments → features →
+ * per-env featurestates (split into env-default + segment-overrides) → segments
+ * → feature-segments (per env, per feature with segment overrides) → edge
+ * identity overrides → tags.
+ *
+ * Walk count grows as 1 (project) + 1 (envs) + 1 (segments) + 1 (tags) + E ×
+ * (1 featurestates + 1 edge-id-overrides + S features-with-segov ×
+ * feature-segments). For the 110-feature, 2-env, 5 features-with-segov live
+ * corpus: ~1 + 1 + 1 + 1 + 2 × (1 + 1 + 5) = ~17 calls. The featurestates
+ * endpoint is paginated under 100/page so larger projects multiply that
+ * featurestates leg.
+ *
+ * `sinceEpochMs` is currently unused — decision D2 says Phase 1 is always a
+ * full re-snapshot. It survives in the signature so reporting (Epic 5) can
+ * compute "what's new since last run" against the same snapshot.
+ */
+export declare function fetchSnapshot(apiKey: string, projectId: number | string): Promise<FlagsmithSnapshot>;