@quonfig/cli 0.0.16 → 0.0.17

package/README.md

@@ -14,7 +14,7 @@ $ npm install -g @quonfig/cli
 $ qfg COMMAND
 running command...
 $ qfg (--version)
-@quonfig/cli/0.0.16 linux-x64 node-v24.4.1
+@quonfig/cli/0.0.17 linux-x64 node-v24.4.1
 $ qfg --help [COMMAND]
 USAGE
   $ qfg COMMAND
@@ -89,7 +89,7 @@ EXAMPLES
   $ qfg config-schema --json-schema    # full JSON Schema document (copy into your editor)
 ```
 
-_See code: [src/commands/config-schema.ts](https://github.com/quonfig/cli/blob/v0.0.16/src/commands/config-schema.ts)_
+_See code: [src/commands/config-schema.ts](https://github.com/quonfig/cli/blob/v0.0.17/src/commands/config-schema.ts)_
 
 ## `qfg create NAME`
 
@@ -161,7 +161,7 @@ EXAMPLES
   $ qfg set-rollout my.new.flag --environment production --true-percent 20
 ```
 
-_See code: [src/commands/create.ts](https://github.com/quonfig/cli/blob/v0.0.16/src/commands/create.ts)_
+_See code: [src/commands/create.ts](https://github.com/quonfig/cli/blob/v0.0.17/src/commands/create.ts)_
 
 ## `qfg flag info [NAME]`
 
@@ -361,7 +361,7 @@ EXAMPLES
   $ qfg generate --targets node-ts -o ./dist # combine with targets
 ```
 
-_See code: [src/commands/generate.ts](https://github.com/quonfig/cli/blob/v0.0.16/src/commands/generate.ts)_
+_See code: [src/commands/generate.ts](https://github.com/quonfig/cli/blob/v0.0.17/src/commands/generate.ts)_
 
 ## `qfg generate-new-hex-key`
 
@@ -384,7 +384,7 @@ EXAMPLES
   $ qfg generate-new-hex-key
 ```
 
-_See code: [src/commands/generate-new-hex-key.ts](https://github.com/quonfig/cli/blob/v0.0.16/src/commands/generate-new-hex-key.ts)_
+_See code: [src/commands/generate-new-hex-key.ts](https://github.com/quonfig/cli/blob/v0.0.17/src/commands/generate-new-hex-key.ts)_
 
 ## `qfg get [NAME]`
 
@@ -416,7 +416,7 @@ EXAMPLES
   $ qfg get my.config.name --environment=production
 ```
 
-_See code: [src/commands/get.ts](https://github.com/quonfig/cli/blob/v0.0.16/src/commands/get.ts)_
+_See code: [src/commands/get.ts](https://github.com/quonfig/cli/blob/v0.0.17/src/commands/get.ts)_
 
 ## `qfg info [NAME]`
 
@@ -464,7 +464,7 @@ EXAMPLES
   $ qfg info my.config.name --exclude-evaluations   # skip 24h stats
 ```
 
-_See code: [src/commands/info.ts](https://github.com/quonfig/cli/blob/v0.0.16/src/commands/info.ts)_
+_See code: [src/commands/info.ts](https://github.com/quonfig/cli/blob/v0.0.17/src/commands/info.ts)_
 
 ## `qfg init [DIRECTORY]`
 
@@ -504,7 +504,7 @@ EXAMPLES
   $ qfg init --dry-run
 ```
 
-_See code: [src/commands/init.ts](https://github.com/quonfig/cli/blob/v0.0.16/src/commands/init.ts)_
+_See code: [src/commands/init.ts](https://github.com/quonfig/cli/blob/v0.0.17/src/commands/init.ts)_
 
 ## `qfg interactive`
 
@@ -534,7 +534,7 @@ EXAMPLES
   $ qfg
 ```
 
-_See code: [src/commands/interactive.ts](https://github.com/quonfig/cli/blob/v0.0.16/src/commands/interactive.ts)_
+_See code: [src/commands/interactive.ts](https://github.com/quonfig/cli/blob/v0.0.17/src/commands/interactive.ts)_
 
 ## `qfg list`
 
@@ -574,7 +574,7 @@ EXAMPLES
   $ qfg list --feature-flags
 ```
 
-_See code: [src/commands/list.ts](https://github.com/quonfig/cli/blob/v0.0.16/src/commands/list.ts)_
+_See code: [src/commands/list.ts](https://github.com/quonfig/cli/blob/v0.0.17/src/commands/list.ts)_
 
 ## `qfg login`
 
@@ -599,7 +599,7 @@ EXAMPLES
   $ qfg login --profile myprofile
 ```
 
-_See code: [src/commands/login.ts](https://github.com/quonfig/cli/blob/v0.0.16/src/commands/login.ts)_
+_See code: [src/commands/login.ts](https://github.com/quonfig/cli/blob/v0.0.17/src/commands/login.ts)_
 
 ## `qfg logout`
 
@@ -622,7 +622,7 @@ EXAMPLES
   $ qfg logout
 ```
 
-_See code: [src/commands/logout.ts](https://github.com/quonfig/cli/blob/v0.0.16/src/commands/logout.ts)_
+_See code: [src/commands/logout.ts](https://github.com/quonfig/cli/blob/v0.0.17/src/commands/logout.ts)_
 
 ## `qfg mcp`
 
@@ -655,7 +655,7 @@ EXAMPLES
   $ qfg mcp --url http://local-app.quonfig-staging.com:3003/api/v1/mcp
 ```
 
-_See code: [src/commands/mcp.ts](https://github.com/quonfig/cli/blob/v0.0.16/src/commands/mcp.ts)_
+_See code: [src/commands/mcp.ts](https://github.com/quonfig/cli/blob/v0.0.17/src/commands/mcp.ts)_
 
 ## `qfg migrate`
 
@@ -709,7 +709,7 @@ EXAMPLES
   $ qfg migrate --from launch --api-key $LAUNCH_API_KEY --dir ./quonfig-config --staging
 ```
 
-_See code: [src/commands/migrate.ts](https://github.com/quonfig/cli/blob/v0.0.16/src/commands/migrate.ts)_
+_See code: [src/commands/migrate.ts](https://github.com/quonfig/cli/blob/v0.0.17/src/commands/migrate.ts)_
 
 ## `qfg migrate doctor`
 
@@ -747,7 +747,7 @@ EXAMPLES
   $ qfg migrate doctor --json
 ```
 
-_See code: [src/commands/migrate/doctor.ts](https://github.com/quonfig/cli/blob/v0.0.16/src/commands/migrate/doctor.ts)_
+_See code: [src/commands/migrate/doctor.ts](https://github.com/quonfig/cli/blob/v0.0.17/src/commands/migrate/doctor.ts)_
 
 ## `qfg migrate my-code`
 
@@ -779,7 +779,7 @@ EXAMPLES
   $ qfg migrate my-code --dry-run
 ```
 
-_See code: [src/commands/migrate/my-code.ts](https://github.com/quonfig/cli/blob/v0.0.16/src/commands/migrate/my-code.ts)_
+_See code: [src/commands/migrate/my-code.ts](https://github.com/quonfig/cli/blob/v0.0.17/src/commands/migrate/my-code.ts)_
 
 ## `qfg migrate status`
 
@@ -810,7 +810,7 @@ EXAMPLES
   $ qfg migrate status --json
 ```
 
-_See code: [src/commands/migrate/status.ts](https://github.com/quonfig/cli/blob/v0.0.16/src/commands/migrate/status.ts)_
+_See code: [src/commands/migrate/status.ts](https://github.com/quonfig/cli/blob/v0.0.17/src/commands/migrate/status.ts)_
 
 ## `qfg override [NAME]`
 
@@ -854,7 +854,7 @@ EXAMPLES
   $ qfg override my.double.config --value=3.14159
 ```
 
-_See code: [src/commands/override.ts](https://github.com/quonfig/cli/blob/v0.0.16/src/commands/override.ts)_
+_See code: [src/commands/override.ts](https://github.com/quonfig/cli/blob/v0.0.17/src/commands/override.ts)_
 
 ## `qfg pull`
 
@@ -898,7 +898,7 @@ EXAMPLES
   $ qfg pull  # uses QUONFIG_DIR env var
 ```
 
-_See code: [src/commands/pull.ts](https://github.com/quonfig/cli/blob/v0.0.16/src/commands/pull.ts)_
+_See code: [src/commands/pull.ts](https://github.com/quonfig/cli/blob/v0.0.17/src/commands/pull.ts)_
 
 ## `qfg push`
 
@@ -946,7 +946,7 @@ EXAMPLES
   $ qfg push --dir ./our-config --yes
 ```
 
-_See code: [src/commands/push.ts](https://github.com/quonfig/cli/blob/v0.0.16/src/commands/push.ts)_
+_See code: [src/commands/push.ts](https://github.com/quonfig/cli/blob/v0.0.17/src/commands/push.ts)_
 
 ## `qfg schema NAME`
 
@@ -984,7 +984,7 @@ EXAMPLES
   $ qfg schema my-schema --set-json-schema=@schemas/my-schema.json --protected
 ```
 
-_See code: [src/commands/schema.ts](https://github.com/quonfig/cli/blob/v0.0.16/src/commands/schema.ts)_
+_See code: [src/commands/schema.ts](https://github.com/quonfig/cli/blob/v0.0.17/src/commands/schema.ts)_
 
 ## `qfg sdk-key`
 
@@ -1011,7 +1011,7 @@ EXAMPLES
   $ qfg sdk-key revoke <key-id>
 ```
 
-_See code: [src/commands/sdk-key.ts](https://github.com/quonfig/cli/blob/v0.0.16/src/commands/sdk-key.ts)_
+_See code: [src/commands/sdk-key.ts](https://github.com/quonfig/cli/blob/v0.0.17/src/commands/sdk-key.ts)_
 
 ## `qfg sdk-key create`
 
@@ -1043,7 +1043,7 @@ EXAMPLES
   $ qfg sdk-key create --environment staging --type browser
 ```
 
-_See code: [src/commands/sdk-key/create.ts](https://github.com/quonfig/cli/blob/v0.0.16/src/commands/sdk-key/create.ts)_
+_See code: [src/commands/sdk-key/create.ts](https://github.com/quonfig/cli/blob/v0.0.17/src/commands/sdk-key/create.ts)_
 
 ## `qfg sdk-key list`
 
@@ -1072,7 +1072,7 @@ EXAMPLES
   $ qfg sdk-key list --environment production
 ```
 
-_See code: [src/commands/sdk-key/list.ts](https://github.com/quonfig/cli/blob/v0.0.16/src/commands/sdk-key/list.ts)_
+_See code: [src/commands/sdk-key/list.ts](https://github.com/quonfig/cli/blob/v0.0.17/src/commands/sdk-key/list.ts)_
 
 ## `qfg sdk-key revoke KEYID`
 
@@ -1099,7 +1099,7 @@ EXAMPLES
   $ qfg sdk-key revoke a1b2c3d4-e5f6-7890-abcd-ef1234567890
 ```
 
-_See code: [src/commands/sdk-key/revoke.ts](https://github.com/quonfig/cli/blob/v0.0.16/src/commands/sdk-key/revoke.ts)_
+_See code: [src/commands/sdk-key/revoke.ts](https://github.com/quonfig/cli/blob/v0.0.17/src/commands/sdk-key/revoke.ts)_
 
 ## `qfg set-default [NAME]`
 
@@ -1170,7 +1170,7 @@ EXAMPLES
   $ qfg pull && qfg config-schema
 ```
 
-_See code: [src/commands/set-default.ts](https://github.com/quonfig/cli/blob/v0.0.16/src/commands/set-default.ts)_
+_See code: [src/commands/set-default.ts](https://github.com/quonfig/cli/blob/v0.0.17/src/commands/set-default.ts)_
 
 ## `qfg set-rollout [NAME]`
 
@@ -1247,7 +1247,7 @@ EXAMPLES
   $ qfg set-rollout my.variant.flag --environment production --weights "a:33,b:33,c:34" --hash-by user.id
 ```
 
-_See code: [src/commands/set-rollout.ts](https://github.com/quonfig/cli/blob/v0.0.16/src/commands/set-rollout.ts)_
+_See code: [src/commands/set-rollout.ts](https://github.com/quonfig/cli/blob/v0.0.17/src/commands/set-rollout.ts)_
 
 ## `qfg sync`
 
@@ -1279,7 +1279,7 @@ EXAMPLES
   $ qfg sync --watch --dir ./our-config --interval 30
 ```
 
-_See code: [src/commands/sync.ts](https://github.com/quonfig/cli/blob/v0.0.16/src/commands/sync.ts)_
+_See code: [src/commands/sync.ts](https://github.com/quonfig/cli/blob/v0.0.17/src/commands/sync.ts)_
 
 ## `qfg toggle [NAME]`
 
@@ -1381,7 +1381,7 @@ EXAMPLES
   $ qfg verify --json
 ```
 
-_See code: [src/commands/verify.ts](https://github.com/quonfig/cli/blob/v0.0.16/src/commands/verify.ts)_
+_See code: [src/commands/verify.ts](https://github.com/quonfig/cli/blob/v0.0.17/src/commands/verify.ts)_
 
 ## `qfg whoami`
 
@@ -1404,7 +1404,7 @@ EXAMPLES
   $ qfg whoami
 ```
 
-_See code: [src/commands/whoami.ts](https://github.com/quonfig/cli/blob/v0.0.16/src/commands/whoami.ts)_
+_See code: [src/commands/whoami.ts](https://github.com/quonfig/cli/blob/v0.0.17/src/commands/whoami.ts)_
 
 ## `qfg workspace`
 
@@ -1427,7 +1427,7 @@ EXAMPLES
   $ qfg workspace
 ```
 
-_See code: [src/commands/workspace.ts](https://github.com/quonfig/cli/blob/v0.0.16/src/commands/workspace.ts)_
+_See code: [src/commands/workspace.ts](https://github.com/quonfig/cli/blob/v0.0.17/src/commands/workspace.ts)_
 
 ## `qfg workspace bootstrap`
 
@@ -1460,7 +1460,7 @@ EXAMPLES
   $ qfg workspace bootstrap --dir ./our-config --skip-validate
 ```
 
-_See code: [src/commands/workspace/bootstrap.ts](https://github.com/quonfig/cli/blob/v0.0.16/src/commands/workspace/bootstrap.ts)_
+_See code: [src/commands/workspace/bootstrap.ts](https://github.com/quonfig/cli/blob/v0.0.17/src/commands/workspace/bootstrap.ts)_
 
 ## `qfg workspace switch [SLUG]`
 
@@ -1488,7 +1488,7 @@ EXAMPLES
   $ qfg workspace switch my-workspace-slug
 ```
 
-_See code: [src/commands/workspace/switch.ts](https://github.com/quonfig/cli/blob/v0.0.16/src/commands/workspace/switch.ts)_
+_See code: [src/commands/workspace/switch.ts](https://github.com/quonfig/cli/blob/v0.0.17/src/commands/workspace/switch.ts)_
 <!-- commandsstop -->
 
 ## Local Development

package/dist/commands/migrate.js

@@ -7,7 +7,7 @@ import { applyLocalMigration } from '../migrate/local-write.js';
 import { PushConflictError } from '../util/clone-and-stack-push.js';
 import { pushMigrationToCloud } from '../migrate/push-to-cloud.js';
 import { UnknownSourceError, getSource } from '../migrate/registry.js';
-import { NotYetImplementedError } from '../migrate/source.js';
+import { NotYetImplementedError, } from '../migrate/source.js';
 import { applyLaunchBaseUrl } from '../migrate/sources/launch/api.js';
 import { mintGiteaToken } from '../util/gitea-api.js';
 import { displayUrl } from '../util/git-ops.js';
@@ -104,6 +104,7 @@ export default class Migrate extends BaseCommand {
                 return this.err(error.message);
             throw error;
         }
+        let duplicateResolutionsForWarn = null;
         try {
             await source.validateAuth(flags['api-key']);
             const environments = await source.listEnvironments();
@@ -148,12 +149,14 @@ export default class Migrate extends BaseCommand {
                     const result = await pushMigrationToCloud({
                         changes: toProcess,
                         commitMessage: buildCommitMessage(flags.from, toProcess.length),
+                        environments,
                         importState,
                         localDir: dir,
                         remoteUrl: repoUrl,
                         reportData: buildReportData(flags.from, toProcess.length),
                         source,
                     });
+                    duplicateResolutionsForWarn = result.duplicateResolutions;
                     this.log(result.committed
                         ? `Pushed ${toProcess.length} change(s). commit=${result.commitSha?.slice(0, 8) ?? ''} action=${result.action}`
                         : `No net changes produced by this run. Nothing to commit or push.`);
@@ -188,6 +191,7 @@ export default class Migrate extends BaseCommand {
                 reportData: buildReportData(flags.from, toProcess.length),
                 source,
             });
+            duplicateResolutionsForWarn = localResult.duplicateResolutions;
             this.log(localResult.committed
                 ? `Committed ${toProcess.length} change(s). commit=${localResult.commitSha?.slice(0, 8) ?? ''} action=${localResult.action}`
                 : `No net changes produced by this run. Nothing to commit.`);
@@ -203,6 +207,13 @@ export default class Migrate extends BaseCommand {
                 return this.err(error.message);
             throw error;
         }
+        finally {
+            // Surface source-level warnings even if apply/push threw (e.g.
+            // detectDuplicateKeys). The source accumulator holds the data regardless.
+            warnAboutDroppedOverrides(this, source.getDroppedOverrides?.() ?? null);
+            warnAboutSkippedConfigs(this, source.getSkippedConfigs?.() ?? null);
+            warnAboutDuplicateResolutions(this, duplicateResolutionsForWarn);
+        }
     }
     async resolvePushWorkspace(slugOrId) {
         const authConfig = await loadAuthConfig();
@@ -250,6 +261,41 @@ function buildReportData(source, count) {
         unsupportedFeatures: [],
     };
 }
+function warnAboutDroppedOverrides(cmd, dropped) {
+    if (!dropped || dropped.total === 0)
+        return;
+    const envIds = Object.keys(dropped.byEnv).sort();
+    cmd.warn(`Dropped ${dropped.total} override section(s) referencing ${envIds.length} env ID(s) not present in the source's env list (likely archived/deleted):`);
+    for (const envId of envIds) {
+        const perFlag = dropped.byEnv[envId];
+        const totalForEnv = Object.values(perFlag).reduce((s, n) => s + n, 0);
+        cmd.warn(`  env-${envId}: ${totalForEnv} dropped from ${Object.keys(perFlag).length} flag(s)`);
+        for (const flagPath of Object.keys(perFlag).sort()) {
+            cmd.warn(`    - ${flagPath} (${perFlag[flagPath]})`);
+        }
+    }
+    cmd.warn(`If any of these envs are still in use, restore them in the source system and re-run the migration. Full detail is also written to MIGRATION_REPORT.md.`);
+}
+function warnAboutDuplicateResolutions(cmd, resolved) {
+    if (!resolved || resolved.total === 0)
+        return;
+    cmd.warn(`Resolved ${resolved.total} cross-type key collision(s) in the source data by keeping the config side and deleting 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) {
+        cmd.warn(`  ${entry.key} (${entry.collisionTypes.join(', ')}): kept ${entry.kept}, deleted ${entry.deleted.join(', ')}`);
+    }
+    cmd.warn('Full detail is also written to MIGRATION_REPORT.md.');
+}
+function warnAboutSkippedConfigs(cmd, skipped) {
+    if (!skipped || skipped.total === 0)
+        return;
+    cmd.warn(`Skipped ${skipped.total} invalid config(s) from the source system — these were not written to the workspace. 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) {
+        cmd.warn(`  ${entry.key}: ${entry.reason}`);
+    }
+    cmd.warn('Full detail is also written to MIGRATION_REPORT.md.');
+}
 function resolveTargetDir(dirFlag, cwd) {
     if (dirFlag)
         return path.resolve(cwd, dirFlag);

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

@@ -1,7 +1,7 @@
 import { type ImportState } from './import-state.js';
 import { type MigrationReportData } from './migration-report.js';
 import { type PushIdentity } from '../util/clone-and-stack-push.js';
-import type { LegacyChange, MigrationSource } from './source.js';
+import type { DroppedOverrideSummary, DuplicateResolutionSummary, LegacyChange, MigrationSource, SkippedConfigSummary } from './source.js';
 export interface ApplyLocalMigrationOptions {
     /** Commit author. Defaults to the migrator identity. */
     author?: PushIdentity;
@@ -22,5 +22,11 @@ export interface ApplyLocalMigrationResult {
     commitSha: string | null;
     /** `false` if translate produced no net changes — nothing was committed. */
     committed: boolean;
+    /** Override sections dropped during translate because env.id was unknown. Null if none. */
+    droppedOverrides: DroppedOverrideSummary | null;
+    /** Cross-type key collisions resolved by preferring the config side. Null if none. */
+    duplicateResolutions: DuplicateResolutionSummary | null;
+    /** Configs soft-skipped during translate due to invalid source data. Null if none. */
+    skippedConfigs: SkippedConfigSummary | null;
 }
 export declare const applyLocalMigration: (opts: ApplyLocalMigrationOptions) => Promise<ApplyLocalMigrationResult>;

package/dist/migrate/local-write.js

@@ -4,6 +4,7 @@ import * as path from 'node:path';
 import * as util from 'node:util';
 import { removeQfFromGitignore, writeImportState } from './import-state.js';
 import { writeMigrationReport } from './migration-report.js';
+import { detectDuplicateKeys } from './sources/launch/translate.js';
 import { MIGRATOR_IDENTITY } from '../util/clone-and-stack-push.js';
 const execFile = util.promisify(execFileCb);
 const isGitRepo = async (dir) => {
@@ -49,14 +50,45 @@ const ensureLocalRepo = async (localDir, branch) => {
     return 'initialized';
 };
 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;
 };
 export const applyLocalMigration = async (opts) => {
     const branch = opts.branch ?? 'main';
@@ -65,13 +97,22 @@ export const applyLocalMigration = async (opts) => {
     await execFile('git', ['-C', opts.localDir, 'config', 'user.name', author.name]);
     await execFile('git', ['-C', opts.localDir, 'config', 'user.email', author.email]);
     ensureQuonfigJson(opts.localDir, opts.environments);
-    writeQuonfigFiles(opts.localDir, opts.changes, opts.source);
+    const resolutionEntries = writeQuonfigFiles(opts.localDir, opts.changes, opts.source);
     removeQfFromGitignore(opts.localDir);
     writeImportState(opts.localDir, opts.importState);
-    writeMigrationReport(opts.localDir, opts.reportData);
+    const droppedOverrides = opts.source.getDroppedOverrides?.() ?? null;
+    const skippedConfigs = opts.source.getSkippedConfigs?.() ?? null;
+    const duplicateResolutions = resolutionEntries.length > 0 ? { entries: resolutionEntries, total: resolutionEntries.length } : null;
+    const reportData = {
+        ...opts.reportData,
+        ...(droppedOverrides ? { droppedOverrides } : {}),
+        ...(duplicateResolutions ? { duplicateResolutions } : {}),
+        ...(skippedConfigs ? { skippedConfigs } : {}),
+    };
+    writeMigrationReport(opts.localDir, reportData);
     await execFile('git', ['-C', opts.localDir, 'add', '--all']);
     if (!(await hasStagedChanges(opts.localDir))) {
-        return { action, committed: false, commitSha: null };
+        return { action, committed: false, commitSha: null, droppedOverrides, duplicateResolutions, skippedConfigs };
     }
     await gitCommitFromStdin(opts.localDir, opts.commitMessage, {
         ...process.env,
@@ -81,5 +122,12 @@ export const applyLocalMigration = async (opts) => {
         GIT_COMMITTER_NAME: author.name,
     });
     const { stdout: sha } = await execFile('git', ['-C', opts.localDir, 'rev-parse', 'HEAD']);
-    return { action, commitSha: sha.trim(), committed: true };
+    return {
+        action,
+        commitSha: sha.trim(),
+        committed: true,
+        droppedOverrides,
+        duplicateResolutions,
+        skippedConfigs,
+    };
 };

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 '../util/clone-and-stack-push.js';
-import type { LegacyChange, MigrationSource } from './source.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>;