nextjs-cms 0.9.20 → 0.9.22

package/dist/cli/lib/update-sections.js

@@ -1,18 +1,17 @@
-import { db } from '../../db/client.js';
-import { NextJsCmsTablesTable } from '../../db/schema.js';
-import { eq, sql } from 'drizzle-orm';
 import fs from 'fs';
 import path from 'path';
-import { SectionFactory } from '../../core/factories/index.js';
-import { getCMSConfig } from '../../core/config/index.js';
-import { CheckboxField, ColorField, DateField, DateRangeField, MapField, NumberField, PasswordField, RichTextField, SelectField, SelectMultipleField, TagsField, TextAreaField, TextField, textAreaField, textField, numberField, } from '../../core/fields/index.js';
-import { is } from '../../core/helpers/index.js';
-import { FileField } from '../../core/fields/index.js';
+import { intro, log, select, spinner } from '@clack/prompts';
 import chalk from 'chalk';
-import { intro, select, spinner, log } from '@clack/prompts';
+import { eq, sql } from 'drizzle-orm';
+import { getCMSConfig } from '../../core/config/index.js';
 import { MysqlTableChecker } from '../../core/db/index.js';
-import { generateDrizzleSchema, generateLocalesTableSchema, resolveCaseStyleFns } from '../utils/schema-generator.js';
+import { SectionFactory } from '../../core/factories/index.js';
+import { CheckboxField, ColorField, DateField, DateRangeField, FileField, MapField, NumberField, numberField, PasswordField, RichTextField, SelectField, SelectMultipleField, TagsField, TextAreaField, textAreaField, TextField, textField, } from '../../core/fields/index.js';
+import { is } from '../../core/helpers/index.js';
+import { db } from '../../db/client.js';
+import { NextJsCmsTablesTable } from '../../db/schema.js';
 import { addTableKeys } from '../utils/add-table-keys.js';
+import { generateDrizzleSchema, generateLocalesTableSchema, resolveCaseStyleFns } from '../utils/schema-generator.js';
 /**
  * Returns all DB column names a field owns.
  * Most fields own a single column (field.name), but rarely some fields own two,
@@ -215,6 +214,7 @@ function resolveCreateTableOptions(sectionType) {
                 createdAt: true,
             };
         case 'destinationDb':
+        case 'selectDb':
         case 'locales':
             return {
                 createdAt: true,
@@ -231,17 +231,191 @@ function resolveCreateTableOptions(sectionType) {
             };
     }
 }
-const STORED_DEFAULT_LOCALE_KEY = 'localization.defaultLocale';
-async function readStoredDefaultLocale() {
-    const [rows] = await db.execute(sql `SELECT \`value\` FROM \`__nextjs_cms_config\` WHERE \`key\` = ${STORED_DEFAULT_LOCALE_KEY} LIMIT 1`);
+const STORED_LOCALIZATION_KEY = 'localization';
+const STORED_LOCALIZATION_VERSION = 1;
+function isStoredLocaleConfig(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        'code' in value &&
+        'label' in value &&
+        typeof value.code === 'string' &&
+        typeof value.label === 'string' &&
+        (!('rtl' in value) || typeof value.rtl === 'boolean' || value.rtl === undefined));
+}
+function isStoredLocalizationTransition(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        'type' in value &&
+        (value.type === 'enable' || value.type === 'disable') &&
+        'status' in value &&
+        value.status === 'pending' &&
+        'startedAt' in value &&
+        typeof value.startedAt === 'string' &&
+        (!('lastAttemptAt' in value) || typeof value.lastAttemptAt === 'string' || value.lastAttemptAt === undefined));
+}
+function isStoredLocalizationState(value) {
+    if (typeof value !== 'object' ||
+        value === null ||
+        !('version' in value) ||
+        value.version !== STORED_LOCALIZATION_VERSION ||
+        !('enabled' in value) ||
+        typeof value.enabled !== 'boolean') {
+        return false;
+    }
+    if (value.enabled === true) {
+        return ('defaultLocale' in value &&
+            typeof value.defaultLocale === 'string' &&
+            'locales' in value &&
+            Array.isArray(value.locales) &&
+            value.locales.every(isStoredLocaleConfig) &&
+            (!('transition' in value) ||
+                value.transition === undefined ||
+                (isStoredLocalizationTransition(value.transition) && value.transition.type === 'disable')));
+    }
+    if ('transition' in value && value.transition !== undefined) {
+        return (isStoredLocalizationTransition(value.transition) &&
+            value.transition.type === 'enable' &&
+            'defaultLocale' in value &&
+            typeof value.defaultLocale === 'string' &&
+            'locales' in value &&
+            Array.isArray(value.locales) &&
+            value.locales.every(isStoredLocaleConfig));
+    }
+    return (!('defaultLocale' in value) && !('locales' in value) && !('previous' in value) && !('lastDisabledAt' in value));
+}
+function isStoredPendingEnableLocalizationState(state) {
+    return state !== null && state !== undefined && !state.enabled && state.transition?.type === 'enable';
+}
+function isStoredDisabledLocalizationState(state) {
+    return state !== null && state !== undefined && !state.enabled && state.transition === undefined;
+}
+function parseStoredLocalizationState(value) {
+    if (!value) {
+        return null;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(value);
+    }
+    catch {
+        throw new Error(`Invalid stored localization state in '__nextjs_cms_config'.`);
+    }
+    if (!isStoredLocalizationState(parsed)) {
+        throw new Error(`Invalid stored localization state in '__nextjs_cms_config'.`);
+    }
+    return parsed;
+}
+async function readStoredLocalizationState() {
+    const [rows] = await db.execute(sql `SELECT \`value\` FROM \`__nextjs_cms_config\` WHERE \`key\` = ${STORED_LOCALIZATION_KEY} LIMIT 1`);
     const row = rows?.[0];
-    return row?.value ?? null;
+    return parseStoredLocalizationState(row?.value ?? null);
+}
+async function writeStoredLocalizationState(state) {
+    const value = JSON.stringify(state);
+    await db.execute(sql `INSERT INTO \`__nextjs_cms_config\` (\`key\`, \`value\`) VALUES (${STORED_LOCALIZATION_KEY}, ${value}) ON DUPLICATE KEY UPDATE \`value\` = ${value}`);
+}
+function buildStoredEnabledLocalizationState(localization) {
+    return {
+        version: STORED_LOCALIZATION_VERSION,
+        enabled: true,
+        defaultLocale: localization.defaultLocale,
+        locales: localization.locales.map((locale) => ({
+            code: locale.code,
+            label: locale.label,
+            rtl: locale.rtl,
+        })),
+    };
 }
-async function writeStoredDefaultLocale(value) {
-    await db.execute(sql `INSERT INTO \`__nextjs_cms_config\` (\`key\`, \`value\`) VALUES (${STORED_DEFAULT_LOCALE_KEY}, ${value}) ON DUPLICATE KEY UPDATE \`value\` = ${value}`);
+function buildStoredPendingEnableLocalizationState(targetState, transition) {
+    return {
+        version: STORED_LOCALIZATION_VERSION,
+        enabled: false,
+        defaultLocale: targetState.defaultLocale,
+        locales: targetState.locales,
+        transition,
+    };
 }
-async function deleteStoredDefaultLocale() {
-    await db.execute(sql `DELETE FROM \`__nextjs_cms_config\` WHERE \`key\` = ${STORED_DEFAULT_LOCALE_KEY}`);
+async function getRegisteredLocalizationArtifacts(existingTables) {
+    const localeColumnTables = [];
+    const localesTables = [];
+    for (const existing of existingTables) {
+        const cols = await MysqlTableChecker.getColumns(existing.name).catch(() => []);
+        if (cols.includes('locale')) {
+            localeColumnTables.push(existing.name);
+        }
+        if (existing.name.endsWith('_locales')) {
+            const stillExists = (await MysqlTableChecker.getExistingTableStructure(existing.name)) !== null;
+            if (stillExists) {
+                localesTables.push(existing.name);
+            }
+        }
+    }
+    return { localeColumnTables, localesTables };
+}
+function isExternalSelectDbField(field) {
+    return ((is(field, SelectField) || is(field, SelectMultipleField)) &&
+        field.optionsType === 'db' &&
+        field.db !== null &&
+        field.db !== undefined);
+}
+function buildSelectDbFieldConfig(name, label, type = 'text', required = true) {
+    if (type === 'number') {
+        return numberField({
+            name,
+            label,
+            required,
+            order: 0,
+        });
+    }
+    return textField({
+        name,
+        label,
+        required,
+        order: 0,
+    });
+}
+function buildLocaleFieldConfig() {
+    return textField({
+        name: 'locale',
+        label: 'Locale',
+        required: true,
+        maxLength: 10,
+        order: 0,
+    });
+}
+async function createEditorPhotosTable(localized) {
+    await db.execute(sql `
+        CREATE TABLE IF NOT EXISTS \`editor_photos\` (
+            \`photo\` VARCHAR(100) NOT NULL PRIMARY KEY,
+            \`section\` VARCHAR(100) NOT NULL,
+            \`item_id\` VARCHAR(50) NOT NULL,
+            \`field\` VARCHAR(100) NOT NULL,
+            \`meta\` LONGTEXT,
+            ${localized ? sql `\`locale\` VARCHAR(10) NOT NULL,` : sql ``}
+            \`linked\` BOOLEAN DEFAULT false,
+            \`created_at\` TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP
+        )
+    `);
+}
+async function ensureEditorPhotosLocaleColumn(defaultLocaleCode, knownColumns) {
+    let columns = knownColumns ?? (await MysqlTableChecker.getColumns('editor_photos').catch(() => []));
+    if (columns.includes('locale')) {
+        return false;
+    }
+    if (columns.length === 0) {
+        await createEditorPhotosTable(true);
+        columns = await MysqlTableChecker.getColumns('editor_photos').catch(() => []);
+        if (columns.includes('locale')) {
+            log.info(chalk.gray(`  - Created 'editor_photos' table with 'locale' column.`));
+            return true;
+        }
+        throw new Error(`Failed to create 'editor_photos' table with a 'locale' column.`);
+    }
+    await db.execute(sql `ALTER TABLE \`editor_photos\` ADD COLUMN \`locale\` VARCHAR(10) DEFAULT NULL`);
+    await db.execute(sql `UPDATE \`editor_photos\` SET \`locale\` = ${defaultLocaleCode} WHERE \`locale\` IS NULL`);
+    await db.execute(sql `ALTER TABLE \`editor_photos\` MODIFY COLUMN \`locale\` VARCHAR(10) NOT NULL`);
+    log.info(chalk.gray(`  - Added 'locale' column to 'editor_photos' and backfilled existing rows with '${defaultLocaleCode}'.`));
+    return true;
 }
 async function ensureTableRegistryEntry(tableName, sectionName) {
     await db
@@ -370,6 +544,108 @@ async function renameTable(oldName, newName) {
         console.error(`Error renaming table \`${oldName}\` to \`${newName}\`:`, error);
     }
 }
+const LOCALIZED_ASSET_DIRECTORIES = {
+    photo: ['.photos', '.thumbs'],
+    document: ['.documents'],
+    video: ['.videos'],
+};
+function getLocalizedAssetFields(fieldConfigs) {
+    return fieldConfigs
+        .filter((field) => {
+        return ('localized' in field &&
+            field.localized === true &&
+            (field.type === 'photo' || field.type === 'document' || field.type === 'video'));
+    })
+        .map((field) => ({
+        name: field.name,
+        type: field.type,
+    }));
+}
+async function unlinkIfExists(filePath) {
+    try {
+        await fs.promises.unlink(filePath);
+        return true;
+    }
+    catch (error) {
+        if (error && typeof error === 'object' && 'code' in error && error.code === 'ENOENT')
+            return false;
+        throw error;
+    }
+}
+async function deleteLocalizedAssetFilesFromLocalesTable(tableName, metadata, uploadsFolder) {
+    const result = { deletedFiles: 0, failedFiles: [] };
+    if (!metadata || metadata.fields.length === 0)
+        return result;
+    const columns = metadata.fields.map((field) => `\`${field.name}\``).join(', ');
+    const [rows] = await db.execute(sql `SELECT ${sql.raw(columns)} FROM ${sql.raw(`\`${tableName}\``)}`);
+    for (const row of rows ?? []) {
+        for (const field of metadata.fields) {
+            const fileName = row[field.name];
+            if (typeof fileName !== 'string' || fileName.trim() === '')
+                continue;
+            for (const directory of LOCALIZED_ASSET_DIRECTORIES[field.type]) {
+                const filePath = path.join(uploadsFolder, directory, metadata.sectionName, fileName);
+                try {
+                    const unlinked = await unlinkIfExists(filePath);
+                    if (unlinked)
+                        result.deletedFiles++;
+                }
+                catch (error) {
+                    // Non-ENOENT failure (e.g. EPERM, EACCES, EBUSY). Record and keep going so
+                    // remaining files still get a chance to be cleaned before the table drops.
+                    // TODO: report failed unlinks to the system_issues subsystem once it lands,
+                    // so admins can retry/resolve them from the UI instead of digging through logs.
+                    result.failedFiles.push({ filePath, error });
+                }
+            }
+        }
+    }
+    return result;
+}
+async function deleteGalleryLocaleFiles(tableName, photoFieldName, sectionName, defaultLocaleCode, uploadsFolder) {
+    const result = { deletedFiles: 0, failedFiles: [] };
+    const [rows] = await db.execute(sql `SELECT \`${sql.raw(photoFieldName)}\` AS photo FROM ${sql.raw(`\`${tableName}\``)} WHERE \`locale\` != ${defaultLocaleCode}`);
+    for (const row of rows ?? []) {
+        if (typeof row.photo !== 'string' || row.photo.trim() === '')
+            continue;
+        for (const directory of ['.photos', '.thumbs']) {
+            const filePath = path.join(uploadsFolder, directory, sectionName, row.photo);
+            try {
+                const unlinked = await unlinkIfExists(filePath);
+                if (unlinked)
+                    result.deletedFiles++;
+            }
+            catch (error) {
+                // Non-ENOENT failure (e.g. EPERM, EACCES, EBUSY). Record and keep going so
+                // remaining files still get a chance to be cleaned before the rows are deleted.
+                // TODO: report failed unlinks to the system_issues subsystem once it lands,
+                // so admins can retry/resolve them from the UI instead of digging through logs.
+                result.failedFiles.push({ filePath, error });
+            }
+        }
+    }
+    return result;
+}
+async function deleteEditorPhotosLocaleFiles(defaultLocaleCode, uploadsFolder) {
+    const result = { deletedFiles: 0, failedFiles: [] };
+    const [nondefaultRows] = await db.execute(sql `SELECT \`photo\`, \`section\` FROM \`editor_photos\` WHERE \`locale\` != ${defaultLocaleCode}`);
+    for (const row of nondefaultRows ?? []) {
+        const filePath = path.join(uploadsFolder, '.photos', row.section, row.photo);
+        try {
+            const unlinked = await unlinkIfExists(filePath);
+            if (unlinked)
+                result.deletedFiles++;
+        }
+        catch (error) {
+            // Non-ENOENT failure (e.g. EPERM, EACCES, EBUSY). Record and keep going so
+            // remaining files still get a chance to be cleaned before the rows are deleted.
+            // TODO: report failed unlinks to the system_issues subsystem once it lands,
+            // so admins can retry/resolve them from the UI instead of digging through logs.
+            result.failedFiles.push({ filePath, error });
+        }
+    }
+    return result;
+}
 async function updateTable(table, s, ctx) {
     console.log();
     console.log(chalk.blueBright(`Updating table '${table.name}' for section '${table.sectionName}'`));
@@ -428,14 +704,14 @@ async function updateTable(table, s, ctx) {
         }
     }
     /**
-     * Special handling: if this is a destinationDb table and 'locale' is being added
+     * Special handling: if this is a localization-owned table and 'locale' is being added
      * (either because localization was newly enabled OR a field was flipped to localized:true),
      * run the 3-step migration inline so rows are backfilled with defaultLocale and the
      * column ends up NOT NULL (required for the primary key to include it).
      */
     const defaultLocaleCode = ctx?.defaultLocaleCode ?? 'en';
     const localeAddIndex = fieldsToAdd.findIndex((f) => f.name === 'locale');
-    if (table.sectionType === 'destinationDb' && localeAddIndex !== -1) {
+    if ((table.sectionType === 'destinationDb' || table.sectionType === 'gallery') && localeAddIndex !== -1) {
         const [localeField] = fieldsToAdd.splice(localeAddIndex, 1);
         try {
             await db.execute(sql `ALTER TABLE \`${sql.raw(table.name)}\` ADD COLUMN \`locale\` VARCHAR(10) DEFAULT NULL`);
@@ -540,18 +816,21 @@ async function updateTable(table, s, ctx) {
         }
     }
     /**
-     * Special handling: if this is a destinationDb table and 'locale' is being removed,
-     * it means a select/tags field was changed from localized: true to localized: false.
+     * Special handling: if this is a localization-owned table and 'locale' is being removed.
+     * For destinationDb tables, this means a select/tags field was delocalized.
+     * For gallery tables, this means gallery.localized was disabled or global localization was disabled.
      * Handle this with a detailed prompt and proper data cleanup.
      */
-    if (table.sectionType === 'destinationDb' && fieldsToRemove.includes('locale')) {
+    if ((table.sectionType === 'destinationDb' || table.sectionType === 'gallery') &&
+        fieldsToRemove.includes('locale')) {
         fieldsToRemove = fieldsToRemove.filter((f) => f !== 'locale');
-        // When localization was globally disabled, we already asked upfront — auto-confirm here.
+        // When localization was globally disabled, we already asked upfront - auto-confirm here.
         let shouldDelocalize = ctx?.localizationTransition === 'disable' ? 'yes' : 'no';
         if (ctx?.localizationTransition !== 'disable') {
             s.stop();
+            const tableDescription = table.sectionType === 'gallery' ? 'gallery table' : 'junction table';
             shouldDelocalize = await select({
-                message: `The 'locale' column in junction table '${table.name}' is no longer needed (field is no longer localized). This will:\n` +
+                message: `The 'locale' column in ${tableDescription} '${table.name}' is no longer needed. This will:\n` +
                     `  1. Delete all non-default-locale rows (locale != '${defaultLocaleCode}')\n` +
                     `  2. Drop the 'locale' column from the table\n` +
                     `  3. Update the primary key to exclude 'locale'\n` +
@@ -566,6 +845,26 @@ async function updateTable(table, s, ctx) {
         }
         if (shouldDelocalize === 'yes') {
             try {
+                if (table.sectionType === 'gallery') {
+                    const photoFieldName = table.gallery?.photoNameField ?? 'photo';
+                    try {
+                        const { deletedFiles, failedFiles } = await deleteGalleryLocaleFiles(table.name, photoFieldName, table.sectionName, defaultLocaleCode, ctx?.uploadsFolder ?? '');
+                        if (deletedFiles > 0) {
+                            console.log(chalk.gray(`  - Deleted ${deletedFiles} gallery file(s) for non-default locales from '${table.sectionName}'`));
+                        }
+                        if (failedFiles.length > 0) {
+                            console.error(chalk.red(`  - Failed to delete ${failedFiles.length} gallery file(s) from '${table.sectionName}'. These files were left on disk:`));
+                            for (const { filePath, error } of failedFiles) {
+                                console.error(chalk.red(`      ${filePath}: ${String(error)}`));
+                            }
+                        }
+                    }
+                    catch (error) {
+                        // Reached only when the SELECT itself fails (DB-level error).
+                        // Per-file unlink failures are collected inside and reported above.
+                        console.error(chalk.red(`  - Error reading '${table.name}' to clean up gallery locale files:`, error));
+                    }
+                }
                 // Delete all non-default-locale rows
                 await db.execute(sql `DELETE FROM ${sql.raw(`\`${table.name}\``)} WHERE \`locale\` != ${defaultLocaleCode}`);
                 log.info(chalk.gray(`  - Deleted non-default-locale rows from '${table.name}'`));
@@ -573,6 +872,14 @@ async function updateTable(table, s, ctx) {
             catch (error) {
                 console.error(chalk.red(`  - Error deleting locale rows from '${table.name}':`, error));
             }
+            if (existingKeys?.primaryKeys.includes('locale')) {
+                alterTableSQLs.push({
+                    field: 'primary key',
+                    table: table.name,
+                    action: 'remove',
+                    sql: `DROP PRIMARY KEY`,
+                });
+            }
             alterTableSQLs.push({
                 field: 'locale',
                 table: table.name,
@@ -644,7 +951,8 @@ async function updateTable(table, s, ctx) {
     /**
      * Add the keys to the table
      */
-    const keyErrors = await addTableKeys(table, existingKeys);
+    const updatedKeys = await MysqlTableChecker.getExistingKeys(table.name);
+    const keyErrors = await addTableKeys(table, updatedKeys);
     sqlErrors += keyErrors;
     s.stop(chalk.italic.hex(`${sqlErrors > 0 ? `#FFA500` : `#fafafa`}`)(`- Table \`${table.name}\` modified successfully ${sqlErrors > 0 ? `with ${sqlErrors} error(s).` : ''}`));
 }
@@ -671,6 +979,8 @@ const main = async (s) => {
     let sections = [];
     const desiredTables = [];
     let existingTables = [];
+    const externalSelectDbTables = new Set();
+    const localesTableAssetMetadata = new Map();
     sections = await SectionFactory.getSectionsSilently();
     console.log(`Found ${sections.length} section(s) to insert: `);
     console.log(chalk.gray(sections.map((s) => s.name).join(', ')));
@@ -678,25 +988,24 @@ const main = async (s) => {
      * Let's see if the table `__nextjs_cms_tables` exists in the database.
      * If it doesn't, we'll create it using the same schema as `NextJsCmsTablesTable`.
      */
-    await db.execute(sql `
-            CREATE TABLE IF NOT EXISTS __nextjs_cms_tables (
-                name VARCHAR(100) NOT NULL PRIMARY KEY,
-                section VARCHAR(200),
-                created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP
-            )
+    await db.execute(sql `
+            CREATE TABLE IF NOT EXISTS __nextjs_cms_tables (
+                name VARCHAR(100) NOT NULL PRIMARY KEY,
+                section VARCHAR(200),
+                created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP
+            )
         `);
     /**
-     * Persistent key/value store for CMS-level state that must survive config removal —
-     * most importantly the original `localization.defaultLocale`, which we need to clean
-     * up locale-scoped rows correctly when localization is later disabled.
+     * Persistent key/value store for CMS-level state that must survive config removal.
      */
-    await db.execute(sql `
-            CREATE TABLE IF NOT EXISTS __nextjs_cms_config (
-                \`key\` VARCHAR(100) NOT NULL PRIMARY KEY,
-                \`value\` VARCHAR(255),
-                updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
-            )
+    await db.execute(sql `
+            CREATE TABLE IF NOT EXISTS __nextjs_cms_config (
+                \`key\` VARCHAR(100) NOT NULL PRIMARY KEY,
+                \`value\` LONGTEXT,
+                updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
+            )
         `);
+    await db.execute(sql `ALTER TABLE \`__nextjs_cms_config\` MODIFY COLUMN \`value\` LONGTEXT`);
     /**
      * Get the existing tables from the database
      */
@@ -712,33 +1021,54 @@ const main = async (s) => {
      */
     const RESERVED_TABLE_SUFFIX = '_locales';
     const RESERVED_COLUMN_NAME = 'locale';
-    const reservedNameErrors = [];
+    const configurationErrors = [];
+    const builtSections = sections.map((_s) => {
+        const section = _s.build();
+        section.buildFields();
+        return section;
+    });
+    const managedSectionTables = new Map(builtSections.map((section) => [section.db.table, section.name]));
     /**
      * Insert the sections into the database
      */
-    for (const _s of sections) {
-        const s = _s.build();
-        s.buildFields();
+    for (const s of builtSections) {
+        localesTableAssetMetadata.set(s.localesTableName, {
+            sectionName: s.name,
+            fields: getLocalizedAssetFields(s.fieldConfigs),
+        });
         if (s.db.table.endsWith(RESERVED_TABLE_SUFFIX)) {
-            reservedNameErrors.push(`Section '${s.name}': table name '${s.db.table}' ends with reserved suffix '${RESERVED_TABLE_SUFFIX}'.`);
+            configurationErrors.push(`Section '${s.name}': table name '${s.db.table}' ends with reserved suffix '${RESERVED_TABLE_SUFFIX}'.`);
         }
         for (const field of s.fields) {
             if (field.name === RESERVED_COLUMN_NAME) {
-                reservedNameErrors.push(`Section '${s.name}', field '${field.name}': field name '${RESERVED_COLUMN_NAME}' is reserved.`);
+                configurationErrors.push(`Section '${s.name}', field '${field.name}': field name '${RESERVED_COLUMN_NAME}' is reserved.`);
             }
             if (field.destinationDb) {
                 if (field.destinationDb.table.endsWith(RESERVED_TABLE_SUFFIX)) {
-                    reservedNameErrors.push(`Section '${s.name}', field '${field.name}': destinationDb.table '${field.destinationDb.table}' ends with reserved suffix '${RESERVED_TABLE_SUFFIX}'.`);
+                    configurationErrors.push(`Section '${s.name}', field '${field.name}': destinationDb.table '${field.destinationDb.table}' ends with reserved suffix '${RESERVED_TABLE_SUFFIX}'.`);
                 }
                 if (field.destinationDb.itemIdentifier === RESERVED_COLUMN_NAME ||
                     field.destinationDb.selectIdentifier === RESERVED_COLUMN_NAME) {
-                    reservedNameErrors.push(`Section '${s.name}', field '${field.name}': destinationDb identifier column name '${RESERVED_COLUMN_NAME}' is reserved.`);
+                    configurationErrors.push(`Section '${s.name}', field '${field.name}': destinationDb identifier column name '${RESERVED_COLUMN_NAME}' is reserved.`);
+                }
+            }
+            if (isExternalSelectDbField(field)) {
+                const ownerSectionName = managedSectionTables.get(field.db.table);
+                if (ownerSectionName) {
+                    configurationErrors.push(`Section '${s.name}', field '${field.name}': db.table '${field.db.table}' belongs to managed section '${ownerSectionName}'. Use the 'section' prop instead of 'db' so update-sections does not treat the section table as an external lookup table.`);
+                }
+                if (field.db.table.endsWith(RESERVED_TABLE_SUFFIX)) {
+                    configurationErrors.push(`Section '${s.name}', field '${field.name}': db.table '${field.db.table}' ends with reserved suffix '${RESERVED_TABLE_SUFFIX}'.`);
+                }
+                const reservedColumns = [field.db.identifier, field.db.label, field.db.orderBy].filter((column) => column === RESERVED_COLUMN_NAME);
+                if (reservedColumns.length > 0) {
+                    configurationErrors.push(`Section '${s.name}', field '${field.name}': db column name '${RESERVED_COLUMN_NAME}' is reserved.`);
                 }
             }
         }
         const galleryForValidation = await s.getGallery();
         if (galleryForValidation?.db.tableName && galleryForValidation.db.tableName.endsWith(RESERVED_TABLE_SUFFIX)) {
-            reservedNameErrors.push(`Section '${s.name}': gallery table '${galleryForValidation.db.tableName}' ends with reserved suffix '${RESERVED_TABLE_SUFFIX}'.`);
+            configurationErrors.push(`Section '${s.name}': gallery table '${galleryForValidation.db.tableName}' ends with reserved suffix '${RESERVED_TABLE_SUFFIX}'.`);
         }
         /**
          * Generate the Drizzle schema for the table
@@ -776,9 +1106,32 @@ const main = async (s) => {
          * Check for `destinationDb`
          */
         for (const field of s.fields) {
-            /**
-             * TODO: We should also check for input.db in select fields, and add the table to the desiredTables array!
-             */
+            if (isExternalSelectDbField(field) && !externalSelectDbTables.has(field.db.table)) {
+                externalSelectDbTables.add(field.db.table);
+                const identifierFieldConfig = buildSelectDbFieldConfig(field.db.identifier, 'Option Id', field.db.identifierType ?? 'text');
+                const labelFieldConfig = buildSelectDbFieldConfig(field.db.label, 'Option Label');
+                const selectDbFieldConfigs = [identifierFieldConfig, labelFieldConfig];
+                if (field.db.orderBy &&
+                    field.db.orderBy !== field.db.identifier &&
+                    field.db.orderBy !== field.db.label) {
+                    selectDbFieldConfigs.push(buildSelectDbFieldConfig(field.db.orderBy, 'Option Order', 'text', false));
+                }
+                desiredTables.push({
+                    name: field.db.table,
+                    fields: selectDbFieldConfigs.map((fieldConfig) => fieldConfig.build()),
+                    sectionName: s.name,
+                    sectionType: 'selectDb',
+                    identifier: identifierFieldConfig,
+                    primaryKey: [identifierFieldConfig],
+                });
+                const selectDbSchema = generateDrizzleSchema({
+                    name: field.db.table,
+                    fields: selectDbFieldConfigs,
+                    identifier: identifierFieldConfig,
+                }, caseStyleFns);
+                drizzleTableSchemas.push(selectDbSchema.schema);
+                selectDbSchema.drizzleImports.forEach((type) => drizzleImports.add(type));
+            }
             if (field.destinationDb) {
                 console.log('Destination DB found for input:', field.name, 'with table:', field.destinationDb.table);
                 const parentIdentifierType = s.db.identifier.type;
@@ -869,6 +1222,7 @@ const main = async (s) => {
         const gallery = await s.getGallery();
         if (gallery?.db.tableName) {
             console.log('Gallery found for section:', s.name, 'with table:', gallery.db.tableName);
+            const isLocalizedGallery = gallery.localized === true && cmsConfig.localization?.enabled === true;
             const photoField = textField({
                 name: gallery.db.photoNameField || 'photo',
                 label: 'Photo Name',
@@ -888,58 +1242,85 @@ const main = async (s) => {
                     required: true,
                     order: 0,
                 });
+            const localeFieldConfig = isLocalizedGallery ? buildLocaleFieldConfig() : undefined;
+            const galleryFields = [
+                galleryRefField.build(),
+                photoField.build(),
+                textAreaField({
+                    name: gallery.db.metaField || 'meta',
+                    label: 'Photo Information',
+                    required: false,
+                    order: 0,
+                }).build(),
+                ...(localeFieldConfig ? [localeFieldConfig.build()] : []),
+            ];
+            const galleryPrimaryKey = localeFieldConfig ? [photoField, localeFieldConfig] : [photoField];
             desiredTables.push({
                 name: gallery.db.tableName,
-                fields: [
-                    galleryRefField.build(),
-                    photoField.build(),
-                    textAreaField({
-                        name: gallery.db.metaField || 'meta',
-                        label: 'Photo Information',
-                        required: false,
-                        order: 0,
-                    }).build(),
-                ],
+                fields: galleryFields,
                 sectionName: s.name,
                 sectionType: 'gallery',
                 /**
-                 * We can use the photoField as the identifier for the gallery table
-                 * since it's unique, we can also use it as the primary key
+                 * Non-localized galleries keep the photo field as the identifier.
+                 * Localized galleries use a composite primary key: photo + locale.
                  */
-                identifier: photoField,
-                primaryKey: [photoField],
+                identifier: isLocalizedGallery ? undefined : photoField,
+                primaryKey: galleryPrimaryKey,
+                gallery: {
+                    referenceIdentifierField: gallery.db.referenceIdentifierField || 'reference_id',
+                    photoNameField: gallery.db.photoNameField || 'photo',
+                    metaField: gallery.db.metaField || 'meta',
+                    localized: isLocalizedGallery,
+                },
             });
-            const gallerySchema = generateDrizzleSchema({
-                name: gallery.db.tableName,
-                fields: [
-                    {
-                        name: gallery.db.referenceIdentifierField || 'reference_id',
-                        type: s.db.identifier.type,
-                        required: true,
-                    },
-                    {
-                        name: gallery.db.photoNameField || 'photo',
-                        type: 'text',
-                        required: true,
-                    },
-                    {
-                        name: gallery.db.metaField || 'meta',
-                        type: 'textarea',
-                        required: false,
-                    },
-                ],
-                identifier: {
+            const gallerySchemaFields = [
+                {
+                    name: gallery.db.referenceIdentifierField || 'reference_id',
+                    type: s.db.identifier.type,
+                    required: true,
+                },
+                {
                     name: gallery.db.photoNameField || 'photo',
                     type: 'text',
+                    required: true,
                 },
+                {
+                    name: gallery.db.metaField || 'meta',
+                    type: 'textarea',
+                    required: false,
+                },
+                ...(isLocalizedGallery
+                    ? [
+                        {
+                            name: 'locale',
+                            type: 'text',
+                            maxLength: 10,
+                            required: true,
+                        },
+                    ]
+                    : []),
+            ];
+            const gallerySchema = generateDrizzleSchema({
+                name: gallery.db.tableName,
+                fields: gallerySchemaFields,
+                ...(isLocalizedGallery
+                    ? {
+                        compositePrimaryKey: [{ name: gallery.db.photoNameField || 'photo' }, { name: 'locale' }],
+                    }
+                    : {
+                        identifier: {
+                            name: gallery.db.photoNameField || 'photo',
+                            type: 'text',
+                        },
+                    }),
             }, caseStyleFns);
             drizzleTableSchemas.push(gallerySchema.schema);
             gallerySchema.drizzleImports.forEach((type) => drizzleImports.add(type));
         }
         /**
-         * Check for localized fields — generate a _locales table if localization is enabled
+         * Check for localized content — generate a _locales table if localization is enabled
          */
-        if (cmsConfig.localization?.enabled && s.hasLocalizedFields) {
+        if (cmsConfig.localization?.enabled && s.hasLocalizedContent) {
             const localesTableName = s.localesTableName;
             const parentIdFieldConfig = s.db.identifier.type === 'number'
                 ? numberField({
@@ -996,13 +1377,13 @@ const main = async (s) => {
         }
     }
     /**
-     * Reject the run before any DB write if any section used a reserved name.
+     * Reject the run before schema writes if any section configuration is unsafe.
      */
-    if (reservedNameErrors.length > 0) {
-        s.stop(`update-sections aborted: ${reservedNameErrors.length} reserved-name conflict(s) detected.\n` +
-            reservedNameErrors.map((e) => `  - ${e}`).join('\n') +
-            `\n\nThe suffix '${RESERVED_TABLE_SUFFIX}' and the column name '${RESERVED_COLUMN_NAME}' are reserved for the localization system. Please rename and re-run.`);
-        throw new Error('update-sections: reserved name conflicts detected');
+    if (configurationErrors.length > 0) {
+        s.stop(`update-sections aborted: ${configurationErrors.length} configuration conflict(s) detected.\n` +
+            configurationErrors.map((e) => `  - ${e}`).join('\n') +
+            `\n\nThe suffix '${RESERVED_TABLE_SUFFIX}' and the column name '${RESERVED_COLUMN_NAME}' are reserved for the localization system. Section-managed tables must be referenced with the 'section' prop. Please update cms.config.ts and re-run.`);
+        throw new Error('update-sections: configuration conflicts detected');
     }
     /**
      * Write schema file if schema generation is enabled
@@ -1053,120 +1434,115 @@ const main = async (s) => {
     console.log(chalk.gray(tablesToRemove.map((table) => table.name).join(', ')));
     console.log(`\n`);
     intro(chalk.inverse(' update-sections '));
-    /**
-     * Detect localization transition by inspecting 'editor_photos' — the presence of its 'locale'
-     * column reflects whether localization was enabled on the previous run. Pair this with the
-     * stored `localization.defaultLocale` from `__nextjs_cms_config` so destructive cleanup uses
-     * the correct locale (the one actually used to tag existing rows), not a guess from the
-     * now-missing config.
-     */
     const localizationCurrentlyEnabled = cmsConfig.localization?.enabled === true;
-    const configDefaultLocale = cmsConfig.localization?.defaultLocale;
     const editorPhotosColumns = await MysqlTableChecker.getColumns('editor_photos').catch(() => []);
     const editorPhotosExists = editorPhotosColumns.length > 0;
     const editorPhotosHasLocale = editorPhotosColumns.includes('locale');
-    const storedDefaultLocale = await readStoredDefaultLocale();
-    // Detect residual `locale` columns on registered tables. Used to resume an interrupted
-    // disable flow: if editor_photos is already cleaned but a junction still carries the
-    // column, the upfront disable path must fire again so cleanup uses the stored locale.
-    let hasResidualLocaleColumn = false;
-    if (!localizationCurrentlyEnabled && !editorPhotosHasLocale && storedDefaultLocale) {
-        for (const existing of existingTables) {
-            const cols = await MysqlTableChecker.getColumns(existing.name).catch(() => []);
-            if (cols.includes('locale')) {
-                hasResidualLocaleColumn = true;
-                break;
-            }
-        }
+    const storedLocalizationState = await readStoredLocalizationState();
+    const storedEnabledLocalizationState = storedLocalizationState?.enabled ? storedLocalizationState : null;
+    const storedPendingEnableLocalizationState = isStoredPendingEnableLocalizationState(storedLocalizationState)
+        ? storedLocalizationState
+        : null;
+    const storedDisabledLocalizationState = isStoredDisabledLocalizationState(storedLocalizationState)
+        ? storedLocalizationState
+        : null;
+    const registeredLocalizationArtifacts = !localizationCurrentlyEnabled || storedDisabledLocalizationState
+        ? await getRegisteredLocalizationArtifacts(existingTables)
+        : { localeColumnTables: [], localesTables: [] };
+    const hasRegisteredLocalizationArtifacts = registeredLocalizationArtifacts.localeColumnTables.length > 0 ||
+        registeredLocalizationArtifacts.localesTables.length > 0;
+    const hasLocalizationArtifacts = editorPhotosHasLocale || hasRegisteredLocalizationArtifacts;
+    if (storedDisabledLocalizationState && hasLocalizationArtifacts) {
+        throw new Error(`Stored localization state says localization is disabled, but localization artifacts still exist in the database. Re-enable localization in cms.config.ts or fix the schema before re-running update-sections.`);
+    }
+    if (!localizationCurrentlyEnabled && !storedLocalizationState && hasLocalizationArtifacts) {
+        throw new Error(`Cannot disable localization safely: no stored localization state found in '__nextjs_cms_config'. Re-enable localization in cms.config.ts and re-run update-sections before disabling it again.`);
     }
     let localizationTransition = null;
-    /**
-     * Enforcement: on steady-state enabled runs, disallow silent changes to `defaultLocale`.
-     * If a mismatch is detected, abort before any destructive operation.
-     */
-    if (localizationCurrentlyEnabled && editorPhotosHasLocale) {
-        if (storedDefaultLocale && configDefaultLocale && storedDefaultLocale !== configDefaultLocale) {
-            s.stop(`Aborting. Changing 'localization.defaultLocale' is not supported (stored='${storedDefaultLocale}', config='${configDefaultLocale}'). Revert cms.config.ts and re-run update-sections.`);
+    let disableCleanupState = null;
+    let enableTargetState = null;
+    let enablePendingState = null;
+    if (localizationCurrentlyEnabled && cmsConfig.localization) {
+        const configLocalizationState = buildStoredEnabledLocalizationState(cmsConfig.localization);
+        enableTargetState = configLocalizationState;
+        const storedPendingDisableLocalizationState = storedEnabledLocalizationState?.transition?.type === 'disable' ? storedEnabledLocalizationState : null;
+        if (storedEnabledLocalizationState &&
+            storedEnabledLocalizationState.defaultLocale !== configLocalizationState.defaultLocale) {
+            s.stop(`Aborting. Changing localization defaultLocale is not supported (stored='${storedEnabledLocalizationState.defaultLocale}', config='${configLocalizationState.defaultLocale}'). Revert cms.config.ts and re-run update-sections.`);
             return;
         }
-        if (!storedDefaultLocale && configDefaultLocale) {
-            // Seed the stored value from current config — one-time backfill for installs that
-            // predate `__nextjs_cms_config`.
-            await writeStoredDefaultLocale(configDefaultLocale);
+        if (storedPendingEnableLocalizationState &&
+            storedPendingEnableLocalizationState.defaultLocale !== configLocalizationState.defaultLocale) {
+            s.stop(`Aborting. Changing localization defaultLocale while enable is pending is not supported (stored='${storedPendingEnableLocalizationState.defaultLocale}', config='${configLocalizationState.defaultLocale}'). Revert cms.config.ts and re-run update-sections.`);
+            return;
         }
-    }
-    // Resolve the locale used for cleanup SQL. For newly-disabled, stored takes precedence;
-    // for newly-enabled, config is the source of truth.
-    const defaultLocaleCode = localizationCurrentlyEnabled
-        ? (configDefaultLocale ?? storedDefaultLocale ?? 'en')
-        : (storedDefaultLocale ?? configDefaultLocale ?? 'en');
-    if (editorPhotosExists && localizationCurrentlyEnabled && !editorPhotosHasLocale) {
         /**
          * Localization is newly enabled: editor_photos lacks the locale column,
          * but the config now has localization.enabled = true. We must backfill
-         * editor_photos and any existing junction tables that carry localized data
+         * editor_photos and any existing tables that carry localized data
          * with the configured defaultLocale.
          */
-        const affectedJunctions = [];
+        const affectedLocalizedTables = [];
         for (const t of desiredTables) {
-            if (t.sectionType !== 'destinationDb')
+            if (t.sectionType !== 'destinationDb' && t.sectionType !== 'gallery')
                 continue;
             if (!t.fields.some((f) => f.name === 'locale'))
                 continue;
             const cols = await MysqlTableChecker.getColumns(t.name).catch(() => []);
             if (cols.length > 0 && !cols.includes('locale')) {
-                affectedJunctions.push(t.name);
+                affectedLocalizedTables.push(t.name);
             }
         }
-        const affectedList = ['editor_photos', ...affectedJunctions];
-        s.stop();
-        const confirm = await select({
-            message: `It looks like you enabled localization. Your existing data in these tables will be marked as defaultLocale '${defaultLocaleCode}':\n` +
-                affectedList.map((n) => `  - ${n}`).join('\n') +
-                `\n\n${chalk.redBright('WARNING:')} Existing data in these tables MUST already be in '${defaultLocaleCode}'. ` +
-                `Changing defaultLocale after this point is not supported. If your data is not in '${defaultLocaleCode}', ` +
-                `stop now and fix your cms.config.ts before re-running update-sections.\n\nProceed?`,
-            options: [
-                { value: 'yes', label: `Yes, that's correct` },
-                { value: 'no', label: 'No, stop — let me reconfigure localization in cms.config.ts' },
-            ],
-            initialValue: 'no',
-        });
-        if (confirm !== 'yes') {
-            s.stop('Aborted. Reconfigure cms.config.ts and re-run update-sections.');
-            return;
-        }
-        localizationTransition = 'enable';
-        try {
-            await db.execute(sql `ALTER TABLE \`editor_photos\` ADD COLUMN \`locale\` VARCHAR(10) DEFAULT NULL`);
-            await db.execute(sql `UPDATE \`editor_photos\` SET \`locale\` = ${defaultLocaleCode} WHERE \`locale\` IS NULL`);
-            await db.execute(sql `ALTER TABLE \`editor_photos\` MODIFY COLUMN \`locale\` VARCHAR(10) NOT NULL`);
-            // Persist the defaultLocale so future disable cleanup uses the right filter even
-            // after `localization` is stripped from cms.config.ts.
-            await writeStoredDefaultLocale(defaultLocaleCode);
-            log.info(chalk.gray(`  - Added 'locale' column to 'editor_photos' and backfilled existing rows with '${defaultLocaleCode}'.`));
-        }
-        catch (error) {
-            console.error(chalk.red(`  - Error migrating 'editor_photos' for localization enable:`, error));
+        const needsEditorPhotosMigration = editorPhotosExists && !editorPhotosHasLocale;
+        const shouldRunEnableTransition = storedPendingEnableLocalizationState ||
+            !storedEnabledLocalizationState ||
+            storedPendingDisableLocalizationState;
+        if (shouldRunEnableTransition) {
+            const affectedList = [...(needsEditorPhotosMigration ? ['editor_photos'] : []), ...affectedLocalizedTables];
+            const affectedListText = affectedList.length > 0
+                ? affectedList.map((n) => `  - ${n}`).join('\n')
+                : `  - No existing tables need a locale backfill; update-sections will verify localized tables after sync.`;
+            const isEnableRetry = storedPendingEnableLocalizationState?.transition.status === 'pending';
+            const isDisableRecovery = storedPendingDisableLocalizationState?.transition?.status === 'pending';
+            s.stop();
+            const confirm = await select({
+                message: (isDisableRecovery
+                    ? `A previous localization disable attempt did not complete, but cms.config.ts has localization enabled again. update-sections will repair localization artifacts and clear the pending disable state after verification.\n\n`
+                    : isEnableRetry
+                        ? `A previous localization enable attempt did not complete. update-sections will retry setup now.\n\n`
+                        : `It looks like you enabled localization. Your existing data in these tables will be marked as defaultLocale '${configLocalizationState.defaultLocale}':\n`) +
+                    affectedListText +
+                    `\n\n${chalk.redBright('WARNING:')} Existing data in these tables MUST already be in '${configLocalizationState.defaultLocale}'. ` +
+                    `Changing defaultLocale after this point is not supported. If your data is not in '${configLocalizationState.defaultLocale}', ` +
+                    `stop now and fix your cms.config.ts before re-running update-sections.\n\nProceed?`,
+                options: [
+                    { value: 'yes', label: `Yes, that's correct` },
+                    { value: 'no', label: 'No, stop - let me reconfigure localization in cms.config.ts' },
+                ],
+                initialValue: 'no',
+            });
+            if (confirm !== 'yes') {
+                s.stop('Aborted. Reconfigure cms.config.ts and re-run update-sections.');
+                return;
+            }
+            localizationTransition = 'enable';
+            const now = new Date().toISOString();
+            enablePendingState = buildStoredPendingEnableLocalizationState(configLocalizationState, {
+                type: 'enable',
+                status: 'pending',
+                startedAt: storedPendingEnableLocalizationState?.transition.startedAt ?? now,
+                ...(isEnableRetry || isDisableRecovery ? { lastAttemptAt: now } : {}),
+            });
+            await writeStoredLocalizationState(enablePendingState);
+            s.start();
         }
-        s.start();
+        await ensureEditorPhotosLocaleColumn(configLocalizationState.defaultLocale, editorPhotosColumns);
     }
-    else if (editorPhotosExists &&
-        !localizationCurrentlyEnabled &&
-        (editorPhotosHasLocale || hasResidualLocaleColumn)) {
+    else if (!localizationCurrentlyEnabled && storedEnabledLocalizationState) {
         /**
          * Localization is newly disabled (or a previous disable run was interrupted):
-         * editor_photos or some junction/_locales table still carries the locale column,
-         * but the config no longer has localization.enabled = true. We purge non-default rows
-         * (and their files), drop the locale column from editor_photos and junction tables,
-         * and drop _locales tables. The deletion filter uses the STORED defaultLocale (not
-         * config, which may be missing), so rows tagged with the original base locale survive
-         * regardless of current config.
+         * the stored localization state is still enabled, but cms.config.ts no longer is.
          */
-        if (!storedDefaultLocale) {
-            s.stop(`Aborting. Cannot disable localization safely: no stored defaultLocale found in '__nextjs_cms_config'. This indicates a corrupted state.`);
-            return;
-        }
         const affected = [
             { name: 'editor_photos', type: 'editor_photos' },
         ];
@@ -1180,23 +1556,27 @@ const main = async (s) => {
                 affected.push({ name: existing.name, type: 'locales' });
             }
             else {
-                affected.push({ name: existing.name, type: 'junction' });
+                affected.push({ name: existing.name, type: 'localized_table' });
             }
         }
         s.stop();
+        const isDisableRetry = storedEnabledLocalizationState.transition?.status === 'pending';
         const confirm = await select({
-            message: `It looks like you disabled localization. The 'locale' column in the tables below is no longer needed and will be dropped.\n\n` +
-                `Base locale (from '__nextjs_cms_config'): '${storedDefaultLocale}'. Rows tagged with this locale will be kept; all others will be deleted.\n\n` +
+            message: (isDisableRetry
+                ? `A previous localization disable attempt did not complete. update-sections will retry cleanup now.\n\n`
+                : `It looks like you disabled localization. The 'locale' column in the tables below is no longer needed and will be dropped.\n\n`) +
+                `Base locale (from '__nextjs_cms_config'): '${storedEnabledLocalizationState.defaultLocale}'. Rows tagged with this locale will be kept; all others will be deleted.\n\n` +
                 `This will:\n` +
-                `  1. Delete all non-base-locale rows (locale != '${storedDefaultLocale}') from editor_photos and junction tables (their files on disk will also be removed)\n` +
-                `  2. Drop the 'locale' column from editor_photos and junction tables\n` +
+                `  1. Delete all non-base-locale rows (locale != '${storedEnabledLocalizationState.defaultLocale}') from editor_photos and localized tables (their files on disk will also be removed where applicable)\n` +
+                `  2. Drop the 'locale' column from editor_photos and localized tables\n` +
                 `  3. Drop '_locales' tables entirely\n\n` +
                 `Affected tables:\n` +
                 affected.map((t) => `  - ${t.name} (${t.type})`).join('\n') +
+                `\n\n${chalk.redBright('WARNING: This action is irreversible and will permanently delete data and affected tables. It is recommended to make a backup of your data before proceeding.')}` +
                 `\n\nProceed?`,
             options: [
                 { value: 'yes', label: `Yes, that's correct` },
-                { value: 'no', label: 'No, stop — let me reconfigure localization in cms.config.ts' },
+                { value: 'no', label: 'No, stop - let me reconfigure localization in cms.config.ts' },
             ],
             initialValue: 'no',
         });
@@ -1205,22 +1585,34 @@ const main = async (s) => {
             return;
         }
         localizationTransition = 'disable';
+        const now = new Date().toISOString();
+        disableCleanupState = {
+            ...storedEnabledLocalizationState,
+            transition: {
+                type: 'disable',
+                status: 'pending',
+                startedAt: storedEnabledLocalizationState.transition?.startedAt ?? now,
+                ...(isDisableRetry ? { lastAttemptAt: now } : {}),
+            },
+        };
+        await writeStoredLocalizationState(disableCleanupState);
         if (editorPhotosHasLocale) {
             try {
                 const uploadsFolder = cmsConfig.media.upload.path;
-                const [nondefaultRows] = await db.execute(sql `SELECT \`photo\`, \`section\` FROM \`editor_photos\` WHERE \`locale\` != ${storedDefaultLocale}`);
-                const rows = nondefaultRows ?? [];
-                for (const row of rows) {
-                    try {
-                        await fs.promises.unlink(path.join(uploadsFolder, '.photos', row.section, row.photo));
-                    }
-                    catch {
-                        // ignore missing files
+                const { deletedFiles, failedFiles } = await deleteEditorPhotosLocaleFiles(storedEnabledLocalizationState.defaultLocale, uploadsFolder);
+                if (deletedFiles > 0) {
+                    console.log(chalk.gray(`  - Deleted ${deletedFiles} editor photo file(s) for non-default locales`));
+                }
+                if (failedFiles.length > 0) {
+                    // TODO: Add the failed-to-delete files to system_issues table (system_issues system not yet implemented)
+                    console.error(chalk.red(`  - Failed to delete ${failedFiles.length} editor photo file(s). These files were left on disk:`));
+                    for (const { filePath, error } of failedFiles) {
+                        console.error(chalk.red(`      ${filePath}: ${String(error)}`));
                     }
                 }
-                await db.execute(sql `DELETE FROM \`editor_photos\` WHERE \`locale\` != ${storedDefaultLocale}`);
+                await db.execute(sql `DELETE FROM \`editor_photos\` WHERE \`locale\` != ${storedEnabledLocalizationState.defaultLocale}`);
                 await db.execute(sql `ALTER TABLE \`editor_photos\` DROP COLUMN \`locale\``);
-                log.info(chalk.gray(`  - Removed ${rows.length} non-base-locale row(s) and dropped 'locale' column from 'editor_photos'.`));
+                log.info(chalk.gray(`  - Removed non-base-locale row(s) and dropped 'locale' column from 'editor_photos'.`));
             }
             catch (error) {
                 console.error(chalk.red(`  - Error migrating 'editor_photos' for localization disable:`, error));
@@ -1231,7 +1623,10 @@ const main = async (s) => {
         }
         s.start();
     }
-    const ctx = { localizationTransition, defaultLocaleCode };
+    const defaultLocaleCode = localizationCurrentlyEnabled
+        ? (cmsConfig.localization?.defaultLocale ?? storedEnabledLocalizationState?.defaultLocale ?? 'en')
+        : (storedEnabledLocalizationState?.defaultLocale ?? cmsConfig.localization?.defaultLocale ?? 'en');
+    const ctx = { localizationTransition, defaultLocaleCode, uploadsFolder: cmsConfig.media.upload.path };
     /**
      * Check if there are tables to update
      */
@@ -1342,7 +1737,7 @@ const main = async (s) => {
          * Loop through the tables to remove
          */
         for (const table of tablesToRemove) {
-            // When localization was globally disabled, auto-confirm dropping _locales tables —
+            // When localization was globally disabled, auto-confirm dropping _locales tables -
             // the upfront prompt already covered them.
             const autoDropLocales = localizationTransition === 'disable' && table.name.endsWith('_locales') ? 'yes' : null;
             let opType;
@@ -1366,6 +1761,26 @@ const main = async (s) => {
                 case 'yes':
                 case 'no':
                     if (opType === 'yes') {
+                        if (table.name.endsWith('_locales')) {
+                            try {
+                                const { deletedFiles, failedFiles } = await deleteLocalizedAssetFilesFromLocalesTable(table.name, localesTableAssetMetadata.get(table.name), cmsConfig.media.upload.path);
+                                if (deletedFiles > 0) {
+                                    console.log(chalk.gray(`  - Deleted ${deletedFiles} localized asset file(s) referenced by '${table.name}'`));
+                                }
+                                if (failedFiles.length > 0) {
+                                    // TODO: Add the failed-to-delete files to system_issues table (system_issues system not yet implemented)
+                                    console.error(chalk.red(`  - Failed to delete ${failedFiles.length} localized asset file(s) referenced by '${table.name}'. These files were left on disk:`));
+                                    for (const { filePath, error } of failedFiles) {
+                                        console.error(chalk.red(`      ${filePath}: ${String(error)}`));
+                                    }
+                                }
+                            }
+                            catch (error) {
+                                // Reached only when the SELECT itself fails (DB-level error).
+                                // Per-file unlink failures are collected inside and reported above.
+                                console.error(chalk.red(`  - Error reading '${table.name}' to clean up localized asset files:`, error));
+                            }
+                        }
                         console.log(chalk.gray(`  - Dropping table '${table.name}'`));
                         await db.execute(sql `DROP TABLE \`${sql.raw(table.name)}\``);
                     }
@@ -1388,19 +1803,45 @@ const main = async (s) => {
             }
         }
     }
-    /**
-     * Only now — after every junction update and every `_locales` drop has been attempted —
-     * is it safe to clear the stored defaultLocale. The individual cleanup steps swallow
-     * errors to keep the run going, so "transition === 'disable'" is not by itself proof the
-     * DB is clean. Post-check the actual state: editor_photos must have no `locale` column,
-     * and no registered table (junction or `_locales`) may still carry one. If any trace
-     * remains, keep the stored value so the next run can resume with the correct filter.
-     */
+    if (localizationTransition === 'enable') {
+        if (!enableTargetState || !enablePendingState) {
+            throw new Error(`Localization enable setup state was not initialized.`);
+        }
+        const missingArtifacts = [];
+        if (editorPhotosExists) {
+            const postEditorPhotosCols = await MysqlTableChecker.getColumns('editor_photos').catch(() => []);
+            if (!postEditorPhotosCols.includes('locale')) {
+                missingArtifacts.push(`editor_photos.locale`);
+            }
+        }
+        for (const table of desiredTables) {
+            if ((table.sectionType === 'destinationDb' || table.sectionType === 'gallery') &&
+                table.fields.some((field) => field.name === 'locale')) {
+                const cols = await MysqlTableChecker.getColumns(table.name).catch(() => []);
+                if (!cols.includes('locale')) {
+                    missingArtifacts.push(`${table.name}.locale`);
+                }
+            }
+            if (table.sectionType === 'locales') {
+                const stillExists = (await MysqlTableChecker.getExistingTableStructure(table.name)) !== null;
+                if (!stillExists) {
+                    missingArtifacts.push(table.name);
+                }
+            }
+        }
+        if (missingArtifacts.length > 0) {
+            throw new Error(`Localization enable setup did not complete. Missing artifacts: ${missingArtifacts.join(', ')}. The pending state was kept in '__nextjs_cms_config' and update-sections will retry on the next run.`);
+        }
+        await writeStoredLocalizationState(enableTargetState);
+    }
     if (localizationTransition === 'disable') {
+        if (!disableCleanupState) {
+            throw new Error(`Localization disable cleanup state was not initialized.`);
+        }
         const postEditorPhotosCols = await MysqlTableChecker.getColumns('editor_photos').catch(() => []);
         let fullyClean = !postEditorPhotosCols.includes('locale');
         if (!fullyClean) {
-            log.warn(chalk.yellow(`  - 'editor_photos' still has a 'locale' column after cleanup. Keeping stored defaultLocale so the next run can resume.`));
+            log.warn(chalk.yellow(`  - 'editor_photos' still has a 'locale' column after cleanup. Keeping localization disable pending so the next run can resume.`));
         }
         const postRegistered = fullyClean
             ? await db.select({ name: NextJsCmsTablesTable.tableName }).from(NextJsCmsTablesTable)
@@ -1410,26 +1851,32 @@ const main = async (s) => {
                 const cols = await MysqlTableChecker.getColumns(t.name).catch(() => []);
                 if (cols.includes('locale')) {
                     fullyClean = false;
-                    log.warn(chalk.yellow(`  - Table '${t.name}' still has a 'locale' column after cleanup. Keeping stored defaultLocale so the next run can resume.`));
+                    log.warn(chalk.yellow(`  - Table '${t.name}' still has a 'locale' column after cleanup. Keeping localization disable pending so the next run can resume.`));
                     break;
                 }
             }
         }
         if (fullyClean) {
-            // Check registered tables whose name ends with '_locales' — scoped to
+            // Check registered tables whose name ends with '_locales' - scoped to
             // __nextjs_cms_tables so unrelated tables sharing the DB are never flagged.
             const registeredLocalesTables = postRegistered.filter((t) => t.name.endsWith('_locales'));
             for (const t of registeredLocalesTables) {
                 const stillExists = (await MysqlTableChecker.getExistingTableStructure(t.name)) !== null;
                 if (stillExists) {
                     fullyClean = false;
-                    log.warn(chalk.yellow(`  - Registered '_locales' table '${t.name}' still exists after cleanup. Keeping stored defaultLocale so the next run can resume.`));
+                    log.warn(chalk.yellow(`  - Registered '_locales' table '${t.name}' still exists after cleanup. Keeping localization disable pending so the next run can resume.`));
                     break;
                 }
             }
         }
         if (fullyClean) {
-            await deleteStoredDefaultLocale();
+            await writeStoredLocalizationState({
+                version: STORED_LOCALIZATION_VERSION,
+                enabled: false,
+            });
+        }
+        else {
+            throw new Error(`Localization disable cleanup did not complete. The pending state was kept in '__nextjs_cms_config' and update-sections will retry on the next run.`);
         }
     }
 };