@quonfig/cli 0.0.50 → 0.0.51

package/dist/migrate/migration-report.js

@@ -110,20 +110,34 @@ const renderDuplicateResolutions = (resolved) => {
     }
     return lines.join('\n');
 };
-const renderCoercedSentinels = (coerced) => {
+const FLAGSMITH_ENV_BUCKET_LABEL = {
+    '_all-envs': 'Override rows (all environments)',
+    '_cross-env': 'Cross-environment value-type divergence (no single env owns this)',
+};
+const renderCoercedSentinels = (coerced, source) => {
     if (!coerced || coerced.total === 0)
         return null;
     const envIds = Object.keys(coerced.byEnv).sort();
-    const lines = [
-        '## Coerced sentinel rule values',
-        '',
-        `Coerced **${coerced.total}** rule value(s) from Launch's "no value set yet" sentinel ({type:"string", value:""}) to the typed default for the surrounding config. The qfg-verify hook would otherwise reject these as type-mismatches and fail-stop the entire push. Affected envs: **${envIds.length}**. Review each and set a real default in the source system if needed.`,
-    ];
+    const intro = source === 'flagsmith'
+        ? `Coerced **${coerced.total}** rule value(s) from Flagsmith's runtime semantics into a concrete served value. ` +
+            `Two flavors are bucketed here:\n\n` +
+            `1. **D-F1: \`enabled=false\` on non-boolean features.** Flagsmith would have ignored the stored value and ` +
+            `served your code's hardcoded default. Quonfig always serves a value, so the migrator emits the stored ` +
+            `\`feature_state_value\` and surfaces every affected flag below.\n` +
+            `2. **D-F5: cross-environment value-type divergence.** Flagsmith allowed the same flag to be a string in one ` +
+            `env and an int in another; Quonfig requires one \`valueType\` per flag. The migrator coerced to \`string\`.\n\n` +
+            `Review each entry below and set a real default in the source system if the value is wrong.`
+        : `Coerced **${coerced.total}** rule value(s) from Launch's "no value set yet" sentinel ` +
+            `({type:"string", value:""}) to the typed default for the surrounding config. The qfg-verify hook would ` +
+            `otherwise reject these as type-mismatches and fail-stop the entire push. Affected envs: ` +
+            `**${envIds.length}**. Review each and set a real default in the source system if needed.`;
+    const lines = ['## Coerced sentinel rule values', '', intro];
     for (const envId of envIds) {
         const perFlag = coerced.byEnv[envId];
         const totalForEnv = Object.values(perFlag).reduce((s, n) => s + n, 0);
         const flagCount = Object.keys(perFlag).length;
-        lines.push('', `### env-${envId} — ${totalForEnv} coerced from ${flagCount} config(s)`, '');
+        const heading = FLAGSMITH_ENV_BUCKET_LABEL[envId] ?? `env-${envId}`;
+        lines.push('', `### ${heading} — ${totalForEnv} coerced from ${flagCount} config(s)`, '');
         const sorted = Object.keys(perFlag).sort();
         for (const flagPath of sorted) {
             lines.push(`- \`${flagPath}\` (${perFlag[flagPath]})`);
@@ -155,6 +169,7 @@ const renderSkippedConfigs = (skipped) => {
  */
 const CONVERSION_NOTE_HEADINGS = {
     'ai-config-skipped': 'AI Configs skipped (out of v1 scope)',
+    'cross-env-value-type-coerced': 'Cross-environment value-type coerced to string',
     'dropped-custom-properties': 'Dropped custom properties',
     'dropped-experiment-metadata': 'Dropped experiment metadata',
     'dropped-maintainer': 'Dropped maintainer metadata',
@@ -162,6 +177,9 @@ const CONVERSION_NOTE_HEADINGS = {
     'dropped-mobile-key-still-visible': 'Dropped mobile-key availability (still client-visible)',
     'dropped-prerequisite': 'Dropped prerequisites',
     'dropped-private-attribute': 'Dropped private attributes',
+    'enabled-false-non-boolean': 'enabled=false on non-boolean features',
+    'identity-override-as-rule': 'Identity overrides converted to leading rules',
+    'identity-traits-referenced': 'Identity traits referenced by segment rules',
     'individual-target-as-rule': 'Individual targets converted to rules',
     'skipped-rule': 'Skipped rules (unsupported operators)',
     'unexportable-segment-membership': 'Unexportable segment membership',
@@ -248,14 +266,15 @@ const renderBeforeYouCutOver = (notes) => {
     }
     return lines.join('\n');
 };
-const renderRebucketedRollouts = (notes) => {
+const renderRebucketedRollouts = (notes, source) => {
     const rollouts = (notes ?? []).filter((n) => n.category === 'rebucketed-rollout');
     if (rollouts.length === 0)
         return null;
+    const sourceLabel = source === 'flagsmith' ? 'Flagsmith' : source === 'launchdarkly' ? 'LaunchDarkly' : source;
     const lines = [
         '## Users will be re-bucketed',
         '',
-        `**${rollouts.length}** flag(s)/segment(s) use a percentage rollout. LaunchDarkly and Quonfig hash buckets ` +
+        `**${rollouts.length}** flag(s)/segment(s) use a percentage rollout. ${sourceLabel} and Quonfig hash buckets ` +
             `differently, so which users land in which bucket *will change* after migration — the rollout percentage is ` +
             `preserved, but individual user assignments are not. Review these before cutover so the re-bucketing is not a surprise:`,
         '',
@@ -451,6 +470,45 @@ const LAUNCHDARKLY_BEHAVIORAL_DIFFERENCES_APPENDIX = [
     '- Maintainer is no longer a field on flags. `git log path/to/flag.json` is the',
     '  new source of truth.',
 ].join('\n');
+/**
+ * Flagsmith-specific behavioral-differences appendix (plan §5.5). Same shape
+ * as the LD version above — static documentation about gaps a customer reading
+ * MIGRATION_REPORT.md should know about independently of their specific data.
+ */
+const FLAGSMITH_BEHAVIORAL_DIFFERENCES_APPENDIX = [
+    '## Behavioral differences post-cutover (independent of this import)',
+    '',
+    '- `enabled=false` semantics differ. Flagsmith ignores `feature_state_value` when',
+    "  `enabled=false` and the SDK serves your code's hardcoded default. Quonfig always",
+    '  serves the configured value. For boolean features the migrator emits `false`; for',
+    '  non-boolean features it emits the stored `feature_state_value` and surfaces every',
+    '  affected flag under "Coerced sentinel rule values" above. Review each before',
+    '  cutover — Flagsmith\'s "off" behavior does NOT round-trip.',
+    '- Flagsmith has no individual-target primitive in Quonfig v1. Identity overrides',
+    '  are emitted as leading `PROP_IS_ONE_OF` rules on `user.key`. Adding/removing an',
+    '  identity is now a config edit (qfg set / web UI), not a per-identity row.',
+    '- Identity traits are runtime context Flagsmith infers from the trait directory.',
+    '  Quonfig has no server-side trait store — your SDK callers must send every trait',
+    '  attribute referenced by a segment rule on the eval context. See "Identity traits',
+    '  referenced by segment rules" above for the exhaustive list.',
+    '- Multivariate bucketing salts differ between Flagsmith and Quonfig. The percentage',
+    '  allocation is preserved, but identity → variation assignments WILL change. See',
+    '  "Users will be re-bucketed" above.',
+    '- MODULO and PERCENTAGE_SPLIT segment-condition operators have no Quonfig equivalent.',
+    '  Rules using them were dropped with `skipped-rule` notes; rebuild by hand if you',
+    '  need the segmentation.',
+    '- Segment rule combinators `type=ANY` and `type=NONE` (within-rule OR / NAND) have',
+    '  no Quonfig equivalent — Quonfig criteria within a single rule are AND-only. Those',
+    '  rules were dropped with `skipped-rule` notes.',
+    "- `:semver`-suffixed values are mapped to Quonfig's `PROP_SEMVER_*` operators.",
+    '  Inclusive variants (GTE/LTE) have no semver equivalent and were dropped.',
+    '- Soft-deleted features in Flagsmith are functionally hard-deleted from the public',
+    '  API (404 on GET, absent from list responses). The migrator cannot enumerate them;',
+    '  any features deleted before this snapshot was taken are simply not present in the',
+    '  Quonfig workspace.',
+    '- Feature owners, project metadata, change requests, and scheduled changes are out',
+    '  of v1 scope. None round-trip into Quonfig.',
+].join('\n');
 const renderFollowUp = (followUp) => {
     const must = followUp.mustFixBeforeCutover.length === 0
         ? NONE
@@ -489,10 +547,10 @@ export const buildMigrationReport = (data) => {
     const skipped = renderSkippedConfigs(data.skippedConfigs);
     if (skipped !== null)
         sections.push(skipped);
-    const coerced = renderCoercedSentinels(data.coercedSentinels);
+    const coerced = renderCoercedSentinels(data.coercedSentinels, data.source);
     if (coerced !== null)
         sections.push(coerced);
-    const rebucketed = renderRebucketedRollouts(data.conversionNotes);
+    const rebucketed = renderRebucketedRollouts(data.conversionNotes, data.source);
     if (rebucketed !== null)
         sections.push(rebucketed);
     const conversionNotes = renderConversionNotes(data.conversionNotes, data.maintainerMap);
@@ -502,6 +560,9 @@ export const buildMigrationReport = (data) => {
     if (data.source === 'launchdarkly') {
         sections.push(LAUNCHDARKLY_BEHAVIORAL_DIFFERENCES_APPENDIX);
     }
+    if (data.source === 'flagsmith') {
+        sections.push(FLAGSMITH_BEHAVIORAL_DIFFERENCES_APPENDIX);
+    }
     return sections.join('\n\n') + '\n';
 };
 export const migrationReportPath = (outputDir) => path.join(outputDir, 'MIGRATION_REPORT.md');

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

@@ -43,7 +43,24 @@ export type ConversionNoteCategory =
 /** 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. */

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>;