@quonfig/cli 0.0.52 → 0.0.54

package/dist/commands/serve.d.ts

@@ -0,0 +1,23 @@
+/**
+ * `qfg serve` — Node-native local server that exposes a datadir over the
+ * same HTTP protocol the browser SDKs already speak. Designed to close the
+ * "browser SDKs can't read a local datadir" gap (epic qfg-38sf, plan
+ * project/plans/qfg-serve.md, Option A).
+ */
+import type { JsonObj } from '../result.js';
+import { BaseCommand } from '../index.js';
+export default class Serve extends BaseCommand {
+    static description: string;
+    static examples: string[];
+    static flags: {
+        datadir: import("@oclif/core/lib/interfaces/parser.js").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces/parser.js").CustomOptions>;
+        environment: import("@oclif/core/lib/interfaces/parser.js").OptionFlag<string, import("@oclif/core/lib/interfaces/parser.js").CustomOptions>;
+        port: import("@oclif/core/lib/interfaces/parser.js").OptionFlag<number, import("@oclif/core/lib/interfaces/parser.js").CustomOptions>;
+        host: import("@oclif/core/lib/interfaces/parser.js").OptionFlag<string, import("@oclif/core/lib/interfaces/parser.js").CustomOptions>;
+        'frontend-sdk-key': import("@oclif/core/lib/interfaces/parser.js").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces/parser.js").CustomOptions>;
+        'cors-origin': import("@oclif/core/lib/interfaces/parser.js").OptionFlag<string[], import("@oclif/core/lib/interfaces/parser.js").CustomOptions>;
+        watch: import("@oclif/core/lib/interfaces/parser.js").BooleanFlag<boolean>;
+        'allow-non-loopback': import("@oclif/core/lib/interfaces/parser.js").BooleanFlag<boolean>;
+    };
+    run(): Promise<JsonObj | void>;
+}

package/dist/commands/serve.js

@@ -0,0 +1,136 @@
+/**
+ * `qfg serve` — Node-native local server that exposes a datadir over the
+ * same HTTP protocol the browser SDKs already speak. Designed to close the
+ * "browser SDKs can't read a local datadir" gap (epic qfg-38sf, plan
+ * project/plans/qfg-serve.md, Option A).
+ */
+import { Flags } from '@oclif/core';
+import { BaseCommand } from '../index.js';
+import { resolveDatadirForServe } from '../serve/datadir-discovery.js';
+import { startServer } from '../serve/server.js';
+export default class Serve extends BaseCommand {
+    static description = `Serve a local datadir over HTTP to browser/RN SDKs.
+
+Reads configs from a local datadir and exposes them at
+\`GET /api/v2/configs/eval-with-context/{base64url(ctx)}\`. Point your
+browser SDK at the resulting URL (\`http://localhost:6580\` by default)
+and the same client code that talks to api-delivery in production will
+work unmodified.
+
+Telemetry is intentionally not served — qfg serve has no Quonfig backend
+behind it. Disable client-side telemetry with
+\`collectEvaluationSummaries: false\` (and \`contextUploadMode: "none"\`),
+or point the SDK's \`telemetryUrl\` at a real endpoint.
+
+The server is bound to 127.0.0.1 by default; pass --allow-non-loopback
+to confirm a LAN-reachable bind.`;
+    static examples = [
+        '<%= config.bin %> serve',
+        '<%= config.bin %> serve --datadir ./our-config --environment production',
+        '<%= config.bin %> serve --port 6581 --frontend-sdk-key PUBLIC_KEY',
+    ];
+    static flags = {
+        datadir: Flags.string({
+            description: 'Datadir to serve (defaults to ./our-config, then ./.quonfig, then errors). Honors QUONFIG_DIR.',
+        }),
+        environment: Flags.string({
+            default: 'development',
+            description: 'Which environment slug to evaluate. Honors QUONFIG_ENVIRONMENT.',
+        }),
+        port: Flags.integer({
+            default: 6580,
+            description: 'TCP port to listen on. Errors on collision; pass --port <n> to retry.',
+        }),
+        host: Flags.string({
+            default: '127.0.0.1',
+            description: 'Bind address. Loopback by default; non-loopback requires --allow-non-loopback.',
+        }),
+        'frontend-sdk-key': Flags.string({
+            description: 'If set, every request must present Authorization: Basic 1:<key>. ' +
+                'If unset, the server is open (matches the "datadir is the source of truth" mental model).',
+        }),
+        'cors-origin': Flags.string({
+            default: ['*'],
+            description: 'Allowed CORS origin (repeatable). Default is *; required when binding to a non-loopback host.',
+            multiple: true,
+        }),
+        watch: Flags.boolean({
+            allowNo: true,
+            default: true,
+            description: 'Reload the envelope when the datadir changes. --no-watch disables.',
+        }),
+        'allow-non-loopback': Flags.boolean({
+            default: false,
+            description: 'Confirm a LAN-reachable bind. Required when --host is not loopback.',
+        }),
+    };
+    async run() {
+        const { flags } = await this.parse(Serve);
+        const envEnvironment = process.env.QUONFIG_ENVIRONMENT;
+        const environment = flags.environment ?? envEnvironment ?? 'development';
+        const resolved = resolveDatadirForServe({
+            flagDatadir: flags.datadir,
+            envDatadir: process.env.QUONFIG_DIR,
+            cwd: process.cwd(),
+        });
+        if (resolved.kind === 'error') {
+            return this.err(resolved.message);
+        }
+        const datadir = resolved.dir;
+        if (this.isVerbose) {
+            this.verboseLog('Serve', { datadir, environment, port: flags.port, host: flags.host });
+        }
+        const logger = {
+            log: (msg) => this.log(msg),
+            warn: (msg) => this.logToStderr(msg),
+        };
+        let handle;
+        try {
+            handle = await startServer({
+                datadir,
+                environment,
+                port: flags.port,
+                host: flags.host,
+                frontendSdkKey: flags['frontend-sdk-key'],
+                corsOrigins: flags['cors-origin'],
+                watch: flags.watch,
+                allowNonLoopback: flags['allow-non-loopback'],
+                verbose: this.isVerbose,
+                logger,
+            });
+        }
+        catch (error) {
+            return this.err(error.message);
+        }
+        const url = `http://${flags.host}:${handle.port}`;
+        this.log(`qfg serve listening on ${url}`);
+        this.log(`  datadir:     ${datadir}`);
+        this.log(`  environment: ${environment}`);
+        if (flags['frontend-sdk-key']) {
+            this.log(`  auth:        required (Authorization: Basic 1:<key>)`);
+        }
+        else {
+            this.log(`  auth:        none (datadir served openly)`);
+        }
+        this.log('');
+        this.log('Point your browser SDK at the URL above:');
+        this.log(`  init({ apiUrls: ["${url}"] })`);
+        this.log('Press Ctrl-C to stop.');
+        // Block until the process is killed. The server is already accepting
+        // connections; we just need to keep the event loop alive.
+        await new Promise((resolve) => {
+            const shutdown = async () => {
+                this.log('\nqfg serve shutting down...');
+                try {
+                    await handle.close();
+                }
+                finally {
+                    resolve();
+                }
+            };
+            process.once('SIGINT', shutdown);
+            process.once('SIGTERM', shutdown);
+        });
+        return { datadir, environment, url };
+    }
+}

package/dist/commands/workspace/create.js

@@ -136,7 +136,15 @@ export default class WorkspaceCreate extends BaseCommand {
         this.log(`  Envs:        ${created.environments.map((e) => e.name).join(', ')}`);
         this.log('');
         this.log(`To use this workspace locally:`);
-        this.log(`  qfg workspace switch ${created.workspaceSlug}`);
+        // `qfg workspace switch` requires the `<org-slug>/<workspace-slug>` pin
+        // form — bare slugs are rejected. Fall back to the interactive picker if
+        // the server did not return an org slug.
+        if (created.organizationSlug) {
+            this.log(`  qfg workspace switch ${created.organizationSlug}/${created.workspaceSlug}`);
+        }
+        else {
+            this.log(`  qfg workspace switch`);
+        }
         return {
             workspaceId: created.workspaceId,
             workspaceSlug: created.workspaceSlug,

package/dist/migrate/local-write.d.ts

@@ -94,7 +94,7 @@ export interface BuildAuditFinalCommitOptions {
 }
 /**
  * qfg-wbkj: build the final state-file commit for audit-log mode. Writes
- * `.qf/import-state.json` + `MIGRATION_REPORT.md` with cumulative counts read
+ * `.qf/import-state.json` + `.qf/MIGRATION_REPORT.md` with cumulative counts read
  * from disk, and surfaces the source's accumulated dropped/skipped/coerced
  * summaries via `onAccumulatorUpdate`. The `preWrite` / `postWrite` hooks let
  * push-to-cloud merge environments and run server-side-equivalent validation

package/dist/migrate/local-write.js

@@ -301,7 +301,7 @@ export const buildAuditPerChangeCommits = (changes, source) => changes.map((chan
 });
 /**
  * qfg-wbkj: build the final state-file commit for audit-log mode. Writes
- * `.qf/import-state.json` + `MIGRATION_REPORT.md` with cumulative counts read
+ * `.qf/import-state.json` + `.qf/MIGRATION_REPORT.md` with cumulative counts read
  * from disk, and surfaces the source's accumulated dropped/skipped/coerced
  * summaries via `onAccumulatorUpdate`. The `preWrite` / `postWrite` hooks let
  * push-to-cloud merge environments and run server-side-equivalent validation

package/dist/migrate/migration-report.d.ts

@@ -85,5 +85,16 @@ export interface MigrationReportData {
  */
 export declare const deriveFollowUpFromConversionNotes: (base: FollowUpChecklist, notes: ConversionNote[] | undefined) => FollowUpChecklist;
 export declare const buildMigrationReport: (data: MigrationReportData) => string;
+/**
+ * Path of the migration report. It lives inside the `.qf/` bookkeeping
+ * directory (next to `import-state.json`), NOT the workspace root (qfg-a631).
+ *
+ * `qfg push` mirrors every non-dotfile on disk and the server's
+ * config-path-allowlist only permits `configs/`, `feature-flags/`, etc. plus
+ * `quonfig.json`/`README.md`. A root-level `MIGRATION_REPORT.md` got swept
+ * into the push and rejected ("Path not allowed by push allow-list"). Keeping
+ * it under the `.qf/` dotdir means the existing dotfile/dotdir skip in
+ * `bare-path-diff.ts` excludes it — no server change needed.
+ */
 export declare const migrationReportPath: (outputDir: string) => string;
 export declare const writeMigrationReport: (outputDir: string, data: MigrationReportData) => string;

package/dist/migrate/migration-report.js

@@ -565,10 +565,21 @@ export const buildMigrationReport = (data) => {
     }
     return sections.join('\n\n') + '\n';
 };
-export const migrationReportPath = (outputDir) => path.join(outputDir, 'MIGRATION_REPORT.md');
+/**
+ * Path of the migration report. It lives inside the `.qf/` bookkeeping
+ * directory (next to `import-state.json`), NOT the workspace root (qfg-a631).
+ *
+ * `qfg push` mirrors every non-dotfile on disk and the server's
+ * config-path-allowlist only permits `configs/`, `feature-flags/`, etc. plus
+ * `quonfig.json`/`README.md`. A root-level `MIGRATION_REPORT.md` got swept
+ * into the push and rejected ("Path not allowed by push allow-list"). Keeping
+ * it under the `.qf/` dotdir means the existing dotfile/dotdir skip in
+ * `bare-path-diff.ts` excludes it — no server change needed.
+ */
+export const migrationReportPath = (outputDir) => path.join(outputDir, '.qf', 'MIGRATION_REPORT.md');
 export const writeMigrationReport = (outputDir, data) => {
-    fs.mkdirSync(outputDir, { recursive: true });
     const filePath = migrationReportPath(outputDir);
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
     fs.writeFileSync(filePath, buildMigrationReport(data), 'utf8');
     return filePath;
 };

package/dist/migrate/push-to-cloud.d.ts

@@ -28,8 +28,8 @@ export interface PushMigrationToCloudOptions {
      * each commit authored as the original Launch user with their `changedAt` as
      * GIT_AUTHOR_DATE and `summary` as the message. One final state-file commit
      * (migrator identity, now) lands on top carrying .qf/import-state.json +
-     * MIGRATION_REPORT.md so the audit-log commits aren't polluted by bookkeeping
-     * churn. Requires that `source.getCommitMeta` be defined.
+     * .qf/MIGRATION_REPORT.md so the audit-log commits aren't polluted by
+     * bookkeeping churn. Requires that `source.getCommitMeta` be defined.
      */
     fullHistory?: boolean;
     importState: ImportState;

package/dist/migrate/source.d.ts

@@ -87,7 +87,13 @@ export interface CommitMeta {
     message: string;
 }
 export interface MigrationSource {
-    fetchChanges(sinceEpochMs: null | number): AsyncIterable<LegacyChange>;
+    /**
+     * Yields the source's change history oldest→newest. `onProgress`, when
+     * provided, is called with the running fetched-change count as pagination
+     * proceeds, so the CLI can show progress during an otherwise-silent fetch.
+     * Sources that fetch in a single request may ignore it.
+     */
+    fetchChanges(sinceEpochMs: null | number, onProgress?: (fetched: number) => void): AsyncIterable<LegacyChange>;
     /**
      * Optional post-translate accumulator. Returns any rule values that translate()
      * coerced from a sentinel like Launch's empty-string "no value set yet" to the

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

@@ -4,4 +4,4 @@ export declare function selectLaunchBaseUrl(staging: boolean): string;
 export declare function applyLaunchBaseUrl(staging: boolean): void;
 export declare function fetchEnvironments(apiKey: string): Promise<Record<string, string>>;
 export declare function fetchChangeHistoryPage(apiKey: string, cursor?: string): Promise<LaunchChangeHistoryResponse>;
-export declare function fetchAllChangeHistory(apiKey: string, sinceEpochMs?: number): Promise<LaunchChangeEntry[]>;
+export declare function fetchAllChangeHistory(apiKey: string, sinceEpochMs?: number, onProgress?: (fetched: number) => void): Promise<LaunchChangeEntry[]>;

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

@@ -49,7 +49,7 @@ export async function fetchChangeHistoryPage(apiKey, cursor) {
     }
     return (await apiFetch(`/api/v1/change-history?${params}`, apiKey));
 }
-export async function fetchAllChangeHistory(apiKey, sinceEpochMs) {
+export async function fetchAllChangeHistory(apiKey, sinceEpochMs, onProgress) {
     const collected = [];
     const seenCursors = new Set();
     let cursor;
@@ -66,6 +66,9 @@ export async function fetchAllChangeHistory(apiKey, sinceEpochMs) {
             }
             collected.push(change);
         }
+        // Report cumulative progress after each page — pagination is silent and
+        // can run for many pages (50 changes/page) on a large account.
+        onProgress?.(collected.length);
         if (done || !page.cursor || seenCursors.has(page.cursor))
             break;
         seenCursors.add(page.cursor);

package/dist/migrate/sources/launch.js

@@ -19,10 +19,10 @@ function requireApiKey(operation) {
         throw new MissingAuthError(operation);
     return state.apiKey;
 }
-async function* fetchChangesImpl(sinceEpochMs) {
+async function* fetchChangesImpl(sinceEpochMs, onProgress) {
     const apiKey = requireApiKey('fetchChanges');
     const since = sinceEpochMs === null ? undefined : sinceEpochMs;
-    const changes = await fetchAllChangeHistory(apiKey, since);
+    const changes = await fetchAllChangeHistory(apiKey, since, onProgress);
     for (const change of changes) {
         yield {
             changedAt: change.changedAt,
@@ -147,8 +147,8 @@ async function validateAuthImpl(apiKey) {
     state.coercedSentinels = new Map();
 }
 export const launchSource = {
-    fetchChanges(sinceEpochMs) {
-        return fetchChangesImpl(sinceEpochMs);
+    fetchChanges(sinceEpochMs, onProgress) {
+        return fetchChangesImpl(sinceEpochMs, onProgress);
     },
     getCoercedSentinels: getCoercedSentinelsImpl,
     getCommitMeta: getCommitMetaImpl,

package/dist/push/bare-path-diff.d.ts

@@ -27,6 +27,13 @@
 import { FileDelta } from './diff-summary.js';
 export interface BarePathDiffResult {
     deltas: FileDelta[];
+    /**
+     * The probe clone's HEAD sha — the workspace's current tip on the cloud
+     * repo. Threaded into `configs.push` as `expectedSha` so the server-side
+     * optimistic lock (qfg-gj3i) accepts bare-path pushes instead of rejecting
+     * them with a forced-upgrade 426.
+     */
+    remoteHeadSha: string;
     /** Tmp dir holding the probe clone. Caller must rm -rf in a finally block. */
     scratchDir: string;
     /** Total file count in the scratch clone (under the same prefix rules as `deltas`). */

package/dist/push/bare-path-diff.js

@@ -52,6 +52,22 @@ export async function computeBarePathDiff(localDir, remoteUrl) {
         }
         throw error;
     }
+    // The probe clone's HEAD is the workspace tip — the optimistic-lock value
+    // `configs.push` needs as `expectedSha` (qfg-gj3i bare-path follow-up).
+    let remoteHeadSha;
+    try {
+        const { stdout } = await runGit(['-C', scratchDir, 'rev-parse', 'HEAD']);
+        remoteHeadSha = stdout.trim();
+    }
+    catch (error) {
+        try {
+            fs.rmSync(scratchDir, { force: true, recursive: true });
+        }
+        catch {
+            /* ignore */
+        }
+        throw error;
+    }
     const localFiles = collectFiles(localDir);
     const remoteFiles = collectFiles(scratchDir);
     const deltas = [];
@@ -69,7 +85,7 @@ export async function computeBarePathDiff(localDir, remoteUrl) {
             deltas.push({ kind: 'deleted', path: rel, beforeJson: remote.content });
         }
     }
-    return { deltas, scratchDir, totalRemoteFiles: remoteFiles.size };
+    return { deltas, remoteHeadSha, scratchDir, totalRemoteFiles: remoteFiles.size };
 }
 /**
  * Walk `root` and return a map of relative-path -> {content, hash} for every

package/dist/push/run-push.d.ts

@@ -87,13 +87,11 @@ export interface GitOps {
     /** Pack-push — local HEAD SHA. Forwarded as `newSha` on the wire. */
     getHeadSha(dir: string): Promise<string>;
     /**
-     * Returns the local SHA of `origin/main` after fetch — the remote tip
-     * the diff was computed against — or undefined if no `origin/main` ref
-     * exists (bare-path push, or repo never fetched).
-     *
-     * Threaded into the `configs.push` call as `expectedSha` so the
-     * server-side optimistic lock (qfg-gj3i) can reject pushes whose
-     * origin moved between fetch and push.
+     * Returns the workspace-HEAD sha that the diff was computed against —
+     * threaded into `configs.push` as `expectedSha` for the server-side
+     * optimistic lock (qfg-gj3i). Clone path: the local `origin/main` SHA
+     * after fetch. Bare path: the probe clone's HEAD. Undefined only when
+     * neither is available; the server rejects a missing value with a 426.
      */
     getOriginMainSha(dir: string): Promise<string | undefined>;
     /**

package/dist/push/run-push.js

@@ -354,10 +354,10 @@ export async function runPush(input, deps) {
             ...(d.beforeJson === undefined ? {} : { beforeJson: d.beforeJson }),
             ...(d.afterJson === undefined ? {} : { afterJson: d.afterJson }),
         }));
-        // qfg-gj3i: pass origin/main SHA as expectedSha so the server-side
-        // optimistic lock can reject the push if origin moved between fetch
-        // and now. Undefined on bare-path; the server treats absence as
-        // "non-clone client" and applies its bare-path policy.
+        // qfg-gj3i: expectedSha is the workspace HEAD the server checks its
+        // optimistic lock against. For the bare path it is the probe clone's
+        // HEAD (resolved inside getOriginMainSha, qfg-nhcb). It must be present
+        // — the server rejects a missing expectedSha with a forced-upgrade 426.
         const expectedSha = await deps.gitOps.getOriginMainSha(input.dir);
         log('Sending push to Quonfig cloud...');
         const result = await deps.pushToServer({

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