@quonfig/cli 0.0.15 → 0.0.17

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

@@ -1,4 +1,5 @@
 import type { IdentifierMap } from './identifier-map.js';
+import type { DroppedOverrideSummary, DuplicateResolutionSummary, SkippedConfigSummary } from './source.js';
 export interface MigrationReportCounts {
     environmentsMapped: number;
     flagsMigrated: number;
@@ -29,11 +30,28 @@ export interface FollowUpChecklist {
 export interface MigrationReportData {
     cleanMappings: CleanMapping[];
     counts: MigrationReportCounts;
+    /**
+     * Override sections that were dropped during translate() because the env.id was not
+     * present in the source's env map (e.g. archived/deleted Reforge envs). Null when
+     * nothing was dropped.
+     */
+    droppedOverrides?: DroppedOverrideSummary | null;
     dryRun: boolean;
+    /**
+     * Cross-type key collisions resolved by keeping the config side and deleting
+     * the non-config type(s). Null when none were detected. Customers should
+     * review each entry and clean up the source data to avoid the collision.
+     */
+    duplicateResolutions?: DuplicateResolutionSummary | null;
     environmentMap: EnvironmentMapEntry[];
     followUp: FollowUpChecklist;
     identifierMap: IdentifierMap;
     lossyMappings: LossyMapping[];
+    /**
+     * Configs soft-skipped by translate() because the source data was invalid
+     * (e.g. variant/valueType mismatch). Null when nothing was skipped.
+     */
+    skippedConfigs?: SkippedConfigSummary | null;
     source: string;
     unsupportedFeatures: UnsupportedFeature[];
 }

package/dist/migrate/migration-report.js

@@ -49,6 +49,59 @@ const renderIdentifierMap = (map) => {
     const rows = sorted.map((k) => `| \`${k}\` | \`${map[k]}\` |`);
     return [header, '', '| Legacy key | Quonfig key |', '| --- | --- |', ...rows].join('\n');
 };
+const renderDroppedOverrides = (dropped) => {
+    if (!dropped || dropped.total === 0)
+        return null;
+    const envIds = Object.keys(dropped.byEnv).sort();
+    const lines = [
+        '## Dropped override sections',
+        '',
+        `Dropped **${dropped.total}** override section(s) referencing **${envIds.length}** env ID(s) not present in the source's env list (likely archived/deleted). If any of these envs are still in use, restore them in the source system and re-run the migration.`,
+    ];
+    for (const envId of envIds) {
+        const perFlag = dropped.byEnv[envId];
+        const totalForEnv = Object.values(perFlag).reduce((s, n) => s + n, 0);
+        const flagCount = Object.keys(perFlag).length;
+        lines.push('', `### env-${envId} — ${totalForEnv} dropped from ${flagCount} flag(s)`, '');
+        const sorted = Object.keys(perFlag).sort();
+        for (const flagPath of sorted) {
+            lines.push(`- \`${flagPath}\` (${perFlag[flagPath]})`);
+        }
+    }
+    return lines.join('\n');
+};
+const renderDuplicateResolutions = (resolved) => {
+    if (!resolved || resolved.total === 0)
+        return null;
+    const lines = [
+        '## Resolved cross-type duplicates',
+        '',
+        `Reforge had **${resolved.total}** key(s) present as both a config and a feature_flag (or other types) at the same time. qfg requires globally-unique keys, so the migrator kept the **config** side and deleted the other type(s). Review each and clean up the source system so the collision stops recurring.`,
+        '',
+    ];
+    const sorted = [...resolved.entries].sort((a, b) => a.key.localeCompare(b.key));
+    for (const entry of sorted) {
+        lines.push(`- \`${entry.key}\` (${entry.collisionTypes.join(', ')}): kept \`${entry.kept}\`, deleted ${entry.deleted
+            .map((p) => `\`${p}\``)
+            .join(', ')}`);
+    }
+    return lines.join('\n');
+};
+const renderSkippedConfigs = (skipped) => {
+    if (!skipped || skipped.total === 0)
+        return null;
+    const lines = [
+        '## Skipped invalid configs',
+        '',
+        `Skipped **${skipped.total}** config(s) with structurally invalid source data — the migrator refused to emit them rather than ship broken data. Fix each in the source system and re-run.`,
+        '',
+    ];
+    const sorted = [...skipped.entries].sort((a, b) => a.key.localeCompare(b.key));
+    for (const entry of sorted) {
+        lines.push(`- \`${entry.key}\` — ${entry.reason}`);
+    }
+    return lines.join('\n');
+};
 const renderFollowUp = (followUp) => {
     const must = followUp.mustFixBeforeCutover.length === 0
         ? NONE
@@ -73,7 +126,17 @@ export const buildMigrationReport = (data) => {
     if (data.dryRun) {
         sections.push('> **DRY RUN** — no files were written to the workspace during this run.');
     }
-    sections.push(`# Migration Report (from ${data.source})`, `_Reflects only the changes produced by this run. Re-running overwrites this file._`, renderCounts(data.counts), renderCleanMappings(data.cleanMappings), renderLossyMappings(data.lossyMappings), renderUnsupported(data.unsupportedFeatures), renderEnvironmentMap(data.environmentMap), renderIdentifierMap(data.identifierMap), renderFollowUp(data.followUp));
+    sections.push(`# Migration Report (from ${data.source})`, `_Reflects only the changes produced by this run. Re-running overwrites this file._`, renderCounts(data.counts), renderCleanMappings(data.cleanMappings), renderLossyMappings(data.lossyMappings), renderUnsupported(data.unsupportedFeatures), renderEnvironmentMap(data.environmentMap), renderIdentifierMap(data.identifierMap));
+    const dropped = renderDroppedOverrides(data.droppedOverrides);
+    if (dropped !== null)
+        sections.push(dropped);
+    const resolved = renderDuplicateResolutions(data.duplicateResolutions);
+    if (resolved !== null)
+        sections.push(resolved);
+    const skipped = renderSkippedConfigs(data.skippedConfigs);
+    if (skipped !== null)
+        sections.push(skipped);
+    sections.push(renderFollowUp(data.followUp));
     return sections.join('\n\n') + '\n';
 };
 export const migrationReportPath = (outputDir) => path.join(outputDir, 'MIGRATION_REPORT.md');

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

@@ -1,15 +1,26 @@
 import { type ImportState } from './import-state.js';
 import { type MigrationReportData } from './migration-report.js';
-import { type CloneAndStackPushResult } from './push-strategy.js';
-import type { LegacyChange, MigrationSource } from './source.js';
+import { type CloneAndStackPushResult } from '../util/clone-and-stack-push.js';
+import type { DroppedOverrideSummary, DuplicateResolutionSummary, LegacyChange, MigrationSource, SkippedConfigSummary } from './source.js';
 export interface PushMigrationToCloudOptions {
     branch?: string;
     changes: LegacyChange[];
     commitMessage: string;
+    /**
+     * Source-side environments (slugified). Additively merged into the target
+     * workspace's quonfig.json so flag files that reference these envs verify
+     * cleanly. Existing target-only envs are preserved.
+     */
+    environments?: string[];
     importState: ImportState;
     localDir: string;
     remoteUrl: string;
     reportData: MigrationReportData;
     source: MigrationSource;
 }
-export declare const pushMigrationToCloud: (opts: PushMigrationToCloudOptions) => Promise<CloneAndStackPushResult>;
+export interface PushMigrationToCloudResult extends CloneAndStackPushResult {
+    droppedOverrides: DroppedOverrideSummary | null;
+    duplicateResolutions: DuplicateResolutionSummary | null;
+    skippedConfigs: SkippedConfigSummary | null;
+}
+export declare const pushMigrationToCloud: (opts: PushMigrationToCloudOptions) => Promise<PushMigrationToCloudResult>;

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

@@ -2,24 +2,94 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { removeQfFromGitignore, writeImportState } from './import-state.js';
 import { writeMigrationReport } from './migration-report.js';
-import { cloneAndStackPush } from './push-strategy.js';
+import { detectDuplicateKeys } from './sources/launch/translate.js';
+import { cloneAndStackPush } from '../util/clone-and-stack-push.js';
 const writeQuonfigFiles = (dir, changes, source) => {
+    const livePaths = new Map();
     for (const change of changes) {
         const files = source.translate(change);
         for (const file of files) {
             const full = path.join(dir, file.path);
-            fs.mkdirSync(path.dirname(full), { recursive: true });
-            fs.writeFileSync(full, file.contents);
+            if (file.deleted) {
+                try {
+                    fs.unlinkSync(full);
+                }
+                catch (error) {
+                    if (error.code !== 'ENOENT')
+                        throw error;
+                }
+                livePaths.delete(file.path);
+            }
+            else {
+                if (file.contents === undefined) {
+                    throw new Error(`translate() emitted a write op for ${file.path} without contents`);
+                }
+                fs.mkdirSync(path.dirname(full), { recursive: true });
+                fs.writeFileSync(full, file.contents);
+                livePaths.set(file.path, true);
+            }
         }
     }
+    const resolutions = detectDuplicateKeys([...livePaths.keys()].map((p) => ({ path: p })));
+    for (const resolution of resolutions) {
+        for (const toDelete of resolution.deleted) {
+            try {
+                fs.unlinkSync(path.join(dir, toDelete));
+            }
+            catch (error) {
+                if (error.code !== 'ENOENT')
+                    throw error;
+            }
+            livePaths.delete(toDelete);
+        }
+    }
+    return resolutions;
+};
+const QUONFIG_JSON_FILENAME = 'quonfig.json';
+const mergeEnvironmentsIntoQuonfigJson = (dir, sourceEnvs) => {
+    const quonfigPath = path.join(dir, QUONFIG_JSON_FILENAME);
+    let existing = {};
+    if (fs.existsSync(quonfigPath)) {
+        try {
+            existing = JSON.parse(fs.readFileSync(quonfigPath, 'utf8'));
+        }
+        catch {
+            existing = {};
+        }
+    }
+    const existingEnvs = Array.isArray(existing.environments) ? existing.environments : [];
+    const merged = [...new Set([...existingEnvs, ...sourceEnvs])].sort();
+    if (existingEnvs.length === merged.length &&
+        existingEnvs.every((e, i) => e === merged[i])) {
+        return;
+    }
+    fs.writeFileSync(quonfigPath, JSON.stringify({ ...existing, environments: merged }, null, 2) + '\n', 'utf8');
 };
 export const pushMigrationToCloud = async (opts) => {
+    let droppedOverrides = null;
+    let duplicateResolutions = null;
+    let skippedConfigs = null;
     const cloneOpts = {
         applyDelta(dir) {
-            writeQuonfigFiles(dir, opts.changes, opts.source);
+            if (opts.environments && opts.environments.length > 0) {
+                mergeEnvironmentsIntoQuonfigJson(dir, opts.environments);
+            }
+            const resolutionEntries = writeQuonfigFiles(dir, opts.changes, opts.source);
             removeQfFromGitignore(dir);
             writeImportState(dir, opts.importState);
-            writeMigrationReport(dir, opts.reportData);
+            droppedOverrides = opts.source.getDroppedOverrides?.() ?? null;
+            skippedConfigs = opts.source.getSkippedConfigs?.() ?? null;
+            duplicateResolutions =
+                resolutionEntries.length > 0
+                    ? { entries: resolutionEntries, total: resolutionEntries.length }
+                    : null;
+            const reportData = {
+                ...opts.reportData,
+                ...(droppedOverrides ? { droppedOverrides } : {}),
+                ...(duplicateResolutions ? { duplicateResolutions } : {}),
+                ...(skippedConfigs ? { skippedConfigs } : {}),
+            };
+            writeMigrationReport(dir, reportData);
         },
         commitMessage: opts.commitMessage,
         localDir: opts.localDir,
@@ -27,5 +97,6 @@ export const pushMigrationToCloud = async (opts) => {
     };
     if (opts.branch !== undefined)
         cloneOpts.branch = opts.branch;
-    return cloneAndStackPush(cloneOpts);
+    const result = await cloneAndStackPush(cloneOpts);
+    return { ...result, droppedOverrides, duplicateResolutions, skippedConfigs };
 };

package/dist/migrate/source.d.ts

@@ -5,11 +5,60 @@ export interface LegacyChange {
     source: string;
 }
 export interface QuonfigFile {
-    contents: string;
+    /** File contents when writing. Ignored when deleted is true. */
+    contents?: string;
+    /** When true, the file at `path` should be removed (tombstone). Default false. */
+    deleted?: boolean;
     path: string;
 }
+export interface DroppedOverrideSummary {
+    /** Per-envId → per-output-path count of dropped override sections. */
+    byEnv: Record<string, Record<string, number>>;
+    /** Total override sections dropped across every env + flag. */
+    total: number;
+}
+export interface SkippedConfigEntry {
+    /** Source key (pre-translate) that was skipped. */
+    key: string;
+    /** Human-readable reason (e.g. variant/valueType mismatch). */
+    reason: string;
+}
+export interface SkippedConfigSummary {
+    /** Individual skip records, in insertion order. */
+    entries: SkippedConfigEntry[];
+    /** Total configs skipped. */
+    total: number;
+}
+export interface DuplicateResolution {
+    /** All types that collided for this key (e.g. ['config', 'feature_flag']). */
+    collisionTypes: string[];
+    /** Paths that were deleted to resolve the collision. */
+    deleted: string[];
+    /** The path that was kept as the winning type. */
+    kept: string;
+    /** The qfg key that collided across types. */
+    key: string;
+}
+export interface DuplicateResolutionSummary {
+    entries: DuplicateResolution[];
+    total: number;
+}
 export interface MigrationSource {
     fetchChanges(sinceEpochMs: null | number): AsyncIterable<LegacyChange>;
+    /**
+     * Optional post-translate accumulator. Returns any override sections that were
+     * dropped during translate() calls because the env.id was not present in the
+     * source's env map (e.g. archived/deleted Reforge envs). Returns null if nothing
+     * was dropped. Callers should consume + surface this before writing the migration
+     * report so customers can review the loss.
+     */
+    getDroppedOverrides?(): DroppedOverrideSummary | null;
+    /**
+     * Optional post-translate accumulator. Returns any configs that translate() soft-
+     * skipped due to invalid source data (e.g. variant/valueType mismatch). Null when
+     * nothing was skipped.
+     */
+    getSkippedConfigs?(): SkippedConfigSummary | null;
     listEnvironments(): Promise<string[]>;
     name: string;
     translate(change: LegacyChange): QuonfigFile[];

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

@@ -1,6 +1,32 @@
 import type { LaunchChangeEntry, LaunchChangeGroup, LaunchConfig } from './types.js';
+/**
+ * Thrown by transformConfig when the source config is structurally invalid
+ * (e.g. variant/valueType mismatch) and the migrator cannot produce a valid
+ * qfg document from it. Callers in the source layer catch this specifically
+ * to soft-skip the config with a warning rather than aborting the whole run.
+ */
+export declare class InvalidSourceConfigError extends Error {
+    constructor(message: string);
+}
 export declare function slugify(value: string): string;
 export declare function isLegacyLogLevel(type: string): boolean;
-export declare function transformConfig(config: LaunchConfig, envIdMap: Record<string, string>): Record<string, unknown>;
+export declare function normalizeLogLevelKey(key: string): string;
+export declare function transformConfig(config: LaunchConfig, envIdMap: Record<string, string>, onDroppedEnv?: (envId: string) => void): Record<string, unknown>;
 export declare function getOutputPath(type: string, key: string): string;
+/**
+ * Walks the set of written files looking for cross-type collisions (the same
+ * key appearing in multiple type-dirs). Reforge occasionally produces a config
+ * and a feature_flag with the same key simultaneously — qfg requires globally-
+ * unique keys, so we resolve the collision by keeping the config side and
+ * marking the other side(s) for deletion. Callers should fs.unlinkSync the
+ * paths in each resolution's `deleted` array and surface the resolutions in
+ * stderr + MIGRATION_REPORT.md so the customer can clean up the source data.
+ *
+ * When the collision does NOT include 'config' (an unexpected pattern we have
+ * not observed in production data), we still throw so the case surfaces for
+ * review rather than silently picking a tiebreak.
+ */
+export declare function detectDuplicateKeys(files: Array<{
+    path: string;
+}>): import('../../source.js').DuplicateResolution[];
 export declare function groupChanges(changes: LaunchChangeEntry[]): LaunchChangeGroup[];

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

@@ -1,3 +1,16 @@
+import { zodToJsonSchema } from './zod-to-json-schema.js';
+/**
+ * Thrown by transformConfig when the source config is structurally invalid
+ * (e.g. variant/valueType mismatch) and the migrator cannot produce a valid
+ * qfg document from it. Callers in the source layer catch this specifically
+ * to soft-skip the config with a warning rather than aborting the whole run.
+ */
+export class InvalidSourceConfigError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'InvalidSourceConfigError';
+    }
+}
 export function slugify(value) {
     return value
         .toLowerCase()
@@ -7,6 +20,9 @@ export function slugify(value) {
 export function isLegacyLogLevel(type) {
     return type.toUpperCase() === 'LOG_LEVEL';
 }
+export function normalizeLogLevelKey(key) {
+    return key.startsWith('log-level.') ? key : `log-level.${key}`;
+}
 function zeroValue(valueType) {
     switch (valueType) {
         case 'bool': {
@@ -106,7 +122,7 @@ function normalizeJsonValuesInConfig(out) {
         }
     }
 }
-export function transformConfig(config, envIdMap) {
+export function transformConfig(config, envIdMap, onDroppedEnv) {
     const out = JSON.parse(JSON.stringify(config));
     delete out.changedBy;
     delete out.modifiedAt;
@@ -121,24 +137,61 @@ export function transformConfig(config, envIdMap) {
     if (typeof out.valueType === 'string' && out.valueType.toUpperCase() === 'LOG_LEVEL_V2') {
         out.valueType = 'log_level';
     }
+    if (out.type === 'log_level' && typeof out.key === 'string') {
+        out.key = normalizeLogLevelKey(out.key);
+    }
     if (typeof out.type === 'string' && out.type.toLowerCase() === 'schema') {
-        throw new Error(`Schema-type configs are not yet supported by qfg migrate --from launch. ` +
-            `File a bead to prioritize this: https://github.com/quonfig/cli/issues/new?title=qfg+migrate+schema+configs`);
+        const defaultSection = out.default;
+        const firstRule = defaultSection?.rules?.[0];
+        const innerValue = firstRule?.value?.value;
+        if (!innerValue || innerValue.schemaType !== 'ZOD' || typeof innerValue.schema !== 'string') {
+            throw new Error(`Unsupported schema payload for ${String(out.key ?? 'unknown')}`);
+        }
+        const key = String(out.key ?? 'unknown');
+        let converted;
+        try {
+            converted = zodToJsonSchema(innerValue.schema);
+        }
+        catch (error) {
+            const msg = error instanceof Error ? error.message : String(error);
+            throw new Error(`Schema conversion failed for "${key}": ${msg}\n--- Zod source ---\n${innerValue.schema}\n--- end ---`);
+        }
+        return converted.schema;
     }
     if (Array.isArray(out.environments)) {
+        const kept = [];
         for (const env of out.environments) {
             if (typeof env.id === 'string') {
-                const name = envIdMap[env.id] ?? `env-${env.id}`;
+                const name = envIdMap[env.id];
+                if (name === undefined) {
+                    onDroppedEnv?.(env.id);
+                    continue;
+                }
                 env.id = slugify(name);
             }
+            kept.push(env);
+        }
+        out.environments = kept;
+    }
+    if (typeof out.valueType === 'string' &&
+        Array.isArray(out.variants) &&
+        !['provided', 'schema', 'weighted_values'].includes(out.valueType)) {
+        const configKey = String(out.key ?? 'unknown');
+        for (const [i, variant] of out.variants.entries()) {
+            const v = variant?.value;
+            if (v && typeof v.type === 'string' && v.type !== out.valueType) {
+                throw new InvalidSourceConfigError(`Variant type mismatch for "${configKey}" at variants[${i}]: value type "${v.type}" does not match config valueType "${String(out.valueType)}"`);
+            }
         }
     }
     if (!out.default && typeof out.valueType === 'string') {
+        const variants = Array.isArray(out.variants) ? out.variants : [];
+        const firstVariantValue = variants.length > 0 && variants[0] && typeof variants[0] === 'object' ? variants[0].value : undefined;
         out.default = {
             rules: [
                 {
                     criteria: [{ operator: 'ALWAYS_TRUE' }],
-                    value: zeroValue(out.valueType),
+                    value: firstVariantValue ?? zeroValue(out.valueType),
                 },
             ],
         };
@@ -153,7 +206,7 @@ export function getOutputPath(type, key) {
             return `feature-flags/${key}.json`;
         }
         case 'LOG_LEVEL_V2': {
-            return `log-levels/${key}.json`;
+            return `log-levels/${normalizeLogLevelKey(key)}.json`;
         }
         case 'SCHEMA': {
             return `schemas/${key}.json`;
@@ -166,6 +219,70 @@ export function getOutputPath(type, key) {
         }
     }
 }
+const PATH_DIR_TO_TYPE = {
+    configs: 'config',
+    'feature-flags': 'feature_flag',
+    'log-levels': 'log_level',
+    schemas: 'schema',
+    segments: 'segment',
+};
+const TYPE_TO_DIR = Object.fromEntries(Object.entries(PATH_DIR_TO_TYPE).map(([dir, type]) => [type, dir]));
+/**
+ * Walks the set of written files looking for cross-type collisions (the same
+ * key appearing in multiple type-dirs). Reforge occasionally produces a config
+ * and a feature_flag with the same key simultaneously — qfg requires globally-
+ * unique keys, so we resolve the collision by keeping the config side and
+ * marking the other side(s) for deletion. Callers should fs.unlinkSync the
+ * paths in each resolution's `deleted` array and surface the resolutions in
+ * stderr + MIGRATION_REPORT.md so the customer can clean up the source data.
+ *
+ * When the collision does NOT include 'config' (an unexpected pattern we have
+ * not observed in production data), we still throw so the case surfaces for
+ * review rather than silently picking a tiebreak.
+ */
+export function detectDuplicateKeys(files) {
+    const keyToTypes = new Map();
+    for (const { path } of files) {
+        const firstSlash = path.indexOf('/');
+        if (firstSlash < 0)
+            continue;
+        const dir = path.slice(0, firstSlash);
+        const type = PATH_DIR_TO_TYPE[dir];
+        if (!type)
+            continue;
+        const file = path.slice(firstSlash + 1);
+        const key = file.replace(/\.json$/, '');
+        const set = keyToTypes.get(key) ?? new Set();
+        set.add(type);
+        keyToTypes.set(key, set);
+    }
+    const resolutions = [];
+    const unexpected = [];
+    for (const [key, types] of [...keyToTypes.entries()].sort(([a], [b]) => a.localeCompare(b))) {
+        if (types.size <= 1)
+            continue;
+        if (!types.has('config')) {
+            unexpected.push(`"${key}" (types: ${[...types].sort().join(', ')})`);
+            continue;
+        }
+        const kept = `configs/${key}.json`;
+        const deleted = [];
+        for (const type of [...types].sort()) {
+            if (type === 'config')
+                continue;
+            const dir = TYPE_TO_DIR[type];
+            if (!dir)
+                continue;
+            deleted.push(`${dir}/${key}.json`);
+        }
+        resolutions.push({ collisionTypes: [...types].sort(), deleted, kept, key });
+    }
+    if (unexpected.length > 0) {
+        throw new Error(`Unexpected cross-type key collision — no 'config' side to tiebreak on. ` +
+            `Please file a bead with the source data details:\n  ${unexpected.join('\n  ')}`);
+    }
+    return resolutions;
+}
 export function groupChanges(changes) {
     const groups = new Map();
     for (const change of changes) {

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

@@ -35,6 +35,9 @@ export interface LaunchConfig {
     sendToClientSdk?: boolean;
     type: string;
     valueType: string;
+    variants?: Array<{
+        value?: LaunchValue;
+    }>;
 }
 export interface LaunchChangeEntry {
     changedAt: number;

package/dist/migrate/sources/launch/zod-to-json-schema.d.ts

@@ -0,0 +1,9 @@
+export type JsonSchema = boolean | JsonSchemaObject;
+export interface JsonSchemaObject {
+    [key: string]: unknown;
+}
+export interface ZodToJsonSchemaResult {
+    schema: JsonSchema;
+    warnings: string[];
+}
+export declare function zodToJsonSchema(source: string): ZodToJsonSchemaResult;