@edgekits/i18n-core 0.2.1 → 0.3.0

package/dist/cli/index.js

@@ -1,46 +1,85 @@
 #!/usr/bin/env node
 import { execFileSync } from 'node:child_process';
 import fs from 'node:fs';
+import os from 'node:os';
 import path from 'node:path';
 import { DEFAULT_GENERATED_DIR, DEFAULT_LOCALES_DIR } from "../types.js";
-import { assertValidNames, buildBulkData, buildFallbacksContent, buildRuntimeConstantsContent, buildTypesContent, localesWithTranslations, schemaSourceLocale, } from "./generate.js";
-import { diffHashes, purgeUrlsFor } from "./hashes.js";
+import { collectTranslations } from "./collect.js";
+import { parseDevVars } from "./dev-vars.js";
+import { assertNoNullValues, assertValidNames, buildBulkData, buildFallbacksContent, buildRuntimeConstantsContent, buildTypesContent, localesWithTranslations, schemaSourceLocale, translationWarnings, } from "./generate.js";
+import { diffHashes, kvKeysFor, purgeUrlsFor, readBaseline, removedKeys, stableStringify, writeBaseline, } from "./hashes.js";
 import { CONFIG_FILE, loadI18nConfig } from "./load-config.js";
 import { purgeTranslationsCache } from "./purge.js";
-import { getKvNamespaceId, getWranglerVar, KV_BINDING, resolveWranglerBin } from "./wrangler.js";
+import { KV_BINDING, readWorkerSettings, resolveWranglerBin } from "./wrangler.js";
 import { checkKeyPrefixZone } from "./zone.js";
+// KV can take up to 60 s to show a write in other locations; the second purge comes after.
+const DEFAULT_PURGE_DELAY_S = 65;
+// Ten minutes: far past KV's settling time, and well inside setTimeout's range.
+const MAX_PURGE_DELAY_S = 600;
 const HELP = `Usage: edgekits-i18n <command> [--fallbacks] [--config <path>] [--wrangler <path>]
+                     [--env <name>] [--purge-delay <seconds>] [--purge-all]
 
 Reads ${CONFIG_FILE} and <localesDir>/<locale>/<namespace>.json from the config's directory.
 
 Commands:
   bundle    Write i18n-data.json, src/i18n.generated.d.ts and <generatedDir>/runtime-constants.ts.
             No side effects. --fallbacks also writes <generatedDir>/fallbacks.generated.ts.
-  seed      bundle + fallbacks, then push to LOCAL KV (wrangler --local).
-            .i18n-hashes.json is left untouched: it records production, not local KV.
-  migrate   bundle + fallbacks, then push to production KV, purge the changed edge-cache
-            entries, and write .i18n-hashes.json. Refuses to run while .i18n-hashes.json
-            has uncommitted changes.
+  seed      bundle + fallbacks, then push to LOCAL KV (wrangler --local): the TRANSLATIONS
+            preview_id when set (what wrangler dev reads), else its id.
+            .i18n-hashes.json is left untouched: it records remote KV, not local.
+  migrate   bundle + fallbacks, then push to remote KV, delete the keys of removed translation
+            files, purge the changed edge-cache entries, wait --purge-delay seconds, purge them
+            again, and write .i18n-hashes.json. Refuses to run while the baseline of the KV
+            namespace it writes differs from the one committed in .i18n-hashes.json.
 
 Options:
-  --config <path>    The ${CONFIG_FILE} to load (default: ./${CONFIG_FILE}). Its directory is the
-                     project root: locales, generated files and .i18n-hashes.json live there.
-  --wrangler <path>  The Worker's wrangler config (default: ./wrangler.jsonc): the TRANSLATIONS id and
-                     CLOUDFLARE_ZONE_ID; .dev.vars and the wrangler binary come from its directory.
+  --config <path>          The config to load (default: ./${CONFIG_FILE}). Its directory
+                           is the project root: locales, generated files and .i18n-hashes.json live there.
+  --wrangler <path>        The Worker's wrangler config (default: ./wrangler.jsonc): the TRANSLATIONS
+                           binding and CLOUDFLARE_ZONE_ID; .dev.vars and the wrangler binary come from
+                           its directory.
+  --env <name>             Read the TRANSLATIONS binding and CLOUDFLARE_ZONE_ID from env.<name> of the
+                           wrangler config (wrangler does not inherit them), pass --env to wrangler, and
+                           read .dev.vars.<name> instead of .dev.vars when it exists (as wrangler does).
+  --purge-delay <seconds>  migrate: the wait between the two purges (default ${DEFAULT_PURGE_DELAY_S}, at most ${MAX_PURGE_DELAY_S}). KV can
+                           take up to 60 s to show a write in other locations, and a read there in that window
+                           re-caches the old value. 0 purges once.
+  --purge-all              migrate: purge every namespace's cache URLs, changed or not. For after a
+                           git revert of translations, which reverts .i18n-hashes.json with them.
+
+Exit status: 0 on success, 1 on an error. migrate also exits 1 when KV was updated but the edge
+cache was not purged (no CLOUDFLARE_ZONE_ID or token, a failed purge); .i18n-hashes.json is then
+not written, so the next migrate retries.
 
 Monorepo: keep the config, locales and generated files in one package and pass any one app's
 Worker config (every app binds the same KV namespace and zone), from the repository root:
   edgekits-i18n migrate --config packages/i18n/${CONFIG_FILE} --wrangler apps/app/wrangler.jsonc
 `;
 const COMMANDS = ['bundle', 'seed', 'migrate'];
-// The flags that take a path; each is removed from argv, with its value, before the
+// The flags that take no value. Anything else that is neither the command nor a value flag
+// stops the run: a mistyped flag (`-e staging`) must not run migrate against the default
+// environment.
+const BOOLEAN_FLAGS = ['--fallbacks', '--purge-all', '--help', '-h'];
+// The flags that take a value; each is removed from argv, with its value, before the
 // command is looked for.
-const PATH_FLAGS = ['--config', '--wrangler'];
+const VALUE_FLAGS = {
+    '--config': 'a path',
+    '--wrangler': 'a path',
+    '--env': 'an environment name',
+    '--purge-delay': 'a number of seconds',
+};
 const WRANGLER_FILE = 'wrangler.jsonc';
 const KV_NAMESPACE_ID = /^[0-9a-f]{32}$/i;
+// A zone id reaches the Purge API's URL path next to the token: only a real id's shape.
+const ZONE_ID = /^[0-9a-f]{32}$/i;
+// An environment name reaches wrangler's argv: only the characters wrangler's own names use.
+const ENV_NAME = /^[A-Za-z0-9_-]+$/;
+// How migrate ends when KV was written but the edge cache was not purged.
+const CACHE_NOT_PURGED = 'KV is updated; the edge cache is not. .i18n-hashes.json was NOT written, so the next ' +
+    '`edgekits-i18n migrate` retries the same purge.';
 await main(process.argv.slice(2));
 async function main(argv) {
-    const { args, flags } = extractPathFlags(argv);
+    const { args, flags } = extractValueFlags(argv);
     const command = args.find((arg) => !arg.startsWith('-'));
     if (!command || args.includes('--help') || args.includes('-h')) {
         console.log(HELP);
@@ -51,22 +90,33 @@ async function main(argv) {
         console.error(HELP);
         process.exit(1);
     }
-    await run(command, args, resolvePaths(flags));
+    const unknown = args.find((arg, i) => arg.startsWith('-') ? !BOOLEAN_FLAGS.includes(arg) : i !== args.indexOf(command));
+    if (unknown !== undefined) {
+        console.error(`[i18n] Unknown argument "${unknown}". Run edgekits-i18n --help for the options.`);
+        process.exit(1);
+    }
+    const purgeAll = args.includes('--purge-all');
+    if (purgeAll && command !== 'migrate') {
+        console.error('[i18n] --purge-all applies to migrate only.');
+        process.exit(1);
+    }
+    await run(command, args, resolvePaths(flags), { ...resolveOptions(flags), purgeAll });
 }
-/** Takes `--config <path>` / `--wrangler <path>` (or `--flag=<path>`) out of argv. */
-function extractPathFlags(argv) {
+/** Takes the value flags (`--config <path>`, or `--config=<path>`, …) out of argv. */
+function extractValueFlags(argv) {
     const args = [];
     const flags = {};
+    const names = Object.keys(VALUE_FLAGS);
     for (let i = 0; i < argv.length; i++) {
         const arg = argv[i];
-        const flag = PATH_FLAGS.find((f) => arg === f || arg.startsWith(`${f}=`));
+        const flag = names.find((f) => arg === f || arg.startsWith(`${f}=`));
         if (!flag) {
             args.push(arg);
             continue;
         }
         const value = arg === flag ? argv[++i] : arg.slice(flag.length + 1);
         if (!value || value.startsWith('-')) {
-            console.error(`[i18n] ${flag} needs a path.`);
+            console.error(`[i18n] ${flag} needs ${VALUE_FLAGS[flag]}.`);
             process.exit(1);
         }
         flags[flag] = value;
@@ -95,24 +145,42 @@ function resolvePaths(flags) {
         // Fixed outputs at the project root.
         data: path.join(root, 'i18n-data.json'),
         types: path.join(root, 'src', 'i18n.generated.d.ts'),
-        // Stores per-namespace content hashes from the last production migrate.
-        // Used to detect which namespaces actually changed and need cache purging.
-        // TRACKED in git: the committed copy is the production purge baseline.
-        // Absence means "first run", all namespaces treated as changed.
+        // Per-namespace content hashes from the last migrate, one baseline per KV namespace id.
+        // Used to detect which namespaces changed (or were removed) and need cache purging.
+        // TRACKED in git: the committed copy is the purge baseline.
+        // Absence (or no entry for the id) means "first run", all namespaces treated as changed.
         hashes: path.join(root, '.i18n-hashes.json'),
     };
 }
+function resolveOptions(flags) {
+    const env = flags['--env'];
+    if (env !== undefined && !ENV_NAME.test(env)) {
+        console.error(`[i18n] --env "${env}" is not an environment name (letters, digits, "-" and "_").`);
+        process.exit(1);
+    }
+    const delay = flags['--purge-delay'];
+    const purgeDelay = delay === undefined ? DEFAULT_PURGE_DELAY_S : Number(delay);
+    if (!Number.isFinite(purgeDelay) || purgeDelay < 0 || purgeDelay > MAX_PURGE_DELAY_S) {
+        console.error(`[i18n] --purge-delay "${delay}" is not a number of seconds from 0 to ${MAX_PURGE_DELAY_S}.`);
+        process.exit(1);
+    }
+    return { env, purgeDelay };
+}
 // A path as the user sees it: relative to where the CLI was run, forward slashes.
 function shown(file) {
     return path.relative(process.cwd(), file).split(path.sep).join('/');
 }
-async function run(command, args, paths) {
+function fail(message) {
+    console.error(`[i18n] ${message}`);
+    process.exit(1);
+}
+function errorMessage(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+async function run(command, args, paths, options) {
     const shouldDeploy = command !== 'bundle';
     const isLocal = command === 'seed';
     const shouldGenerateFallbacks = shouldDeploy || args.includes('--fallbacks') || process.env.I18N_GENERATE_FALLBACKS === 'true';
-    if (command === 'migrate') {
-        assertCleanPurgeBaseline(paths);
-    }
     const config = await loadI18nConfig(paths.config);
     const defaultLocale = config.defaultLocale;
     const localesDir = path.join(paths.root, config.localesDir ?? DEFAULT_LOCALES_DIR);
@@ -120,12 +188,34 @@ async function run(command, args, paths) {
     const outputRuntimeConstants = path.join(generatedDir, 'runtime-constants.ts');
     const outputFallbacks = path.join(generatedDir, 'fallbacks.generated.ts');
     // Read before writing anything, so a missing binding fails the run up front.
-    const kvId = shouldDeploy ? getKvNamespaceId(paths.wranglerConfig, KV_BINDING) : undefined;
+    const worker = shouldDeploy ? readWorkerSettings(paths.wranglerConfig, KV_BINDING, options.env) : undefined;
+    // seed writes the namespace `wrangler dev` reads (preview_id when set), migrate the id.
+    const writeKvId = worker && (isLocal ? (worker.previewId ?? worker.kvId) : worker.kvId);
     // The id becomes a command-line argument (deploy()); only a real namespace id's shape
     // may get there.
-    if (kvId !== undefined && !KV_NAMESPACE_ID.test(kvId)) {
-        console.error(`[i18n] The ${KV_BINDING} id in ${shown(paths.wranglerConfig)}, "${kvId}", is not a KV namespace id (32 hex characters).`);
-        process.exit(1);
+    if (writeKvId !== undefined && !KV_NAMESPACE_ID.test(writeKvId)) {
+        const field = isLocal && worker?.previewId !== undefined ? 'preview_id' : 'id';
+        fail(`The ${KV_BINDING} ${field} in ${shown(paths.wranglerConfig)}, "${writeKvId}", is not a KV namespace id (32 hex characters).`);
+    }
+    if (worker && worker.otherEnvs.length > 0) {
+        console.warn(`[i18n] ⚠️  ${shown(paths.wranglerConfig)} binds ${KV_BINDING} to a different id in ` +
+            `${worker.otherEnvs.map((name) => `env.${name}`).join(', ')}; this run uses the top-level binding. ` +
+            'Pass --env <name> to target one of those environments.');
+    }
+    // Two KV namespaces behind one zone and one keyPrefix: their entries share cache URLs, so
+    // each migrate purges, and each Worker caches, the other's.
+    if (worker && worker.sameZoneScopes.length > 0) {
+        console.warn(`[i18n] ⚠️  ${worker.sameZoneScopes.join(', ')} of ${shown(paths.wranglerConfig)} uses the same ` +
+            `CLOUDFLARE_ZONE_ID with another ${KV_BINDING} namespace: with one keyPrefix both cache translations ` +
+            'under the same URLs. Use a per-environment keyPrefix (a config per environment).');
+    }
+    // A zone id from the wrangler config is checked before anything is written; one from the
+    // environment or .dev.vars, at the purge.
+    if (worker?.zoneId !== undefined && !isLocal && !ZONE_ID.test(worker.zoneId)) {
+        fail(`CLOUDFLARE_ZONE_ID "${worker.zoneId}" in ${shown(paths.wranglerConfig)} is not a zone id (32 hex characters).`);
+    }
+    if (command === 'migrate') {
+        assertCleanPurgeBaseline(paths, worker.kvId, worker.topLevelKvId);
     }
     // The Worker's wrangler, found before anything is written.
     let wranglerBin;
@@ -134,24 +224,41 @@ async function run(command, args, paths) {
             wranglerBin = resolveWranglerBin(paths.wranglerRoot);
         }
         catch (err) {
-            console.error(`[i18n] ${err instanceof Error ? err.message : String(err)}`);
-            process.exit(1);
+            fail(errorMessage(err));
         }
     }
     // -------------------------------------------------------------------------
     // 1. Collect translations from <localesDir>/<locale>/<namespace>.json
     // -------------------------------------------------------------------------
-    const collected = collectTranslations(localesDir);
-    // The schema is built here too, so an untypeable value (a mixed array) stops the run
-    // before anything is written.
+    if (!fs.existsSync(localesDir)) {
+        fail(`Locales directory not found: ${localesDir}`);
+    }
+    let collected;
+    let ignored;
+    try {
+        ;
+        ({ collected, ignored } = collectTranslations(localesDir, shown));
+    }
+    catch (err) {
+        fail(errorMessage(err));
+    }
+    for (const file of ignored) {
+        console.warn(`[i18n] ⚠️  ${file} is in a subfolder of its locale folder and is ignored: a namespace is ` +
+            '<localesDir>/<locale>/<namespace>.json.');
+    }
+    // The schema is built here too, so an untypeable value (a mixed array, a null) stops the
+    // run before anything is written.
     let typesContent;
     try {
         assertValidNames(collected, config.languages);
+        assertNoNullValues(collected);
         typesContent = buildTypesContent(collected, defaultLocale);
     }
     catch (err) {
-        console.error(`[i18n] ${err instanceof Error ? err.message : String(err)}`);
-        process.exit(1);
+        fail(errorMessage(err));
+    }
+    for (const warning of translationWarnings(collected, defaultLocale)) {
+        console.warn(`[i18n] ⚠️  ${warning}`);
     }
     const locales = localesWithTranslations(collected);
     if (locales.length === 0) {
@@ -160,18 +267,37 @@ async function run(command, args, paths) {
     // -------------------------------------------------------------------------
     // 2. Compute per-namespace content hashes and detect changes
     // -------------------------------------------------------------------------
-    // Load previous hashes (absent on first run — all namespaces treated as new)
-    const previousHashes = fs.existsSync(paths.hashes)
-        ? JSON.parse(fs.readFileSync(paths.hashes, 'utf8'))
-        : {};
-    const { currentHashes, changedKeys } = diffHashes(collected, previousHashes);
-    if (changedKeys.length > 0) {
-        console.log(`[i18n] Changed namespaces (${changedKeys.length}):`);
-        changedKeys.forEach((k) => console.log(`  - ${k}`));
+    // The parsed baseline file (absent on first run — all namespaces treated as new)
+    let baselineFile;
+    if (fs.existsSync(paths.hashes)) {
+        try {
+            baselineFile = JSON.parse(fs.readFileSync(paths.hashes, 'utf8'));
+        }
+        catch (err) {
+            fail(`${shown(paths.hashes)} is not valid JSON: ${errorMessage(err)}`);
+        }
     }
-    else {
+    // The baseline of the KV namespace migrate writes; bundle reads no wrangler config and
+    // gets one only when the file holds a single baseline.
+    const previousHashes = readBaseline(baselineFile, worker?.kvId, worker?.topLevelKvId);
+    const { currentHashes, changedKeys } = diffHashes(collected, previousHashes ?? {});
+    const removed = previousHashes ? removedKeys(previousHashes, currentHashes) : [];
+    if (previousHashes === undefined) {
+        console.log(`[i18n] ${shown(paths.hashes)} holds baselines for several KV namespaces: seed and migrate list the changes.`);
+    }
+    else if (changedKeys.length === 0 && removed.length === 0) {
         console.log('[i18n] No translation changes detected.');
     }
+    else {
+        if (changedKeys.length > 0) {
+            console.log(`[i18n] Changed namespaces (${changedKeys.length}):`);
+            changedKeys.forEach((k) => console.log(`  - ${k}`));
+        }
+        if (removed.length > 0) {
+            console.log(`[i18n] Removed namespaces (${removed.length}):`);
+            removed.forEach((k) => console.log(`  - ${k}`));
+        }
+    }
     // -------------------------------------------------------------------------
     // 3. Write KV bulk data, types and runtime constants
     // -------------------------------------------------------------------------
@@ -206,76 +332,53 @@ async function run(command, args, paths) {
     // 5. Push to KV + purge changed cache entries via Cloudflare API
     //    seed    → local KV only, no purge, hashes untouched (a warm local cache under
     //              `astro dev` is the consumer's to drop: `I18N_CACHE=off`, restart)
-    //    migrate → remote KV + Cloudflare Purge API, hashes written on success
+    //    migrate → remote KV, removed keys deleted, two purge rounds, hashes written on success
     // -------------------------------------------------------------------------
     if (!shouldDeploy) {
         console.log('[i18n] Skipping KV deploy (bundle). Use `edgekits-i18n seed` or `edgekits-i18n migrate`.');
         return;
     }
-    await deploy({ config, paths, kvId: kvId, wranglerBin: wranglerBin, isLocal, changedKeys, currentHashes });
-}
-function collectTranslations(localesDir) {
-    if (!fs.existsSync(localesDir)) {
-        console.error(`Locales directory not found: ${localesDir}`);
-        process.exit(1);
-    }
-    const localeDirs = fs
-        .readdirSync(localesDir, { withFileTypes: true })
-        .filter((d) => d.isDirectory())
-        .map((d) => d.name)
-        .filter((locale) => {
-        const fullPath = path.join(localesDir, locale);
-        const files = fs.readdirSync(fullPath, { withFileTypes: true });
-        return files.some((f) => f.isFile() && f.name.endsWith('.json'));
+    await deploy({
+        config,
+        paths,
+        options,
+        worker: worker,
+        writeKvId: writeKvId,
+        wranglerBin: wranglerBin,
+        isLocal,
+        changedKeys,
+        removed,
+        currentHashes,
+        baselineFile,
     });
-    const collected = {};
-    for (const locale of localeDirs) {
-        const localeDir = path.join(localesDir, locale);
-        const files = fs
-            .readdirSync(localeDir, { withFileTypes: true })
-            .filter((f) => f.isFile() && f.name.endsWith('.json'));
-        for (const file of files) {
-            const namespace = path.basename(file.name, '.json');
-            const raw = fs.readFileSync(path.join(localeDir, file.name), 'utf8');
-            const json = JSON.parse(raw);
-            if (!collected[locale])
-                collected[locale] = {};
-            collected[locale][namespace] = json;
-        }
-    }
-    return collected;
 }
 function writeFile(file, content) {
     fs.mkdirSync(path.dirname(file), { recursive: true });
     fs.writeFileSync(file, content, 'utf8');
 }
-async function deploy({ config, paths, kvId, wranglerBin, isLocal, changedKeys, currentHashes, }) {
+/**
+ * Run the Worker's wrangler with `args`, then `--config` and `--env` when given. wrangler's
+ * JavaScript entry, run by this Node binary: no shell on any platform (no `.cmd` shim on
+ * Windows), and the arguments are constants, shape-checked ids and names, and absolute paths.
+ * Always an explicit --config, from the Worker root: wrangler resolves `.wrangler/state`
+ * (where a local seed lands, and where `wrangler dev` there reads) from the directory of the
+ * config it loaded, and without --config a stray wrangler.json there would win over the
+ * wrangler.jsonc this CLI read.
+ */
+function runWrangler(wranglerBin, paths, options, args) {
+    const envArgs = options.env !== undefined ? ['--env', options.env] : [];
+    execFileSync(process.execPath, [wranglerBin, ...args, '--config', paths.wranglerConfig, ...envArgs], {
+        cwd: paths.wranglerRoot,
+        stdio: 'inherit',
+    });
+}
+async function deploy({ config, paths, options, worker, writeKvId, wranglerBin, isLocal, changedKeys, removed, currentHashes, baselineFile, }) {
     const kvFlag = isLocal ? '--local' : '--remote';
     const target = isLocal ? 'local' : 'remote';
     // Push all translations to KV
     console.log(`[i18n] Pushing translations to ${target} KV...`);
     try {
-        // wrangler's JavaScript entry, run by this Node binary: no shell on any platform
-        // (no `.cmd` shim on Windows), and the arguments are constants, the shape-checked id
-        // and absolute paths.
-        // Always an explicit --config, from the Worker root: wrangler resolves `.wrangler/state`
-        // (where a local seed lands, and where `wrangler dev` there reads) from the directory
-        // of the config it loaded, and without --config a stray wrangler.json there would win
-        // over the wrangler.jsonc this CLI read.
-        execFileSync(process.execPath, [
-            wranglerBin,
-            'kv',
-            'bulk',
-            'put',
-            paths.data,
-            kvFlag,
-            `--namespace-id=${kvId}`,
-            '--config',
-            paths.wranglerConfig,
-        ], {
-            cwd: paths.wranglerRoot,
-            stdio: 'inherit',
-        });
+        runWrangler(wranglerBin, paths, options, ['kv', 'bulk', 'put', paths.data, kvFlag, `--namespace-id=${writeKvId}`]);
         console.log(`[i18n] ✅ KV updated (${target}).`);
     }
     catch (err) {
@@ -284,25 +387,62 @@ async function deploy({ config, paths, kvId, wranglerBin, isLocal, changedKeys,
     }
     if (isLocal) {
         // Local KV: no purge (a warm local cache under `astro dev` is the consumer's to drop),
-        // and the hashes describe production only.
+        // and the hashes describe remote KV only.
         console.log('[i18n] .i18n-hashes.json left untouched (local seed).');
         return;
     }
     // ---------------------------------------------------------------------------
+    // The removed translation files: their keys leave KV, their URLs join the purge.
+    // ---------------------------------------------------------------------------
+    if (removed.length > 0) {
+        const keys = kvKeysFor(removed, config.keyPrefix);
+        console.log(`[i18n] Deleting ${keys.length} KV key(s) of removed translation files:`);
+        keys.forEach((key) => console.log(`  - ${key}`));
+        const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'edgekits-i18n-'));
+        let deleteError;
+        try {
+            const keysFile = path.join(dir, 'deleted-keys.json');
+            fs.writeFileSync(keysFile, JSON.stringify(keys), 'utf8');
+            runWrangler(wranglerBin, paths, options, [
+                'kv',
+                'bulk',
+                'delete',
+                keysFile,
+                '--remote',
+                `--namespace-id=${writeKvId}`,
+                '--force',
+            ]);
+        }
+        catch (err) {
+            deleteError = err ?? new Error('wrangler kv bulk delete failed');
+        }
+        finally {
+            fs.rmSync(dir, { recursive: true, force: true });
+        }
+        if (deleteError !== undefined) {
+            console.error('[i18n] ❌ Failed to delete the removed keys from remote KV.', deleteError);
+            fail(CACHE_NOT_PURGED);
+        }
+        console.log(`[i18n] ✅ ${keys.length} key(s) deleted.`);
+    }
+    // ---------------------------------------------------------------------------
     // Graceful recovery for the hash file:
     //
     //   We update .i18n-hashes.json ONLY when one of these holds:
     //     - No changes: nothing needed purging to begin with.
-    //     - A successful purge of all changed URLs.
+    //     - Both purge rounds of every changed and removed URL succeeded.
     //
-    //   If a purge was attempted but failed (network error, rate limit
-    //   saturation, API error, missing credentials), we DO NOT write the file.
-    //   This way, the next `edgekits-i18n migrate` will see the same diff as this
-    //   one and re-attempt the invalidation automatically. No manual intervention,
-    //   no silent cache staleness.
+    //   Otherwise (missing zone id or token, network error, rate limit saturation,
+    //   API error) we DO NOT write the file and exit 1: the next `edgekits-i18n
+    //   migrate` sees the same diff and re-attempts the invalidation.
     // ---------------------------------------------------------------------------
-    let shouldWriteHashes = false;
-    if (changedKeys.length === 0) {
+    // `--purge-all`: every current namespace, changed or not (a reverted baseline reports no
+    // change for a rollback), plus the removed ones.
+    const purgeKeys = options.purgeAll ? [...Object.keys(currentHashes), ...removed] : [...changedKeys, ...removed];
+    if (options.purgeAll) {
+        console.log(`[i18n] --purge-all: purging all ${purgeKeys.length} namespace URL(s), changed or not.`);
+    }
+    if (purgeKeys.length === 0) {
         // Nothing changed — nothing to purge, safe to update hashes.
         //
         // Said out loud rather than passed over: a silent no-op on a deploy path is
@@ -310,70 +450,71 @@ async function deploy({ config, paths, kvId, wranglerBin, isLocal, changedKeys,
         // outcome, so not an error — but the operator has to be able to see it, and
         // to see WHICH half of the job was skipped.
         console.log('[i18n] Nothing changed against the recorded baseline, so NO cache entry was purged.\n' +
-            '       The bulk put above is unconditional, so production KV did receive every value;\n' +
+            '       The bulk put above is unconditional, so remote KV did receive every value;\n' +
             '       it is the edge cache that was left alone, and it holds translations for a year.\n' +
             '       If you expected a change here, .i18n-hashes.json is describing a state that\n' +
-            '       production is not actually in.');
-        shouldWriteHashes = true;
+            '       this KV namespace is not actually in (after a git revert of translations, say):\n' +
+            '       run migrate --purge-all.');
+        writeHashes(paths, baselineFile, worker, currentHashes);
+        return;
     }
-    else {
-        // Changes — the purge must succeed before we update hashes.
-        loadDevVars(paths.wranglerRoot);
-        const purgeUrls = purgeUrlsFor(changedKeys, config.keyPrefix);
-        const zoneId = getWranglerVar(paths.wranglerConfig, 'CLOUDFLARE_ZONE_ID') || process.env.CLOUDFLARE_ZONE_ID;
-        const apiToken = process.env.CLOUDFLARE_CACHEPURGE_API_TOKEN;
-        if (!zoneId) {
-            console.warn(`[i18n] ⚠️  CLOUDFLARE_ZONE_ID not found in ${shown(paths.wranglerConfig)} vars or environment. ` +
-                'Skipping cache purge — hash file NOT updated. Re-run `edgekits-i18n migrate` after setting the variable.');
-        }
-        else if (!apiToken) {
-            console.warn('[i18n] ⚠️  CLOUDFLARE_CACHEPURGE_API_TOKEN not set in environment. ' +
-                'Skipping cache purge — hash file NOT updated. Re-run `edgekits-i18n migrate` after setting the secret.');
-        }
-        else {
-            // Advisory: the Purge API reports success even for URLs it cannot reach, so the
-            // name is all there is to check. Never decides shouldWriteHashes.
-            await checkKeyPrefixZone(config.keyPrefix, zoneId, apiToken);
-            console.log(`[i18n] Purging ${purgeUrls.length} cache entries via Cloudflare API...`);
-            const purgeSuccess = await purgeTranslationsCache(zoneId, apiToken, purgeUrls);
-            if (purgeSuccess) {
-                console.log('[i18n] ✅ Cache purge completed.');
-                shouldWriteHashes = true;
-            }
-            else {
-                console.error('[i18n] ❌ Cache purge failed — hash file NOT updated. ' +
-                    'Re-run `edgekits-i18n migrate` to retry the same invalidation.');
-                // Non-fatal for KV: translations are already pushed. Cache will
-                // converge on the next successful migrate.
-            }
-        }
+    loadDevVars(paths.wranglerRoot, options.env);
+    const zoneId = worker.zoneId || process.env.CLOUDFLARE_ZONE_ID;
+    const apiToken = process.env.CLOUDFLARE_CACHEPURGE_API_TOKEN;
+    const scope = options.env !== undefined
+        ? `env.${options.env}.vars of ${shown(paths.wranglerConfig)}`
+        : `${shown(paths.wranglerConfig)} vars`;
+    if (!zoneId) {
+        fail(`❌ CLOUDFLARE_ZONE_ID not found in ${scope} or the environment, so the cache purge was skipped. ${CACHE_NOT_PURGED}`);
     }
-    if (shouldWriteHashes) {
-        fs.writeFileSync(paths.hashes, JSON.stringify(currentHashes, null, 2) + '\n', 'utf8');
-        console.log(`[i18n] ✅ ${shown(paths.hashes)} updated.`);
+    if (!ZONE_ID.test(zoneId)) {
+        fail(`❌ CLOUDFLARE_ZONE_ID "${zoneId}" is not a zone id (32 hex characters), so the cache purge was skipped. ${CACHE_NOT_PURGED}`);
     }
+    if (!apiToken) {
+        fail(`❌ CLOUDFLARE_CACHEPURGE_API_TOKEN not set in the environment or .dev.vars, so the cache purge was skipped. ${CACHE_NOT_PURGED}`);
+    }
+    // Advisory: the Purge API reports success even for URLs it cannot reach, so the
+    // name is all there is to check. Never decides whether the hashes are written.
+    await checkKeyPrefixZone(config.keyPrefix, zoneId, apiToken);
+    const purgeUrls = purgeUrlsFor(purgeKeys, config.keyPrefix);
+    console.log(`[i18n] Purging ${purgeUrls.length} cache entries via Cloudflare API...`);
+    if (!(await purgeTranslationsCache(zoneId, apiToken, purgeUrls))) {
+        fail(`❌ Cache purge failed. ${CACHE_NOT_PURGED}`);
+    }
+    // A read of a purged URL in a location where KV still shows the old value caches that
+    // old value again, for a year. The same URLs are purged again once KV has settled.
+    if (options.purgeDelay > 0) {
+        console.log(`[i18n] Waiting ${options.purgeDelay} s for KV to settle, then purging the same ${purgeUrls.length} URL(s) again: ` +
+            'KV can take up to 60 s to show a write in other locations, and a read there meanwhile re-caches the old value.');
+        await new Promise((resolve) => setTimeout(resolve, options.purgeDelay * 1000));
+        if (!(await purgeTranslationsCache(zoneId, apiToken, purgeUrls))) {
+            fail(`❌ The second cache purge failed. ${CACHE_NOT_PURGED}`);
+        }
+    }
+    console.log('[i18n] ✅ Cache purge completed.');
+    writeHashes(paths, baselineFile, worker, currentHashes);
+}
+// The baseline of the Worker's KV id replaced in the file, the other namespaces' kept
+// (ADR-0034); an old flat file stays the top-level id's.
+function writeHashes(paths, baselineFile, worker, hashes) {
+    const file = writeBaseline(baselineFile, worker.kvId, hashes, worker.topLevelKvId);
+    fs.writeFileSync(paths.hashes, JSON.stringify(file, null, 2) + '\n', 'utf8');
+    console.log(`[i18n] ✅ ${shown(paths.hashes)} updated.`);
 }
 /**
  * Load the Worker root's .dev.vars into process.env. wrangler dev reads .dev.vars for
- * the Worker runtime, but Node does not — so it is parsed here. Never overwrites a
- * variable already set in the real environment.
+ * the Worker runtime, but Node does not — so it is parsed here, with the same dotenv
+ * syntax (dev-vars.ts). With `--env <name>`, `.dev.vars.<name>` replaces `.dev.vars` when it
+ * exists, as in wrangler (the two are not merged). Never overwrites a variable already set
+ * in the real environment.
  */
-function loadDevVars(wranglerRoot) {
-    const devVarsPath = path.join(wranglerRoot, '.dev.vars');
+function loadDevVars(wranglerRoot, env) {
+    const envPath = env !== undefined ? path.join(wranglerRoot, `.dev.vars.${env}`) : undefined;
+    const devVarsPath = envPath !== undefined && fs.existsSync(envPath) ? envPath : path.join(wranglerRoot, '.dev.vars');
     if (!fs.existsSync(devVarsPath))
         return;
-    const lines = fs.readFileSync(devVarsPath, 'utf8').split('\n');
-    for (const line of lines) {
-        const trimmed = line.trim();
-        // Skip empty lines and comments
-        if (!trimmed || trimmed.startsWith('#'))
-            continue;
-        const eqIndex = trimmed.indexOf('=');
-        if (eqIndex === -1)
-            continue;
-        const key = trimmed.slice(0, eqIndex).trim();
-        const value = trimmed.slice(eqIndex + 1).trim();
-        if (key && !(key in process.env)) {
+    for (const [key, value] of Object.entries(parseDevVars(fs.readFileSync(devVarsPath, 'utf8')))) {
+        if (!(key in process.env)) {
             process.env[key] = value;
         }
     }
@@ -381,15 +522,15 @@ function loadDevVars(wranglerRoot) {
 // ---------------------------------------------------------------------------
 // Precondition (migrate only): the purge baseline must be clean
 //
-// `.i18n-hashes.json` records what PRODUCTION KV already holds, and the diff
+// `.i18n-hashes.json` records what remote KV already holds, and the diff
 // against it is the ONLY thing that decides which cache entries get purged.
 //
 // Migrate against a modified copy and the diff comes out wrong. Note what that
 // does and does not break: the bulk put is unconditional, so every value still
-// reaches production KV. What is skipped is the PURGE — and translations are
-// served `s-maxage=31536000, immutable` (see fetcher.ts), so the stale edge copy
+// reaches KV. What is skipped is the PURGE — and translations are served
+// `s-maxage=31536000, immutable` (see fetcher.ts), so the stale edge copy
 // never ages out. A purge is the only thing that ends it. The run then writes a
-// baseline claiming production is current, and exits 0.
+// baseline claiming KV is current, and exits 0.
 //
 // The live page that results is neither the old one nor the new one: keys that
 // exist only in the shipped fallbacks render beside keys still served stale
@@ -398,49 +539,65 @@ function loadDevVars(wranglerRoot) {
 // precondition that refuses to run, rather than a warning nobody sees.
 //
 // `seed` never writes this file, so it is exempt and never dirties it.
+//
+// Only the baseline of the KV namespace this run writes is compared with the committed
+// file (`git show HEAD:<file>`): a migrate of another namespace earlier in the same job
+// (`migrate --env staging && migrate`) changes only its own entry.
 // ---------------------------------------------------------------------------
 /**
- * Abort if the purge baseline carries uncommitted changes.
+ * Abort if the baseline of `kvId` in the purge baseline file differs from the committed
+ * one. `flatOwner`: the top-level KV id, whose baseline an old flat file is.
  *
  * Outside a git work tree, or with no git on PATH, this warns and proceeds: a
  * guard on the deploy path must not be the reason the CLI cannot run in CI
  * or from a tarball.
  */
-function assertCleanPurgeBaseline(paths) {
-    // git runs from the project root on the bare file name; messages show the path from
-    // where the CLI was run.
+function assertCleanPurgeBaseline(paths, kvId, flatOwner) {
+    // git runs from the project root on the file's path from there; messages show the path
+    // from where the CLI was run.
     const relativePath = path.relative(paths.root, paths.hashes).split(path.sep).join('/');
     const shownPath = shown(paths.hashes);
-    let status;
+    const git = (args) => execFileSync('git', args, { cwd: paths.root, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] });
     try {
-        // Porcelain v1 is a stable format, and `--` scopes it to the one path, so a
-        // dirty working tree elsewhere (the usual state) is not this guard's business.
-        status = execFileSync('git', ['status', '--porcelain', '--', relativePath], {
-            cwd: paths.root,
-            encoding: 'utf8',
-            stdio: ['ignore', 'pipe', 'pipe'],
-        });
+        git(['rev-parse', '--is-inside-work-tree']);
     }
     catch (err) {
         console.warn(`[i18n] ⚠️  Could not check ${shownPath} against git (${err instanceof Error ? err.message.split('\n')[0] : String(err)}).\n` +
             '        Proceeding WITHOUT the purge-baseline check. If that file carries hashes\n' +
-            '        that do not describe production, this run will skip the cache purge and say nothing.');
+            '        that do not describe KV, this run will skip the cache purge and say nothing.');
+        return;
+    }
+    // The committed file; none when HEAD does not have it (a first migrate, or no commit yet).
+    let committed;
+    try {
+        committed = git(['show', `HEAD:./${relativePath}`]);
+    }
+    catch {
+        committed = undefined;
+    }
+    const working = fs.existsSync(paths.hashes) ? fs.readFileSync(paths.hashes, 'utf8') : undefined;
+    const entryOf = (text) => text === undefined ? {} : readBaseline(JSON.parse(text), kvId, flatOwner);
+    let same;
+    try {
+        same = stableStringify(entryOf(committed)) === stableStringify(entryOf(working));
+    }
+    catch {
+        // Not JSON: the run itself reports the working file; a broken committed one is history.
         return;
     }
-    if (status.trim() === '')
+    if (same)
         return;
-    console.error(`\n[i18n] ❌ ${shownPath} has uncommitted changes. Refusing to migrate.\n` +
-        `\n  git status --porcelain: ${status.trim()}\n` +
-        '\n  That file is the purge baseline: the record of what production KV already holds.\n' +
+    console.error(`\n[i18n] ❌ ${shownPath}: the baseline of KV namespace ${kvId} differs from the committed one (HEAD). Refusing to migrate.\n` +
+        '\n  That file is the purge baseline: the record of what remote KV already holds.\n' +
         '  Migrating against a modified copy makes the change diff come out wrong. Every value\n' +
         '  is still pushed to KV, but the cache purge is driven by that diff, so stale edge\n' +
         '  entries survive — and translations are cached immutable for a year, so they do not\n' +
         '  age out on their own. The run would exit 0 as though it had worked.\n' +
         '\n  Two things dirty this file, and they need opposite fixes:\n' +
         '\n    1. Something other than migrate wrote it (a hand edit, or a pre-package local\n' +
-        '       seed script). Those hashes lie about production. Discard them, then migrate:\n' +
+        '       seed script). Those hashes lie about KV. Discard them, then migrate:\n' +
         `           git checkout ${shownPath} && npx edgekits-i18n migrate\n` +
-        '\n    2. A previous `edgekits-i18n migrate` wrote it. Those hashes describe production\n' +
+        '\n    2. A previous `edgekits-i18n migrate` wrote it. Those hashes describe KV\n' +
         '       and are correct. Commit them; migrating again is unnecessary:\n' +
         `           git add ${shownPath} && git commit\n` +
         '\n  The CLI cannot tell the two apart — the file looks identical either way. If you\n' +