@quonfig/cli 0.0.66 → 0.0.67

package/README.md

@@ -17,7 +17,7 @@ $ npm install -g @quonfig/cli
 $ qfg COMMAND
 running command...
 $ qfg (--version)
-@quonfig/cli/0.0.66 linux-x64 node-v24.4.1
+@quonfig/cli/0.0.67 linux-x64 node-v24.4.1
 $ qfg --help [COMMAND]
 USAGE
   $ qfg COMMAND
@@ -201,7 +201,7 @@ EXAMPLES
   $ qfg activity restore my.flag --yes
 ```
 
-_See code: [src/commands/activity.ts](https://github.com/quonfig/cli/blob/v0.0.66/src/commands/activity.ts)_
+_See code: [src/commands/activity.ts](https://github.com/quonfig/cli/blob/v0.0.67/src/commands/activity.ts)_
 
 ## `qfg activity deleted`
 
@@ -230,7 +230,7 @@ EXAMPLES
   $ qfg activity deleted --json
 ```
 
-_See code: [src/commands/activity/deleted.ts](https://github.com/quonfig/cli/blob/v0.0.66/src/commands/activity/deleted.ts)_
+_See code: [src/commands/activity/deleted.ts](https://github.com/quonfig/cli/blob/v0.0.67/src/commands/activity/deleted.ts)_
 
 ## `qfg activity feed`
 
@@ -265,7 +265,7 @@ EXAMPLES
   $ qfg activity feed --json
 ```
 
-_See code: [src/commands/activity/feed.ts](https://github.com/quonfig/cli/blob/v0.0.66/src/commands/activity/feed.ts)_
+_See code: [src/commands/activity/feed.ts](https://github.com/quonfig/cli/blob/v0.0.67/src/commands/activity/feed.ts)_
 
 ## `qfg activity history [NAME]`
 
@@ -299,7 +299,7 @@ EXAMPLES
   $ qfg activity history request.timeout --json
 ```
 
-_See code: [src/commands/activity/history.ts](https://github.com/quonfig/cli/blob/v0.0.66/src/commands/activity/history.ts)_
+_See code: [src/commands/activity/history.ts](https://github.com/quonfig/cli/blob/v0.0.67/src/commands/activity/history.ts)_
 
 ## `qfg activity restore [NAME]`
 
@@ -338,7 +338,7 @@ EXAMPLES
   $ qfg activity restore request.timeout --type config --yes
 ```
 
-_See code: [src/commands/activity/restore.ts](https://github.com/quonfig/cli/blob/v0.0.66/src/commands/activity/restore.ts)_
+_See code: [src/commands/activity/restore.ts](https://github.com/quonfig/cli/blob/v0.0.67/src/commands/activity/restore.ts)_
 
 ## `qfg audit-log [NAME]`
 
@@ -366,7 +366,7 @@ EXAMPLES
   $ qfg audit-log my.flag
 ```
 
-_See code: [src/commands/audit-log.ts](https://github.com/quonfig/cli/blob/v0.0.66/src/commands/audit-log.ts)_
+_See code: [src/commands/audit-log.ts](https://github.com/quonfig/cli/blob/v0.0.67/src/commands/audit-log.ts)_
 
 ## `qfg cleanup`
 
@@ -407,7 +407,7 @@ EXAMPLES
   $ qfg cleanup status my.flag.key
 ```
 
-_See code: [src/commands/cleanup.ts](https://github.com/quonfig/cli/blob/v0.0.66/src/commands/cleanup.ts)_
+_See code: [src/commands/cleanup.ts](https://github.com/quonfig/cli/blob/v0.0.67/src/commands/cleanup.ts)_
 
 ## `qfg cleanup list`
 
@@ -453,7 +453,7 @@ EXAMPLES
   $ qfg cleanup list --json
 ```
 
-_See code: [src/commands/cleanup/list.ts](https://github.com/quonfig/cli/blob/v0.0.66/src/commands/cleanup/list.ts)_
+_See code: [src/commands/cleanup/list.ts](https://github.com/quonfig/cli/blob/v0.0.67/src/commands/cleanup/list.ts)_
 
 ## `qfg cleanup remove [NAME]`
 
@@ -498,7 +498,7 @@ EXAMPLES
   $ qfg cleanup remove my.flag.key --json
 ```
 
-_See code: [src/commands/cleanup/remove.ts](https://github.com/quonfig/cli/blob/v0.0.66/src/commands/cleanup/remove.ts)_
+_See code: [src/commands/cleanup/remove.ts](https://github.com/quonfig/cli/blob/v0.0.67/src/commands/cleanup/remove.ts)_
 
 ## `qfg cleanup status [NAME]`
 
@@ -538,7 +538,7 @@ EXAMPLES
   $ qfg cleanup status my.flag.key --json
 ```
 
-_See code: [src/commands/cleanup/status.ts](https://github.com/quonfig/cli/blob/v0.0.66/src/commands/cleanup/status.ts)_
+_See code: [src/commands/cleanup/status.ts](https://github.com/quonfig/cli/blob/v0.0.67/src/commands/cleanup/status.ts)_
 
 ## `qfg cleanup verify [NAME]`
 
@@ -584,7 +584,7 @@ EXAMPLES
   $ qfg cleanup verify my.flag.key && qfg delete my.flag.key
 ```
 
-_See code: [src/commands/cleanup/verify.ts](https://github.com/quonfig/cli/blob/v0.0.66/src/commands/cleanup/verify.ts)_
+_See code: [src/commands/cleanup/verify.ts](https://github.com/quonfig/cli/blob/v0.0.67/src/commands/cleanup/verify.ts)_
 
 ## `qfg config-schema`
 
@@ -613,7 +613,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.66/src/commands/config-schema.ts)_
+_See code: [src/commands/config-schema.ts](https://github.com/quonfig/cli/blob/v0.0.67/src/commands/config-schema.ts)_
 
 ## `qfg create NAME`
 
@@ -700,7 +700,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.66/src/commands/create.ts)_
+_See code: [src/commands/create.ts](https://github.com/quonfig/cli/blob/v0.0.67/src/commands/create.ts)_
 
 ## `qfg delete NAME`
 
@@ -746,7 +746,7 @@ EXAMPLES
   $ qfg delete my.config --yes
 ```
 
-_See code: [src/commands/delete.ts](https://github.com/quonfig/cli/blob/v0.0.66/src/commands/delete.ts)_
+_See code: [src/commands/delete.ts](https://github.com/quonfig/cli/blob/v0.0.67/src/commands/delete.ts)_
 
 ## `qfg flag info [NAME]`
 
@@ -950,7 +950,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.66/src/commands/generate.ts)_
+_See code: [src/commands/generate.ts](https://github.com/quonfig/cli/blob/v0.0.67/src/commands/generate.ts)_
 
 ## `qfg generate-new-hex-key`
 
@@ -973,7 +973,7 @@ EXAMPLES
   $ qfg generate-new-hex-key
 ```
 
-_See code: [src/commands/generate-new-hex-key.ts](https://github.com/quonfig/cli/blob/v0.0.66/src/commands/generate-new-hex-key.ts)_
+_See code: [src/commands/generate-new-hex-key.ts](https://github.com/quonfig/cli/blob/v0.0.67/src/commands/generate-new-hex-key.ts)_
 
 ## `qfg get [NAME]`
 
@@ -1005,7 +1005,7 @@ EXAMPLES
   $ qfg get my.config.name --environment=production
 ```
 
-_See code: [src/commands/get.ts](https://github.com/quonfig/cli/blob/v0.0.66/src/commands/get.ts)_
+_See code: [src/commands/get.ts](https://github.com/quonfig/cli/blob/v0.0.67/src/commands/get.ts)_
 
 ## `qfg history NAME`
 
@@ -1031,7 +1031,7 @@ EXAMPLES
   $ qfg history my.flag
 ```
 
-_See code: [src/commands/history.ts](https://github.com/quonfig/cli/blob/v0.0.66/src/commands/history.ts)_
+_See code: [src/commands/history.ts](https://github.com/quonfig/cli/blob/v0.0.67/src/commands/history.ts)_
 
 ## `qfg info [NAME]`
 
@@ -1079,7 +1079,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.66/src/commands/info.ts)_
+_See code: [src/commands/info.ts](https://github.com/quonfig/cli/blob/v0.0.67/src/commands/info.ts)_
 
 ## `qfg init [DIRECTORY]`
 
@@ -1119,7 +1119,7 @@ EXAMPLES
   $ qfg init --dry-run
 ```
 
-_See code: [src/commands/init.ts](https://github.com/quonfig/cli/blob/v0.0.66/src/commands/init.ts)_
+_See code: [src/commands/init.ts](https://github.com/quonfig/cli/blob/v0.0.67/src/commands/init.ts)_
 
 ## `qfg interactive`
 
@@ -1149,7 +1149,7 @@ EXAMPLES
   $ qfg
 ```
 
-_See code: [src/commands/interactive.ts](https://github.com/quonfig/cli/blob/v0.0.66/src/commands/interactive.ts)_
+_See code: [src/commands/interactive.ts](https://github.com/quonfig/cli/blob/v0.0.67/src/commands/interactive.ts)_
 
 ## `qfg list`
 
@@ -1189,7 +1189,7 @@ EXAMPLES
   $ qfg list --feature-flags
 ```
 
-_See code: [src/commands/list.ts](https://github.com/quonfig/cli/blob/v0.0.66/src/commands/list.ts)_
+_See code: [src/commands/list.ts](https://github.com/quonfig/cli/blob/v0.0.67/src/commands/list.ts)_
 
 ## `qfg log`
 
@@ -1214,7 +1214,7 @@ EXAMPLES
   $ qfg log --limit 5
 ```
 
-_See code: [src/commands/log.ts](https://github.com/quonfig/cli/blob/v0.0.66/src/commands/log.ts)_
+_See code: [src/commands/log.ts](https://github.com/quonfig/cli/blob/v0.0.67/src/commands/log.ts)_
 
 ## `qfg log-level NAME`
 
@@ -1279,7 +1279,7 @@ EXAMPLES
   $ qfg log-level log-level.my-app --target=Chatty --value=INFO --environment=production
 ```
 
-_See code: [src/commands/log-level.ts](https://github.com/quonfig/cli/blob/v0.0.66/src/commands/log-level.ts)_
+_See code: [src/commands/log-level.ts](https://github.com/quonfig/cli/blob/v0.0.67/src/commands/log-level.ts)_
 
 ## `qfg login`
 
@@ -1304,7 +1304,7 @@ EXAMPLES
   $ qfg login --profile myprofile
 ```
 
-_See code: [src/commands/login.ts](https://github.com/quonfig/cli/blob/v0.0.66/src/commands/login.ts)_
+_See code: [src/commands/login.ts](https://github.com/quonfig/cli/blob/v0.0.67/src/commands/login.ts)_
 
 ## `qfg logout`
 
@@ -1327,7 +1327,7 @@ EXAMPLES
   $ qfg logout
 ```
 
-_See code: [src/commands/logout.ts](https://github.com/quonfig/cli/blob/v0.0.66/src/commands/logout.ts)_
+_See code: [src/commands/logout.ts](https://github.com/quonfig/cli/blob/v0.0.67/src/commands/logout.ts)_
 
 ## `qfg migrate`
 
@@ -1392,7 +1392,7 @@ EXAMPLES
   $ qfg migrate --from launch --source-api-key $LAUNCH_API_KEY --dir ./quonfig-repo --staging
 ```
 
-_See code: [src/commands/migrate.ts](https://github.com/quonfig/cli/blob/v0.0.66/src/commands/migrate.ts)_
+_See code: [src/commands/migrate.ts](https://github.com/quonfig/cli/blob/v0.0.67/src/commands/migrate.ts)_
 
 ## `qfg migrate doctor`
 
@@ -1430,7 +1430,7 @@ EXAMPLES
   $ qfg migrate doctor --json
 ```
 
-_See code: [src/commands/migrate/doctor.ts](https://github.com/quonfig/cli/blob/v0.0.66/src/commands/migrate/doctor.ts)_
+_See code: [src/commands/migrate/doctor.ts](https://github.com/quonfig/cli/blob/v0.0.67/src/commands/migrate/doctor.ts)_
 
 ## `qfg migrate my-code`
 
@@ -1462,7 +1462,7 @@ EXAMPLES
   $ qfg migrate my-code --dry-run
 ```
 
-_See code: [src/commands/migrate/my-code.ts](https://github.com/quonfig/cli/blob/v0.0.66/src/commands/migrate/my-code.ts)_
+_See code: [src/commands/migrate/my-code.ts](https://github.com/quonfig/cli/blob/v0.0.67/src/commands/migrate/my-code.ts)_
 
 ## `qfg migrate status`
 
@@ -1493,7 +1493,7 @@ EXAMPLES
   $ qfg migrate status --json
 ```
 
-_See code: [src/commands/migrate/status.ts](https://github.com/quonfig/cli/blob/v0.0.66/src/commands/migrate/status.ts)_
+_See code: [src/commands/migrate/status.ts](https://github.com/quonfig/cli/blob/v0.0.67/src/commands/migrate/status.ts)_
 
 ## `qfg override [NAME] [VALUE]`
 
@@ -1548,7 +1548,7 @@ EXAMPLES
   $ qfg override my.flag true --env=staging
 ```
 
-_See code: [src/commands/override.ts](https://github.com/quonfig/cli/blob/v0.0.66/src/commands/override.ts)_
+_See code: [src/commands/override.ts](https://github.com/quonfig/cli/blob/v0.0.67/src/commands/override.ts)_
 
 ## `qfg pull`
 
@@ -1596,7 +1596,7 @@ EXAMPLES
   $ qfg pull  # uses QUONFIG_DIR env var
 ```
 
-_See code: [src/commands/pull.ts](https://github.com/quonfig/cli/blob/v0.0.66/src/commands/pull.ts)_
+_See code: [src/commands/pull.ts](https://github.com/quonfig/cli/blob/v0.0.67/src/commands/pull.ts)_
 
 ## `qfg push`
 
@@ -1645,7 +1645,7 @@ EXAMPLES
   $ qfg push --dir ./our-config --yes
 ```
 
-_See code: [src/commands/push.ts](https://github.com/quonfig/cli/blob/v0.0.66/src/commands/push.ts)_
+_See code: [src/commands/push.ts](https://github.com/quonfig/cli/blob/v0.0.67/src/commands/push.ts)_
 
 ## `qfg run [COMMAND]`
 
@@ -1696,7 +1696,7 @@ EXAMPLES
   $ qfg run --env DATABASE_URL=db.url --preserve-env --environment=staging -- npm test
 ```
 
-_See code: [src/commands/run.ts](https://github.com/quonfig/cli/blob/v0.0.66/src/commands/run.ts)_
+_See code: [src/commands/run.ts](https://github.com/quonfig/cli/blob/v0.0.67/src/commands/run.ts)_
 
 ## `qfg schema NAME`
 
@@ -1734,7 +1734,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.66/src/commands/schema.ts)_
+_See code: [src/commands/schema.ts](https://github.com/quonfig/cli/blob/v0.0.67/src/commands/schema.ts)_
 
 ## `qfg sdk-key`
 
@@ -1761,7 +1761,7 @@ EXAMPLES
   $ qfg sdk-key revoke <key-id>
 ```
 
-_See code: [src/commands/sdk-key.ts](https://github.com/quonfig/cli/blob/v0.0.66/src/commands/sdk-key.ts)_
+_See code: [src/commands/sdk-key.ts](https://github.com/quonfig/cli/blob/v0.0.67/src/commands/sdk-key.ts)_
 
 ## `qfg sdk-key create`
 
@@ -1793,7 +1793,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.66/src/commands/sdk-key/create.ts)_
+_See code: [src/commands/sdk-key/create.ts](https://github.com/quonfig/cli/blob/v0.0.67/src/commands/sdk-key/create.ts)_
 
 ## `qfg sdk-key list`
 
@@ -1822,7 +1822,7 @@ EXAMPLES
   $ qfg sdk-key list --environment production
 ```
 
-_See code: [src/commands/sdk-key/list.ts](https://github.com/quonfig/cli/blob/v0.0.66/src/commands/sdk-key/list.ts)_
+_See code: [src/commands/sdk-key/list.ts](https://github.com/quonfig/cli/blob/v0.0.67/src/commands/sdk-key/list.ts)_
 
 ## `qfg sdk-key revoke KEYID`
 
@@ -1849,7 +1849,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.66/src/commands/sdk-key/revoke.ts)_
+_See code: [src/commands/sdk-key/revoke.ts](https://github.com/quonfig/cli/blob/v0.0.67/src/commands/sdk-key/revoke.ts)_
 
 ## `qfg serve`
 
@@ -1906,7 +1906,7 @@ EXAMPLES
   $ qfg serve --port 6581 --frontend-sdk-key PUBLIC_KEY
 ```
 
-_See code: [src/commands/serve.ts](https://github.com/quonfig/cli/blob/v0.0.66/src/commands/serve.ts)_
+_See code: [src/commands/serve.ts](https://github.com/quonfig/cli/blob/v0.0.67/src/commands/serve.ts)_
 
 ## `qfg set-default [NAME]`
 
@@ -1977,7 +1977,7 @@ EXAMPLES
   $ qfg pull && qfg config-schema
 ```
 
-_See code: [src/commands/set-default.ts](https://github.com/quonfig/cli/blob/v0.0.66/src/commands/set-default.ts)_
+_See code: [src/commands/set-default.ts](https://github.com/quonfig/cli/blob/v0.0.67/src/commands/set-default.ts)_
 
 ## `qfg set-rollout [NAME]`
 
@@ -2054,7 +2054,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.66/src/commands/set-rollout.ts)_
+_See code: [src/commands/set-rollout.ts](https://github.com/quonfig/cli/blob/v0.0.67/src/commands/set-rollout.ts)_
 
 ## `qfg sync`
 
@@ -2086,7 +2086,7 @@ EXAMPLES
   $ qfg sync --watch --dir ./our-config --interval 30
 ```
 
-_See code: [src/commands/sync.ts](https://github.com/quonfig/cli/blob/v0.0.66/src/commands/sync.ts)_
+_See code: [src/commands/sync.ts](https://github.com/quonfig/cli/blob/v0.0.67/src/commands/sync.ts)_
 
 ## `qfg toggle [NAME]`
 
@@ -2188,7 +2188,7 @@ EXAMPLES
   $ qfg verify --json
 ```
 
-_See code: [src/commands/verify.ts](https://github.com/quonfig/cli/blob/v0.0.66/src/commands/verify.ts)_
+_See code: [src/commands/verify.ts](https://github.com/quonfig/cli/blob/v0.0.67/src/commands/verify.ts)_
 
 ## `qfg whoami`
 
@@ -2211,7 +2211,7 @@ EXAMPLES
   $ qfg whoami
 ```
 
-_See code: [src/commands/whoami.ts](https://github.com/quonfig/cli/blob/v0.0.66/src/commands/whoami.ts)_
+_See code: [src/commands/whoami.ts](https://github.com/quonfig/cli/blob/v0.0.67/src/commands/whoami.ts)_
 
 ## `qfg workspace`
 
@@ -2234,7 +2234,7 @@ EXAMPLES
   $ qfg workspace
 ```
 
-_See code: [src/commands/workspace.ts](https://github.com/quonfig/cli/blob/v0.0.66/src/commands/workspace.ts)_
+_See code: [src/commands/workspace.ts](https://github.com/quonfig/cli/blob/v0.0.67/src/commands/workspace.ts)_
 
 ## `qfg workspace bootstrap`
 
@@ -2267,7 +2267,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.66/src/commands/workspace/bootstrap.ts)_
+_See code: [src/commands/workspace/bootstrap.ts](https://github.com/quonfig/cli/blob/v0.0.67/src/commands/workspace/bootstrap.ts)_
 
 ## `qfg workspace create SLUG`
 
@@ -2301,7 +2301,7 @@ EXAMPLES
   $ qfg workspace create my-team --org 11111111-1111-1111-1111-111111111111
 ```
 
-_See code: [src/commands/workspace/create.ts](https://github.com/quonfig/cli/blob/v0.0.66/src/commands/workspace/create.ts)_
+_See code: [src/commands/workspace/create.ts](https://github.com/quonfig/cli/blob/v0.0.67/src/commands/workspace/create.ts)_
 
 ## `qfg workspace switch [SLUG]`
 
@@ -2329,7 +2329,7 @@ EXAMPLES
   $ qfg workspace switch acme/production
 ```
 
-_See code: [src/commands/workspace/switch.ts](https://github.com/quonfig/cli/blob/v0.0.66/src/commands/workspace/switch.ts)_
+_See code: [src/commands/workspace/switch.ts](https://github.com/quonfig/cli/blob/v0.0.67/src/commands/workspace/switch.ts)_
 <!-- commandsstop -->
 
 ## Local Development

package/dist/migrate/import-state.d.ts

@@ -10,5 +10,8 @@ export declare class CrossSourceError extends Error {
 }
 export declare function writeImportState(outputDir: string, state: ImportState): void;
 export declare function readImportState(outputDir: string): ImportState | null;
+export declare function writeKeyPlan(outputDir: string, keys: Record<string, string>): void;
+/** The persisted plan, or null when absent/unreadable (treat as first run). */
+export declare function readKeyPlan(outputDir: string): null | Record<string, string>;
 export declare function assertSourceMatches(outputDir: string, requestedSource: string): void;
 export declare function removeQfFromGitignore(outputDir: string): void;

package/dist/migrate/import-state.js

@@ -35,6 +35,38 @@ export function readImportState(outputDir) {
         return null;
     return parsed;
 }
+function keyPlanPath(outputDir) {
+    return path.join(outputDir, '.qf', 'key-plan.json');
+}
+export function writeKeyPlan(outputDir, keys) {
+    const filePath = keyPlanPath(outputDir);
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    const sorted = {};
+    for (const source of Object.keys(keys).sort())
+        sorted[source] = keys[source];
+    const serialized = { keys: sorted, version: 1 };
+    fs.writeFileSync(filePath, JSON.stringify(serialized, null, 2) + '\n', 'utf8');
+}
+/** The persisted plan, or null when absent/unreadable (treat as first run). */
+export function readKeyPlan(outputDir) {
+    const filePath = keyPlanPath(outputDir);
+    if (!fs.existsSync(filePath))
+        return null;
+    try {
+        const parsed = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+        if (typeof parsed?.keys !== 'object' || parsed.keys === null || Array.isArray(parsed.keys))
+            return null;
+        const out = {};
+        for (const [source, final] of Object.entries(parsed.keys)) {
+            if (typeof final === 'string')
+                out[source] = final;
+        }
+        return out;
+    }
+    catch {
+        return null;
+    }
+}
 export function assertSourceMatches(outputDir, requestedSource) {
     const state = readImportState(outputDir);
     if (!state)

package/dist/migrate/key-rewriter.d.ts

@@ -8,27 +8,57 @@ export interface KeyRewrite {
 }
 export declare function resetKeyRewriter(): void;
 /**
- * Pre-pass: compute the final key for every source key. Sorted first so the
- * assignment of the un-suffixed base name on a collision is deterministic and
- * independent of the order changes were fetched in.
+ * Seed the rewriter with the complete source->final map persisted by previous
+ * runs. Every persisted final is immediately marked taken (case-insensitively)
+ * so keys planned later this run can never claim one. Call after
+ * `resetKeyRewriter()` and before `planKeyRewrites()` — `planKeyRewritesForChanges`
+ * does this ordering for you.
+ */
+export declare function seedPersistedKeyPlan(keys: Readonly<Record<string, string>>): void;
+/**
+ * Pre-pass: compute the final key for every source key. Three passes, each
+ * sorted so every assignment is deterministic and independent of the order
+ * changes were fetched in:
+ *
+ *   0. Keys mapped by a PREVIOUS run keep their persisted final verbatim (see
+ *      `seedPersistedKeyPlan`) — full and delta runs must resolve identically.
+ *   1. Keys that are ALREADY fully valid (sanitize is an identity: they pass
+ *      Policy A and the FS-floor) claim their own names FIRST and are never
+ *      renamed to make room for sanitized junk — customer code calling
+ *      get("my-flag") must keep resolving to the same flag even when a source
+ *      key like "my flag" sanitizes to the same name. If two VALID keys
+ *      collide case-insensitively ("Foo"/"foo" — a genuine source conflict the
+ *      FS-floor hard-rejects), the lexicographically-first one keeps its name
+ *      and the other is suffixed.
+ *   2. Keys that needed sanitizing then disambiguate AROUND the valid ones
+ *      (-2, -3, ...).
  */
 export declare function planKeyRewrites(sourceKeys: Iterable<string>): void;
 /**
- * The final key for `sourceKey`. Uses the planned map when present, else a pure
+ * The final key for `sourceKey`. Uses the planned map when present, then the
+ * PERSISTED map (a delta run's flag can reference a segment that was migrated
+ * in the full run but is absent from the delta's change set), else a pure
  * sanitize (no disambiguation, no mutation) as a safe fallback.
  */
 export declare function resolveKey(sourceKey: string): string;
 /** Every key that was actually rewritten (conforming keys are omitted). */
 export declare function getKeyRewrites(): KeyRewrite[];
 /**
- * Run-level pre-pass: reset the rewriter and plan every source key BEFORE any
- * change is translated, so both key-definition and by-key reference sites
- * resolve against the same fully-disambiguated map. Structurally typed on
- * `{key?}` to stay decoupled from LegacyChange.
+ * The COMPLETE source->final map to persist to `.qf/key-plan.json`: every key
+ * planned this run (unchanged ones included) merged over everything persisted
+ * by previous runs, sorted by source key for stable on-disk diffs.
+ */
+export declare function getFullKeyPlan(): Record<string, string>;
+/**
+ * Run-level pre-pass: reset the rewriter, seed the persisted plan from any
+ * previous run, and plan every source key BEFORE any change is translated, so
+ * both key-definition and by-key reference sites resolve against the same
+ * fully-disambiguated map. Structurally typed on `{key?}` to stay decoupled
+ * from LegacyChange.
  */
 export declare function planKeyRewritesForChanges(changes: ReadonlyArray<{
     key?: string;
-}>): void;
+}>, persistedKeys?: Readonly<Record<string, string>>): void;
 /**
  * `--strict-keys` escape hatch: refuse to migrate if any source key would need
  * rewriting, so a customer who requires byte-identical keys can clean up the
@@ -41,10 +71,12 @@ export declare class StrictKeysError extends Error {
 /**
  * Plan the rewrites for a run and, when `strict`, throw `StrictKeysError` if any
  * key would be rewritten. Call once at the top of each migrate orchestrator
- * before translating.
+ * before translating. `persistedKeys` (from `readKeyPlan`) makes previously
+ * mapped keys resolve exactly as they did on the run that mapped them.
  */
 export declare function preflightKeyRewrites(changes: ReadonlyArray<{
     key?: string;
 }>, opts?: {
+    persistedKeys?: Readonly<Record<string, string>>;
     strict?: boolean;
 }): void;