@edgekits/astro-i18n 0.0.0-stage → 0.1.1

package/dist/cli/generate.d.ts

@@ -0,0 +1,47 @@
+/**
+ * The CLI's code generation, as pure functions of the collected locale tree: no
+ * filesystem, so the emitted text is testable. Formats are those of the site's
+ * `scripts/bundle-translations.ts`, header aside.
+ */
+export type TranslationTree = Record<string, unknown>;
+export type CollectedData = Record<string, Record<string, TranslationTree>>;
+export type KvBulkEntry = {
+    key: string;
+    value: string;
+};
+export declare const NAMESPACE_NAME: RegExp;
+/**
+ * Throws, naming the offender, when a locale folder is not one of the config's
+ * `languages` or a namespace file name does not match NAMESPACE_NAME. Run on the
+ * collected tree before anything is generated or pushed.
+ */
+export declare function assertValidNames(collected: CollectedData, languages: Readonly<Record<string, unknown>>): void;
+/**
+ * A single-quoted TS string literal, escaped by JSON.stringify. For every name the
+ * validation accepts it is byte-identical to the plain `'name'` the CLI always wrote, so
+ * existing generated files do not change; anything else comes out escaped, not injected.
+ */
+export declare function quoteString(value: string): string;
+/** Locales that have at least one namespace, sorted. */
+export declare function localesWithTranslations(collected: CollectedData): string[];
+/**
+ * The locale the schema and the namespace list are derived from: the default locale
+ * when it has translations, otherwise the first locale that does.
+ */
+export declare function schemaSourceLocale(collected: CollectedData, defaultLocale: string): string | undefined;
+/** `wrangler kv bulk put` input: one entry per locale and namespace. */
+export declare function buildBulkData(collected: CollectedData, keyPrefix: string): KvBulkEntry[];
+/** `src/i18n.generated.d.ts`: the global `I18n.Schema`, from the schema source locale. */
+export declare function buildTypesContent(collected: CollectedData, defaultLocale: string): string;
+/**
+ * `runtime-constants.ts`:
+ *   - NAMESPACE_KEYS            -> from the schema source locale (default locale preferred)
+ *   - LOCALES_WITH_TRANSLATIONS -> from all collected locales
+ *   - FULLY_TRANSLATED_LOCALES  -> locales that have ALL namespace keys
+ */
+export declare function buildRuntimeConstantsContent(collected: CollectedData, defaultLocale: string): string;
+/**
+ * `fallbacks.generated.ts`: one `FALLBACK_<NAMESPACE>` per default-locale namespace.
+ * Null when the default locale has no translations (nothing to fall back to).
+ */
+export declare function buildFallbacksContent(collected: CollectedData, defaultLocale: string): string | null;

package/dist/cli/generate.js

@@ -0,0 +1,133 @@
+import { formatTranslationKvKey } from "../key-format.js";
+const HEADER = `// Auto-generated by @edgekits/astro-i18n (edgekits-i18n CLI)
+// Do not edit manually.
+`;
+// A namespace becomes part of a KV key, a cache URL and the `FALLBACK_<NAMESPACE>`
+// identifier, so its file name is restricted to what is valid in all three.
+export const NAMESPACE_NAME = /^[a-z0-9][a-z0-9_]*$/;
+/**
+ * Throws, naming the offender, when a locale folder is not one of the config's
+ * `languages` or a namespace file name does not match NAMESPACE_NAME. Run on the
+ * collected tree before anything is generated or pushed.
+ */
+export function assertValidNames(collected, languages) {
+    const configured = Object.keys(languages);
+    for (const [locale, namespaces] of Object.entries(collected)) {
+        if (!configured.includes(locale)) {
+            throw new Error(`Locale folder "${locale}" is not one of \`languages\` in edgekits-i18n.config.ts: ${configured.join(', ')}.`);
+        }
+        for (const ns of Object.keys(namespaces)) {
+            if (!NAMESPACE_NAME.test(ns)) {
+                throw new Error(`Namespace "${ns}" (${locale}/${ns}.json) must match ${NAMESPACE_NAME}: lowercase letters, digits and underscores.`);
+            }
+        }
+    }
+}
+/**
+ * A single-quoted TS string literal, escaped by JSON.stringify. For every name the
+ * validation accepts it is byte-identical to the plain `'name'` the CLI always wrote, so
+ * existing generated files do not change; anything else comes out escaped, not injected.
+ */
+export function quoteString(value) {
+    const escaped = JSON.stringify(value).slice(1, -1).replace(/\\"/g, '"').replace(/'/g, "\\'");
+    return `'${escaped}'`;
+}
+/** Locales that have at least one namespace, sorted. */
+export function localesWithTranslations(collected) {
+    return Object.keys(collected).sort();
+}
+/**
+ * The locale the schema and the namespace list are derived from: the default locale
+ * when it has translations, otherwise the first locale that does.
+ */
+export function schemaSourceLocale(collected, defaultLocale) {
+    if (collected[defaultLocale])
+        return defaultLocale;
+    return localesWithTranslations(collected)[0];
+}
+/** `wrangler kv bulk put` input: one entry per locale and namespace. */
+export function buildBulkData(collected, keyPrefix) {
+    const bulkData = [];
+    for (const [locale, namespaces] of Object.entries(collected)) {
+        for (const [ns, json] of Object.entries(namespaces)) {
+            bulkData.push({ key: formatTranslationKvKey(keyPrefix, locale, ns), value: JSON.stringify(json) });
+        }
+    }
+    return bulkData;
+}
+function generateSchemaTs(schema, indent = 4) {
+    const pad = ' '.repeat(indent);
+    const padInner = ' '.repeat(indent + 2);
+    if (schema && typeof schema === 'object' && !Array.isArray(schema)) {
+        const entries = Object.entries(schema);
+        if (entries.length === 0)
+            return '{}';
+        const lines = entries.map(([key, value]) => {
+            const valueTs = value && typeof value === 'object' && !Array.isArray(value)
+                ? generateSchemaTs(value, indent + 2)
+                : 'string';
+            return `${padInner}${JSON.stringify(key)}: ${valueTs}`;
+        });
+        return `{\n${lines.join(';\n')};\n${pad}}`;
+    }
+    return 'string';
+}
+/** `src/i18n.generated.d.ts`: the global `I18n.Schema`, from the schema source locale. */
+export function buildTypesContent(collected, defaultLocale) {
+    const source = schemaSourceLocale(collected, defaultLocale);
+    const schemaObject = (source && collected[source]) || {};
+    const namespaceLines = Object.entries(schemaObject).map(([ns, value]) => {
+        const valueTs = generateSchemaTs(value, 10);
+        return `      ${JSON.stringify(ns)}: ${valueTs}`;
+    });
+    const interfaceBody = namespaceLines.length > 0
+        ? `    export interface Schema {\n${namespaceLines.join(';\n')};\n    }`
+        : `    export interface Schema {}`;
+    return `${HEADER}
+declare global {
+  namespace I18n {
+${interfaceBody}
+  }
+}
+
+export {}
+`;
+}
+/**
+ * `runtime-constants.ts`:
+ *   - NAMESPACE_KEYS            -> from the schema source locale (default locale preferred)
+ *   - LOCALES_WITH_TRANSLATIONS -> from all collected locales
+ *   - FULLY_TRANSLATED_LOCALES  -> locales that have ALL namespace keys
+ */
+export function buildRuntimeConstantsContent(collected, defaultLocale) {
+    const source = schemaSourceLocale(collected, defaultLocale);
+    const namespaceKeys = Object.keys((source && collected[source]) || {}).sort();
+    const locales = localesWithTranslations(collected);
+    const fullyTranslatedLocales = locales.filter((locale) => {
+        const localeNamespaces = Object.keys(collected[locale] || {});
+        return namespaceKeys.every((ns) => localeNamespaces.includes(ns));
+    });
+    return `${HEADER}
+export const NAMESPACE_KEYS = [${namespaceKeys.map(quoteString).join(', ')}] as [string, ...string[]];
+
+export const LOCALES_WITH_TRANSLATIONS = [${locales.map(quoteString).join(', ')}] as const;
+
+export const FULLY_TRANSLATED_LOCALES = [${fullyTranslatedLocales.map(quoteString).join(', ')}] as const;
+`;
+}
+/**
+ * `fallbacks.generated.ts`: one `FALLBACK_<NAMESPACE>` per default-locale namespace.
+ * Null when the default locale has no translations (nothing to fall back to).
+ */
+export function buildFallbacksContent(collected, defaultLocale) {
+    const fallbackNamespaces = collected[defaultLocale];
+    if (!fallbackNamespaces)
+        return null;
+    const lines = [HEADER];
+    lines.push(`export const FALLBACK_LOCALE = ${JSON.stringify(defaultLocale)} as const;\n`);
+    for (const [ns, json] of Object.entries(fallbackNamespaces)) {
+        const constName = `FALLBACK_${ns.toUpperCase()}`;
+        lines.push(`export const ${constName} = ${JSON.stringify(json, null, 2)} as const;\n`);
+    }
+    return lines.join('\n');
+}

package/dist/cli/hashes.d.ts

@@ -0,0 +1,19 @@
+import type { CollectedData } from './generate.ts';
+/**
+ * Per-namespace content hashes and the change diff that drives the cache purge.
+ * Pure apart from hashing. Same algorithm as the site's `scripts/bundle-translations.ts`,
+ * so an existing `.i18n-hashes.json` stays a valid baseline.
+ */
+export type HashMap = Record<string, string>;
+export declare function stableStringify(value: unknown): string;
+export declare function computeHash(value: unknown): string;
+/**
+ * Hash every collected namespace and list the "<locale>:<namespace>" pairs whose hash
+ * differs from the previous run (all of them when there is no previous run).
+ */
+export declare function diffHashes(collected: CollectedData, previousHashes: HashMap): {
+    currentHashes: HashMap;
+    changedKeys: string[];
+};
+/** Purge API URLs for the changed "<locale>:<namespace>" pairs. */
+export declare function purgeUrlsFor(changedKeys: readonly string[], keyPrefix: string): string[];

package/dist/cli/hashes.js

@@ -0,0 +1,42 @@
+import crypto from 'node:crypto';
+import { formatTranslationCacheUrl } from "../key-format.js";
+export function stableStringify(value) {
+    if (value === null || typeof value !== 'object') {
+        return JSON.stringify(value);
+    }
+    if (Array.isArray(value)) {
+        return '[' + value.map(stableStringify).join(',') + ']';
+    }
+    const entries = Object.entries(value).sort(([a], [b]) => a.localeCompare(b));
+    return '{' + entries.map(([k, v]) => JSON.stringify(k) + ':' + stableStringify(v)).join(',') + '}';
+}
+export function computeHash(value) {
+    const json = stableStringify(value);
+    return crypto.createHash('sha256').update(json).digest('hex').slice(0, 12);
+}
+/**
+ * Hash every collected namespace and list the "<locale>:<namespace>" pairs whose hash
+ * differs from the previous run (all of them when there is no previous run).
+ */
+export function diffHashes(collected, previousHashes) {
+    const currentHashes = {};
+    const changedKeys = [];
+    for (const [locale, namespaces] of Object.entries(collected)) {
+        for (const [ns, json] of Object.entries(namespaces)) {
+            const hashKey = `${locale}:${ns}`;
+            const hash = computeHash(json);
+            currentHashes[hashKey] = hash;
+            if (previousHashes[hashKey] !== hash) {
+                changedKeys.push(hashKey);
+            }
+        }
+    }
+    return { currentHashes, changedKeys };
+}
+/** Purge API URLs for the changed "<locale>:<namespace>" pairs. */
+export function purgeUrlsFor(changedKeys, keyPrefix) {
+    return changedKeys.map((hashKey) => {
+        const [locale, ns] = hashKey.split(':');
+        return formatTranslationCacheUrl(keyPrefix, locale, ns);
+    });
+}

package/dist/cli/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli/index.js

@@ -0,0 +1,362 @@
+#!/usr/bin/env node
+import { execFileSync } from 'node:child_process';
+import fs from 'node:fs';
+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 { CONFIG_FILE, loadI18nConfig } from "./load-config.js";
+import { purgeTranslationsCache } from "./purge.js";
+import { getKvNamespaceId, getWranglerVar, KV_BINDING, resolveWranglerBin } from "./wrangler.js";
+const HELP = `Usage: edgekits-i18n <command> [--fallbacks]
+
+Reads ${CONFIG_FILE} and <localesDir>/<locale>/<namespace>.json from the current 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.
+`;
+const COMMANDS = ['bundle', 'seed', 'migrate'];
+const ROOT = process.cwd();
+// Fixed outputs at the project root.
+const OUTPUT_DATA = path.join(ROOT, 'i18n-data.json');
+const OUTPUT_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.
+const HASHES_FILE = path.join(ROOT, '.i18n-hashes.json');
+const KV_NAMESPACE_ID = /^[0-9a-f]{32}$/i;
+await main(process.argv.slice(2));
+async function main(args) {
+    const command = args.find((arg) => !arg.startsWith('-'));
+    if (!command || args.includes('--help') || args.includes('-h')) {
+        console.log(HELP);
+        return;
+    }
+    if (!COMMANDS.includes(command)) {
+        console.error(`[i18n] Unknown command "${command}".\n`);
+        console.error(HELP);
+        process.exit(1);
+    }
+    await run(command, args);
+}
+async function run(command, args) {
+    const shouldDeploy = command !== 'bundle';
+    const isLocal = command === 'seed';
+    const shouldGenerateFallbacks = shouldDeploy || args.includes('--fallbacks') || process.env.I18N_GENERATE_FALLBACKS === 'true';
+    if (command === 'migrate') {
+        assertCleanPurgeBaseline();
+    }
+    const config = await loadI18nConfig(ROOT);
+    const defaultLocale = config.defaultLocale;
+    const localesDir = path.join(ROOT, config.localesDir ?? DEFAULT_LOCALES_DIR);
+    const generatedDir = path.join(ROOT, config.generatedDir ?? DEFAULT_GENERATED_DIR);
+    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(ROOT, KV_BINDING) : undefined;
+    // 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 wrangler.jsonc, "${kvId}", is not a KV namespace id (32 hex characters).`);
+        process.exit(1);
+    }
+    // The project's wrangler, found before anything is written.
+    let wranglerBin;
+    if (shouldDeploy) {
+        try {
+            wranglerBin = resolveWranglerBin(ROOT);
+        }
+        catch (err) {
+            console.error(`[i18n] ${err instanceof Error ? err.message : String(err)}`);
+            process.exit(1);
+        }
+    }
+    // -------------------------------------------------------------------------
+    // 1. Collect translations from <localesDir>/<locale>/<namespace>.json
+    // -------------------------------------------------------------------------
+    const collected = collectTranslations(localesDir);
+    try {
+        assertValidNames(collected, config.languages);
+    }
+    catch (err) {
+        console.error(`[i18n] ${err instanceof Error ? err.message : String(err)}`);
+        process.exit(1);
+    }
+    const locales = localesWithTranslations(collected);
+    if (locales.length === 0) {
+        console.warn(`[i18n] No locales with JSON files found in ${localesDir}. Generating empty artifacts.`);
+    }
+    // -------------------------------------------------------------------------
+    // 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(HASHES_FILE)
+        ? JSON.parse(fs.readFileSync(HASHES_FILE, 'utf8'))
+        : {};
+    const { currentHashes, changedKeys } = diffHashes(collected, previousHashes);
+    if (changedKeys.length > 0) {
+        console.log(`[i18n] Changed namespaces (${changedKeys.length}):`);
+        changedKeys.forEach((k) => console.log(`  - ${k}`));
+    }
+    else {
+        console.log('[i18n] No translation changes detected.');
+    }
+    // -------------------------------------------------------------------------
+    // 3. Write KV bulk data, types and runtime constants
+    // -------------------------------------------------------------------------
+    fs.writeFileSync(OUTPUT_DATA, JSON.stringify(buildBulkData(collected, config.keyPrefix), null, 2) + '\n', 'utf8');
+    const source = schemaSourceLocale(collected, defaultLocale);
+    if (source && source !== defaultLocale) {
+        console.warn(`[i18n] defaultLocale="${defaultLocale}" has no translation files. ` +
+            `Using "${source}" as the source for I18n.Schema.`);
+    }
+    writeFile(OUTPUT_TYPES, buildTypesContent(collected, defaultLocale));
+    writeFile(outputRuntimeConstants, buildRuntimeConstantsContent(collected, defaultLocale));
+    // -------------------------------------------------------------------------
+    // 4. Fallbacks (seed, migrate, or bundle --fallbacks)
+    // -------------------------------------------------------------------------
+    let wroteFallbacks = false;
+    if (shouldGenerateFallbacks) {
+        const fallbacksContent = buildFallbacksContent(collected, defaultLocale);
+        if (fallbacksContent === null) {
+            console.warn(`[i18n] No translations found for defaultLocale="${defaultLocale}". ` + 'Skipping fallback generation.');
+        }
+        else {
+            writeFile(outputFallbacks, fallbacksContent);
+            wroteFallbacks = true;
+        }
+    }
+    else {
+        console.log('[i18n] Skipping fallback generation. Enable with I18N_GENERATE_FALLBACKS=true or --fallbacks.');
+    }
+    const outputs = [OUTPUT_DATA, OUTPUT_TYPES, outputRuntimeConstants, wroteFallbacks ? outputFallbacks : null].filter(Boolean);
+    console.log('Generated:\n' + outputs.map((p) => `- ${path.relative(ROOT, p).split(path.sep).join('/')}`).join('\n'));
+    // -------------------------------------------------------------------------
+    // 5. Push to KV + purge changed cache entries via Cloudflare API
+    //    seed    → local KV only, no purge (local KV; the edge cache is not involved), hashes untouched
+    //    migrate → remote KV + Cloudflare Purge API, 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, 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'));
+    });
+    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, kvId, wranglerBin, isLocal, changedKeys, currentHashes, }) {
+    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 plus the shape-checked id.
+        execFileSync(process.execPath, [wranglerBin, 'kv', 'bulk', 'put', 'i18n-data.json', kvFlag, `--namespace-id=${kvId}`], {
+            cwd: ROOT,
+            stdio: 'inherit',
+        });
+        console.log(`[i18n] ✅ KV updated (${target}).`);
+    }
+    catch (err) {
+        console.error(`[i18n] ❌ Failed to push to ${target} KV.`, err);
+        process.exit(1);
+    }
+    if (isLocal) {
+        // Local KV: no purge (the edge cache is not involved), and the hashes describe production only.
+        console.log('[i18n] .i18n-hashes.json left untouched (local seed).');
+        return;
+    }
+    // ---------------------------------------------------------------------------
+    // 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.
+    //
+    //   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.
+    // ---------------------------------------------------------------------------
+    let shouldWriteHashes = false;
+    if (changedKeys.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
+        // what made the 2026-09-12 staleness take an afternoon to find. Legitimate
+        // 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' +
+            '       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;
+    }
+    else {
+        // Changes — the purge must succeed before we update hashes.
+        loadDevVars();
+        const purgeUrls = purgeUrlsFor(changedKeys, config.keyPrefix);
+        const zoneId = getWranglerVar(ROOT, '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 wrangler.jsonc 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 {
+            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.
+            }
+        }
+    }
+    if (shouldWriteHashes) {
+        fs.writeFileSync(HASHES_FILE, JSON.stringify(currentHashes, null, 2) + '\n', 'utf8');
+        console.log('[i18n] ✅ .i18n-hashes.json updated.');
+    }
+}
+/**
+ * Load .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.
+ */
+function loadDevVars() {
+    const devVarsPath = path.join(ROOT, '.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)) {
+            process.env[key] = value;
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// Precondition (migrate only): the purge baseline must be clean
+//
+// `.i18n-hashes.json` records what PRODUCTION 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
+// 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.
+//
+// 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
+// from the edge. That reached production on 2026-09-12, and nothing failed
+// loudly — it was caught by somebody reading the live page. Hence a
+// precondition that refuses to run, rather than a warning nobody sees.
+//
+// `seed` never writes this file, so it is exempt and never dirties it.
+// ---------------------------------------------------------------------------
+/**
+ * Abort if the purge baseline carries uncommitted changes.
+ *
+ * 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() {
+    const relativePath = path.relative(ROOT, HASHES_FILE).split(path.sep).join('/');
+    let status;
+    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: ROOT,
+            encoding: 'utf8',
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
+    }
+    catch (err) {
+        console.warn(`[i18n] ⚠️  Could not check ${relativePath} 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.');
+        return;
+    }
+    if (status.trim() === '')
+        return;
+    console.error(`\n[i18n] ❌ ${relativePath} 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' +
+        '  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' +
+        '           git checkout .i18n-hashes.json && npx edgekits-i18n migrate\n' +
+        '\n    2. A previous `edgekits-i18n migrate` wrote it. Those hashes describe production\n' +
+        '       and are correct. Commit them; migrating again is unnecessary:\n' +
+        '           git add .i18n-hashes.json && git commit\n' +
+        '\n  The CLI cannot tell the two apart — the file looks identical either way. If you\n' +
+        '  are unsure, the last i18n command you ran is the answer.\n');
+    process.exit(1);
+}

package/dist/cli/load-config.d.ts

@@ -0,0 +1,7 @@
+import { type I18nConfig } from '../types.ts';
+export declare const CONFIG_FILE = "edgekits-i18n.config.ts";
+/**
+ * Load the project's `edgekits-i18n.config.ts` from `root` — the same file its
+ * `astro.config` passes to the integration — and validate it.
+ */
+export declare function loadI18nConfig(root: string): Promise<I18nConfig>;

package/dist/cli/load-config.js

@@ -0,0 +1,19 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { createJiti } from 'jiti';
+import { defineI18nConfig } from "../types.js";
+export const CONFIG_FILE = 'edgekits-i18n.config.ts';
+/**
+ * Load the project's `edgekits-i18n.config.ts` from `root` — the same file its
+ * `astro.config` passes to the integration — and validate it.
+ */
+export async function loadI18nConfig(root) {
+    const configPath = path.join(root, CONFIG_FILE);
+    if (!fs.existsSync(configPath)) {
+        console.error(`[i18n] ${CONFIG_FILE} not found in ${root}`);
+        process.exit(1);
+    }
+    const jiti = createJiti(import.meta.url);
+    const config = await jiti.import(configPath, { default: true });
+    return defineI18nConfig(config);
+}

package/dist/cli/purge.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Purge a list of URLs from Cloudflare's edge cache via the Purge API.
+ *
+ * Handles Cloudflare's rate limits automatically:
+ *   - Max 100 URLs per request (max operations per request)
+ *   - Max 800 URLs per second on Free plan (8 chunks of 100)
+ *   - HTTP 429: up to MAX_RETRIES retries per chunk, waiting `Retry-After` seconds when
+ *     the response sends it, otherwise 2 s, 4 s, 8 s… (every wait capped at
+ *     MAX_RETRY_WAIT_MS); then the chunk counts as failed.
+ *
+ * Reference: https://developers.cloudflare.com/cache/how-to/purge-cache/
+ *
+ * `deps` replaces `fetch` and the wait in tests.
+ *
+ * @returns true if all chunks succeeded, false if any chunk failed
+ */
+export declare function purgeTranslationsCache(zoneId: string, apiToken: string, urls: string[], deps?: PurgeDeps): Promise<boolean>;
+export type PurgeDeps = {
+    fetch?: (input: string, init: RequestInit) => Promise<Response>;
+    sleep?: (ms: number) => Promise<void>;
+};
+export declare const MAX_RETRIES = 5;
+export declare const MAX_RETRY_WAIT_MS = 30000;
+/**
+ * The wait before 429 retry number `attempt` (1-based): `Retry-After` in seconds when
+ * the header holds a non-negative number, otherwise 2 s doubled per attempt. Either way
+ * capped at MAX_RETRY_WAIT_MS, so a large header cannot stall the run.
+ */
+export declare function retryWaitMs(retryAfter: string | null, attempt: number): number;