@quonfig/cli 0.0.51 → 0.0.53

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

@@ -76,6 +76,29 @@ function mvOptionValue(opt) {
         return opt.integer_value ?? 0;
     return opt.string_value ?? '';
 }
+/**
+ * True when a STANDARD feature has no value payload in any env — every
+ * env-default's `feature_state_value` envelope is shaped `{type: 'unicode',
+ * boolean_value: null, integer_value: null, string_value: null}` (the default
+ * Flagsmith emits for bool-only flags). In that shape the per-env `enabled`
+ * bit IS the value; treating the flag as `string` and coercing the empty
+ * envelope to `''` would silently lose the bool. The detection is bundle-pure
+ * so both `decideValueType` and the value-emission paths can re-check it.
+ */
+function isValuelessStandardBool(bundle) {
+    const { feature, featurestates_by_env } = bundle;
+    if (feature.type !== 'STANDARD')
+        return false;
+    const envs = Object.values(featurestates_by_env);
+    if (envs.length === 0)
+        return false;
+    return envs.every((env) => {
+        const fsv = env.default?.feature_state_value;
+        if (!fsv || typeof fsv !== 'object')
+            return false;
+        return fsv.boolean_value === null && fsv.integer_value === null && fsv.string_value === null;
+    });
+}
 /**
  * Decide the feature's Quonfig valueType. Multivariate features take their
  * type from the variation values (all variants share a type in valid Flagsmith
@@ -86,6 +109,9 @@ function mvOptionValue(opt) {
 function decideValueType(bundle, report) {
     const { feature, featurestates_by_env } = bundle;
     const mvOptions = feature.multivariate_options ?? [];
+    // Value-less STANDARD feature: enabled IS the bool value (qfg-ybt9).
+    if (isValuelessStandardBool(bundle))
+        return 'bool';
     if (feature.type === 'MULTIVARIATE' && mvOptions.length > 0) {
         const variantValues = mvOptions.map((o) => mvOptionValue(o));
         const types = new Set(variantValues.map((v) => inferValueType(v)));
@@ -337,6 +363,10 @@ function flattenSegmentRuleForSegment(rule, segment, report) {
 function envDefaultRuleValue(bundle, envApiKey, fsState, ctx) {
     const { feature } = bundle;
     const mvOptions = feature.multivariate_options ?? [];
+    // Value-less STANDARD bool (qfg-ybt9): enabled IS the value; envelope is empty.
+    if (isValuelessStandardBool(bundle)) {
+        return { type: 'bool', value: fsState?.enabled ?? false };
+    }
     // enabled=false (D-F1)
     if (fsState && !fsState.enabled) {
         if (ctx.valueType === 'bool') {
@@ -369,6 +399,10 @@ function identityOverrideRuleValue(bundle, override, ctx) {
     const { feature } = bundle;
     const mvOptions = feature.multivariate_options ?? [];
     const mvWeights = override.feature_state.multivariate_feature_state_values ?? [];
+    // Value-less STANDARD bool (qfg-ybt9): override's enabled IS the value.
+    if (isValuelessStandardBool(bundle)) {
+        return { type: 'bool', value: override.feature_state.enabled };
+    }
     // enabled=false on the override: prefer the served value of the override's
     // own feature_state_value, with the same D-F1 reporting if non-boolean.
     if (!override.feature_state.enabled) {
@@ -397,6 +431,10 @@ function identityOverrideRuleValue(bundle, override, ctx) {
 function servedValueSilent(bundle, fsState, ctx) {
     const { feature } = bundle;
     const mvOptions = feature.multivariate_options ?? [];
+    // Value-less STANDARD bool (qfg-ybt9): enabled IS the value.
+    if (isValuelessStandardBool(bundle)) {
+        return { type: 'bool', value: fsState?.enabled ?? false };
+    }
     if (fsState && !fsState.enabled && ctx.valueType === 'bool') {
         return { type: 'bool', value: false };
     }
@@ -502,6 +540,14 @@ export function translateFeature(bundle, report, options = {}) {
         segmentIdByFeatureSegmentId[envApiKey] = m;
     }
     const ctx = { feature, report, segmentNameById, tagLabelById, valueType };
+    // Plan §5.4: every MULTIVARIATE feature triggers a re-bucketing note —
+    // Flagsmith and Quonfig hash identities with different salts, so individual
+    // identity → variation assignments change post-migration regardless of any
+    // per-env override structure. The overall percentage allocation is preserved.
+    if (feature.type === 'MULTIVARIATE' && (feature.multivariate_options?.length ?? 0) > 0) {
+        report.add('rebucketed-rollout', feature.name, 'multivariate feature; Flagsmith and Quonfig hash identities into buckets with different salts, so ' +
+            'individual identity → variation assignments will change after migration (the overall percentage allocation is preserved)');
+    }
     // Per-env rule list synthesis (plan §5.1, D-F2 ordering): identity overrides
     // first, then segment overrides (already sorted ASC by priority by the
     // fetcher), then the trailing ALWAYS_TRUE serving the env default.

package/dist/migrate/sources/flagsmith.js

@@ -44,7 +44,6 @@ function resolveProjectId() {
 const state = {
     apiKey: null,
     environments: [],
-    multivariateFeatures: [],
     project: null,
     projectId: resolveProjectId(),
     report: new ConversionReport(),
@@ -95,7 +94,6 @@ async function validateAuthImpl(apiKey) {
     state.project = project;
     state.report = new ConversionReport();
     state.environments = [];
-    state.multivariateFeatures = [];
     state.segments = [];
     state.tags = [];
 }
@@ -129,9 +127,6 @@ async function* fetchChangesImpl() {
     state.environments = snapshot.environments;
     state.segments = snapshot.segments;
     state.tags = snapshot.tags;
-    state.multivariateFeatures = snapshot.features
-        .filter((bundle) => bundle.feature.type === 'MULTIVARIATE' && (bundle.feature.multivariate_options?.length ?? 0) > 0)
-        .map((bundle) => bundle.feature.name);
     for (const featureBundle of snapshot.features) {
         yield {
             key: featureBundle.feature.name,
@@ -316,20 +311,6 @@ function getConversionNotesImpl() {
         return out;
     };
     const notes = state.report.all().map((n) => ({ ...n, detail: decorate(n.detail) }));
-    // Synthesize rebucketed-rollout notes for every MULTIVARIATE feature so the
-    // dedicated "Users will be re-bucketed" section in MIGRATION_REPORT.md
-    // names each one (plan §5.4). Flagsmith and Quonfig hash buckets with
-    // different salts; identity-level assignments WILL change post-migration
-    // for every MV flag, regardless of whether the allocation has any per-env
-    // overrides.
-    for (const featureName of state.multivariateFeatures) {
-        notes.push({
-            category: 'rebucketed-rollout',
-            detail: 'multivariate feature; Flagsmith and Quonfig hash identities into buckets with different salts, so ' +
-                'individual identity → variation assignments will change after migration (the overall percentage allocation is preserved)',
-            key: featureName,
-        });
-    }
     // Identity-trait references — pure FYI, no action required server-side, but
     // every trait must be sent by the SDK caller at eval time or matching rules
     // will silently miss. Plan §5.5 / D-F6.
@@ -376,7 +357,6 @@ export const flagsmithSource = {
 export function __resetFlagsmithSourceForTests() {
     state.apiKey = null;
     state.environments = [];
-    state.multivariateFeatures = [];
     state.project = null;
     state.projectId = resolveProjectId();
     state.report = new ConversionReport();

package/dist/quonfig.js

@@ -19,7 +19,6 @@ export const initQuonfig = async (_ctx, flagsOrDatafile) => {
     quonfig = new Quonfig({
         sdkKey,
         collectEvaluationSummaries: false,
-        collectLoggerCounts: false,
         contextUploadMode: 'none',
         datafile,
         enableSSE: false,

package/dist/serve/datadir-discovery.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Datadir discovery for `qfg serve`.
+ *
+ * Resolution order (plan §4):
+ *   1. --datadir flag
+ *   2. QUONFIG_DIR env var
+ *   3. ./our-config if present
+ *   4. ./.quonfig if present
+ *   5. error
+ *
+ * Kept narrow on purpose: `qfg pull`/`qfg push` use a richer
+ * `resolveWorkspaceDir` helper that walks up looking for `quonfig.json` — but
+ * `qfg serve` is intentionally cwd-relative (the user said "serve THIS dir")
+ * and the walk would surface a confusing path on a misconfigured repo. The
+ * default-pair lookup mirrors `qfg pull --dir` defaults documented in the
+ * plan.
+ */
+export declare const DEFAULT_DATADIR_CANDIDATES: readonly ["our-config", ".quonfig"];
+export declare const NO_DATADIR_ERROR: string;
+export interface ResolveDatadirInput {
+    cwd: string;
+    envDatadir: string | undefined;
+    flagDatadir: string | undefined;
+}
+export type ResolveDatadirResult = {
+    kind: 'ok';
+    dir: string;
+    source: 'flag' | 'env' | 'cwd-default';
+} | {
+    kind: 'error';
+    message: string;
+};
+export declare const resolveDatadirForServe: (input: ResolveDatadirInput) => ResolveDatadirResult;

package/dist/serve/datadir-discovery.js

@@ -0,0 +1,38 @@
+/**
+ * Datadir discovery for `qfg serve`.
+ *
+ * Resolution order (plan §4):
+ *   1. --datadir flag
+ *   2. QUONFIG_DIR env var
+ *   3. ./our-config if present
+ *   4. ./.quonfig if present
+ *   5. error
+ *
+ * Kept narrow on purpose: `qfg pull`/`qfg push` use a richer
+ * `resolveWorkspaceDir` helper that walks up looking for `quonfig.json` — but
+ * `qfg serve` is intentionally cwd-relative (the user said "serve THIS dir")
+ * and the walk would surface a confusing path on a misconfigured repo. The
+ * default-pair lookup mirrors `qfg pull --dir` defaults documented in the
+ * plan.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+export const DEFAULT_DATADIR_CANDIDATES = ['our-config', '.quonfig'];
+export const NO_DATADIR_ERROR = 'No datadir found. Pass --datadir <path>, set QUONFIG_DIR, ' +
+    `or run from a directory containing ${DEFAULT_DATADIR_CANDIDATES.map((c) => `./${c}`).join(' or ')}.`;
+const blank = (s) => s === undefined || s === '';
+export const resolveDatadirForServe = (input) => {
+    if (!blank(input.flagDatadir)) {
+        return { kind: 'ok', dir: path.resolve(input.cwd, input.flagDatadir), source: 'flag' };
+    }
+    if (!blank(input.envDatadir)) {
+        return { kind: 'ok', dir: path.resolve(input.cwd, input.envDatadir), source: 'env' };
+    }
+    for (const candidate of DEFAULT_DATADIR_CANDIDATES) {
+        const abs = path.resolve(input.cwd, candidate);
+        if (fs.existsSync(abs)) {
+            return { kind: 'ok', dir: abs, source: 'cwd-default' };
+        }
+    }
+    return { kind: 'error', message: NO_DATADIR_ERROR };
+};

package/dist/serve/handlers/evalContext.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Handler for `GET /api/v2/configs/eval-with-context/{base64url(ctx)}`.
+ *
+ * Mirrors api-delivery/internal/serve/eval_context.go so SDK clients see the
+ * same EvalEnvelope shape they get in production. The fields are:
+ *
+ *   { evaluations: { [key]: {
+ *       value: { type, value, confidential?, decryptWith? },
+ *       configId, configType, valueType, reason,
+ *       ruleIndex?, weightedValueIndex?
+ *     } },
+ *     meta: { version, environment }
+ *   }
+ *
+ * `reason` follows the cross-SDK spec
+ * `project/plans/openfeature-resolution-details.md`:
+ *   - "SPLIT"            for weighted-value flags
+ *   - "TARGETING_MATCH"  for configs whose matched rule has a non-ALWAYS_TRUE criterion
+ *   - "STATIC"           otherwise
+ *
+ * `ruleIndex` and `weightedValueIndex` are emitted only when the reason class
+ * carries useful information (TARGETING_MATCH or SPLIT). This matches the Go
+ * handler's "omit, don't null" rule.
+ */
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import type { Evaluator, ConfigStore } from '@quonfig/node';
+export interface EvalEnvelope {
+    evaluations: Record<string, EvalResult>;
+    meta: {
+        version: string;
+        environment: string;
+    };
+}
+export interface EvalResult {
+    configId: string;
+    configType: string;
+    reason: string;
+    ruleIndex?: number;
+    value: {
+        type: string;
+        value: unknown;
+        confidential?: boolean;
+        decryptWith?: string;
+    };
+    valueType: string;
+    weightedValueIndex?: number;
+}
+export interface EvalHandlerDeps {
+    /**
+     * Snapshot accessor — returns the *current* store + evaluator + meta. We
+     * read this on every request so that auto-reload swaps under us
+     * transparently.
+     *
+     * Note (qfg-38sf.1 audit, F3): the sendToClientSdk filter is unconditional
+     * and lives inside this handler. There is no `frontendFilter` toggle —
+     * every qfg serve consumer is a frontend client by definition, so the
+     * filter always applies.
+     */
+    getSnapshot(): {
+        store: ConfigStore;
+        evaluator: Evaluator;
+        environment: string;
+        version: string;
+    };
+}
+export declare function handleEvalContext(req: IncomingMessage, res: ServerResponse, ctxToken: string, deps: EvalHandlerDeps): Promise<void>;

package/dist/serve/handlers/evalContext.js

@@ -0,0 +1,170 @@
+/**
+ * Handler for `GET /api/v2/configs/eval-with-context/{base64url(ctx)}`.
+ *
+ * Mirrors api-delivery/internal/serve/eval_context.go so SDK clients see the
+ * same EvalEnvelope shape they get in production. The fields are:
+ *
+ *   { evaluations: { [key]: {
+ *       value: { type, value, confidential?, decryptWith? },
+ *       configId, configType, valueType, reason,
+ *       ruleIndex?, weightedValueIndex?
+ *     } },
+ *     meta: { version, environment }
+ *   }
+ *
+ * `reason` follows the cross-SDK spec
+ * `project/plans/openfeature-resolution-details.md`:
+ *   - "SPLIT"            for weighted-value flags
+ *   - "TARGETING_MATCH"  for configs whose matched rule has a non-ALWAYS_TRUE criterion
+ *   - "STATIC"           otherwise
+ *
+ * `ruleIndex` and `weightedValueIndex` are emitted only when the reason class
+ * carries useful information (TARGETING_MATCH or SPLIT). This matches the Go
+ * handler's "omit, don't null" rule.
+ */
+/**
+ * G6 (qfg-38sf.1 audit): cap on the raw base64 context token length before
+ * we allocate a Buffer for it. 64 KB is well above the realistic size of any
+ * SDK-sent context envelope (Quonfig contexts are typically a few hundred
+ * bytes; the SDK base64-encodes a small JSON object) while still bounded
+ * enough to prevent a malicious client from forcing the server to allocate
+ * a multi-megabyte buffer per request.
+ */
+const MAX_CTX_TOKEN_BYTES = 64 * 1024;
+export async function handleEvalContext(req, res, ctxToken, deps) {
+    // G6: bound the token size BEFORE we decode it. The 64KB cap is way above
+    // realistic context payloads and small enough that a malicious caller
+    // can't trick us into allocating gigabytes. 414 URI Too Long is the right
+    // status — RFC 7231 §6.5.12 covers exactly this case (the URL is the
+    // request-target, the ctx is a path segment, so it's a URI-length problem,
+    // not a body-length problem).
+    if (ctxToken.length > MAX_CTX_TOKEN_BYTES) {
+        res.writeHead(414, { 'Content-Type': 'text/plain' });
+        res.end('context token too large');
+        return;
+    }
+    // base64url decode → JSON. We accept the URL-safe alphabet and the
+    // standard one because the Go handler does (`base64.URLEncoding`,
+    // `StdEncoding`, `RawURLEncoding` — Node's "base64url" parser already
+    // covers the no-padding URL-safe case; we try standard as a fallback).
+    let contextData;
+    try {
+        let json;
+        try {
+            json = Buffer.from(ctxToken, 'base64url').toString('utf8');
+        }
+        catch {
+            json = Buffer.from(ctxToken, 'base64').toString('utf8');
+        }
+        contextData = JSON.parse(json);
+    }
+    catch {
+        res.writeHead(400, { 'Content-Type': 'text/plain' });
+        res.end('invalid context token encoding');
+        return;
+    }
+    const snap = deps.getSnapshot();
+    const evaluations = {};
+    // The SDK's Evaluator takes a `Contexts` map shaped exactly like the JSON
+    // we just decoded: { [contextName]: { [key]: value } }. No translation
+    // needed.
+    for (const key of snap.store.keys()) {
+        const cfg = snap.store.get(key);
+        if (!cfg)
+            continue;
+        // F3 (qfg-38sf.1 audit): UNCONDITIONAL sendToClientSdk filter. Every qfg
+        // serve consumer is a frontend client by definition, so we apply the
+        // same gate api-delivery uses for frontend SDK keys
+        // (eval_context.go:103) regardless of whether --frontend-sdk-key was
+        // passed. Feature flags bypass the filter, matching the Go behavior.
+        if (cfg.type !== 'feature_flag' && !cfg.sendToClientSdk) {
+            continue;
+        }
+        const match = snap.evaluator.evaluateConfig(cfg, snap.environment, contextData);
+        if (!match.isMatch || match.value === undefined)
+            continue;
+        const reason = resolutionReason(cfg, match);
+        const result = {
+            value: {
+                type: match.value.type,
+                value: coerceNumeric(match.value.type, match.value.value),
+            },
+            configId: cfg.id,
+            configType: cfg.type,
+            valueType: cfg.valueType,
+            reason,
+        };
+        if (match.value.confidential !== undefined)
+            result.value.confidential = match.value.confidential;
+        if (match.value.decryptWith !== undefined)
+            result.value.decryptWith = match.value.decryptWith;
+        if (reason === 'TARGETING_MATCH' || reason === 'SPLIT') {
+            result.ruleIndex = match.ruleIndex;
+        }
+        if (reason === 'SPLIT') {
+            result.weightedValueIndex = match.weightedValueIndex;
+        }
+        evaluations[cfg.key] = result;
+    }
+    const envelope = {
+        evaluations,
+        meta: { version: snap.version, environment: snap.environment },
+    };
+    res.writeHead(200, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify(envelope));
+}
+/**
+ * qfg-38sf.7: coerce `int`/`double` values to JS numbers so the envelope emits
+ * JSON numbers, not JSON strings.
+ *
+ * Config files (and integration-test-data) store numeric values as JSON
+ * strings — e.g. `{"type": "int", "value": "5"}`. api-delivery's
+ * `Value.UnmarshalJSON` (api-delivery/internal/config/types.go:182-215) coerces
+ * `int` via `strconv.ParseInt` and `double` via `strconv.ParseFloat` at config
+ * *load* time, so its EvalEnvelope emits JSON numbers. sdk-node's datadir
+ * loader does no such coercion and passes the value through verbatim, so
+ * `match.value.value` arrives here as a string. We coerce on output to match
+ * api-delivery — a browser SDK consumer doing arithmetic on an integer flag
+ * would otherwise get string-concatenation behavior.
+ *
+ * Discriminate on `valueType` — the value's *own* type, the same field
+ * api-delivery switches on (`raw.Type`). This is correct even when the matched
+ * value's type differs from the config's declared `valueType` (e.g. a
+ * weighted-values config resolving to an `int` arm). ONLY `int` and `double`
+ * are coerced; `string`, `bool`, `string_list`, `json`, `provided`, etc. pass
+ * through untouched. Integration-test-data's largest numeric value is ~2.5e12,
+ * far below Number.MAX_SAFE_INTEGER, so `Number(...)` is lossless here.
+ */
+function coerceNumeric(valueType, value) {
+    if ((valueType === 'int' || valueType === 'double') && typeof value === 'string') {
+        const n = Number(value);
+        return Number.isNaN(n) ? value : n;
+    }
+    return value;
+}
+function resolutionReason(cfg, _match) {
+    if (cfg.valueType === 'weighted_values')
+        return 'SPLIT';
+    if (hasResolutionTargeting(cfg))
+        return 'TARGETING_MATCH';
+    return 'STATIC';
+}
+function hasResolutionTargeting(cfg) {
+    if (rulesAreTargeted(cfg.default?.rules))
+        return true;
+    const envRules = cfg.environment?.rules;
+    if (rulesAreTargeted(envRules))
+        return true;
+    return false;
+}
+function rulesAreTargeted(rules) {
+    if (!rules)
+        return false;
+    for (const rule of rules) {
+        for (const criterion of rule.criteria) {
+            if (criterion.operator !== 'ALWAYS_TRUE')
+                return true;
+        }
+    }
+    return false;
+}

package/dist/serve/server.d.ts

@@ -0,0 +1,53 @@
+/**
+ * HTTP server for `qfg serve`. Boots a single `@quonfig/node` Quonfig client
+ * with `{datadir, dataDirAutoReload}` so file changes flow into a shared
+ * snapshot (mirror of the SDK's `ConfigStore`). All requests evaluate against
+ * that snapshot — see plan project/plans/qfg-serve.md §5 ("Integration with
+ * auto-reload work").
+ *
+ * Bound by default to 127.0.0.1. Auth and CORS are configured per plan §4.
+ */
+import type { ConfigResponse } from '@quonfig/node';
+export interface Logger {
+    log: (msg: string) => void;
+    warn: (msg: string) => void;
+}
+export interface ServeOptions {
+    allowNonLoopback: boolean;
+    corsOrigins: string[];
+    datadir: string;
+    environment: string;
+    /**
+     * Test-only escape hatch — startServer treats this string as the bind host
+     * for the loopback / non-loopback policy check, while still actually
+     * binding to `host`. Lets unit tests assert the WARN path without binding
+     * 0.0.0.0 in CI (which some networks forbid). NOT a public option.
+     */
+    forceNonLoopbackForTest?: string;
+    frontendSdkKey?: string;
+    host: string;
+    logger: Logger;
+    port: number;
+    verbose: boolean;
+    watch: boolean;
+    /** Override the SDK's 200ms default debounce; lets tests check the watch path quickly. */
+    watchDebounceMs?: number;
+}
+export interface ServeHandle {
+    /** Stop watching, close all sockets, await SDK close. Idempotent. */
+    close(): Promise<void>;
+    host: string;
+    port: number;
+}
+export declare function startServer(opts: ServeOptions): Promise<ServeHandle>;
+/**
+ * G8 (qfg-38sf.6): compute meta.version as sha256 of the canonicalized
+ * configs array. Canonical form is `JSON.stringify(configs, sortedKeys)` so
+ * two snapshots with identical config content produce the same hash regardless
+ * of object-key order. The hash replaces the prior `datadir:<abs-path>#<ts>`
+ * shape, which leaked operator filesystem layout and changed on every reload
+ * even when the data was unchanged.
+ *
+ * Exported for unit tests that want to assert determinism / stability.
+ */
+export declare function computeVersion(configs: ConfigResponse[]): string;