@dboio/cli 0.10.1 → 0.11.1

package/src/commands/push.js

@@ -12,11 +12,13 @@ import { checkModifyKey, isModifyKeyError, handleModifyKeyError } from '../lib/m
 import { resolveTransactionKey } from '../lib/transaction-key.js';
 import { setFileTimestamps } from '../lib/timestamps.js';
 import { stripUidFromFilename, renameToUidConvention, hasUidInFilename, buildUidFilename } from '../lib/filenames.js';
-import { findMetadataFiles } from '../lib/diff.js';
+import { findMetadataFiles, findFileInProject, findByUID } from '../lib/diff.js';
 import { loadIgnore } from '../lib/ignore.js';
-import { detectChangedColumns, findBaselineEntry, detectOutputChanges, getAllUserColumns, isReference, resolveReferencePath } from '../lib/delta.js';
+import { detectChangedColumns, findBaselineEntry, detectOutputChanges, getAllUserColumns, isReference, resolveReferencePath, detectBinChanges, synthesizeBinMetadata } from '../lib/delta.js';
 import { BINS_DIR, ENTITY_DIR_NAMES, loadStructureFile, findBinByPath } from '../lib/structure.js';
 import { ensureTrashIcon } from '../lib/folder-icon.js';
+import { checkToeStepping } from '../lib/toe-stepping.js';
+import { runPendingMigrations } from '../lib/migrations.js';
 
 /**
  * Resolve an @reference file path to an absolute filesystem path.
@@ -29,6 +31,15 @@ function resolveAtReference(refFile, metaDir) {
   }
   return join(metaDir, refFile);
 }
+/**
+ * Resolve whether toe-stepping is enabled.
+ * --toe-stepping false (or '0', 'no') disables the server conflict check.
+ */
+function isToeStepping(options) {
+  const v = String(options.toeStepping ?? 'true').toLowerCase();
+  return v !== 'false' && v !== '0' && v !== 'no';
+}
+
 import { ENTITY_DEPENDENCIES } from '../lib/dependencies.js';
 
 export const pushCommand = new Command('push')
@@ -40,13 +51,16 @@ export const pushCommand = new Command('push')
   .option('--meta-only', 'Only push metadata changes, skip file content')
   .option('--content-only', 'Only push file content, skip metadata columns')
   .option('-y, --yes', 'Auto-accept all prompts (path refactoring, etc.)')
+  .option('--toe-stepping <value>', 'Check for server conflicts before push: true (default) or false', 'true')
   .option('--row-key <type>', 'Override row key type for this invocation (RowUID or RowID)')
   .option('--json', 'Output raw JSON')
   .option('--jq <expr>', 'Filter JSON response')
   .option('-v, --verbose', 'Show HTTP request details')
   .option('--domain <host>', 'Override domain')
+  .option('--no-migrate', 'Skip pending migrations for this invocation')
   .action(async (targetPath, options) => {
     try {
+      await runPendingMigrations(options);
       const client = new DboClient({ domain: options.domain, verbose: options.verbose });
 
       // ModifyKey guard — check once before any submissions
@@ -63,7 +77,62 @@ export const pushCommand = new Command('push')
       // Process pending deletions from synchronize.json
       await processPendingDeletes(client, options, modifyKey, transactionKey);
 
-      const pathStat = await stat(targetPath);
+      // ── Resolution order ──────────────────────────────────────────
+      // 1. Commas → UID list
+      // 2. stat() → file/directory (existing behaviour)
+      // 3. stat fails:
+      //    a. No extension + no path separator → search by UID
+      //    b. Otherwise → bare filename search via findFileInProject()
+
+      // 1. Comma-separated → treat as UID list
+      if (targetPath.includes(',')) {
+        const uids = targetPath.split(',').map(u => u.trim()).filter(Boolean);
+        await pushByUIDs(uids, client, options, modifyKey, transactionKey);
+        return;
+      }
+
+      // 2. Try stat (existing path)
+      let pathStat;
+      try {
+        pathStat = await stat(targetPath);
+      } catch {
+        // stat failed — try smart resolution
+        const hasPathSep = targetPath.includes('/') || targetPath.includes('\\');
+        const hasExt = extname(targetPath) !== '';
+
+        if (!hasPathSep && !hasExt) {
+          // 3a. Looks like a UID (no extension, no path separator)
+          await pushByUIDs([targetPath], client, options, modifyKey, transactionKey);
+          return;
+        }
+
+        if (!hasPathSep) {
+          // 3b. Bare filename — search project
+          const matches = await findFileInProject(targetPath);
+          if (matches.length === 1) {
+            const resolved = matches[0];
+            log.dim(`  Found: ${relative(process.cwd(), resolved)}`);
+            const resolvedStat = await stat(resolved);
+            if (resolvedStat.isDirectory()) {
+              await pushDirectory(resolved, client, options, modifyKey, transactionKey);
+            } else {
+              await pushSingleFile(resolved, client, options, modifyKey, transactionKey);
+            }
+            return;
+          } else if (matches.length > 1) {
+            log.error(`Multiple matches for "${targetPath}":`);
+            for (const m of matches) {
+              log.plain(`  ${relative(process.cwd(), m)}`);
+            }
+            log.info('Please specify the full path.');
+            process.exit(1);
+          }
+        }
+
+        // No match found
+        log.error(`Path not found: "${targetPath}"`);
+        process.exit(1);
+      }
 
       if (pathStat.isDirectory()) {
         await pushDirectory(targetPath, client, options, modifyKey, transactionKey);
@@ -214,9 +283,15 @@ async function moveWillDeleteToTrash(entry) {
  */
 async function pushSingleFile(filePath, client, options, modifyKey = null, transactionKey = 'RowUID') {
   // Find the metadata file
-  const dir = dirname(filePath);
-  const base = basename(filePath, extname(filePath));
-  const metaPath = join(dir, `${base}.metadata.json`);
+  let metaPath;
+  if (filePath.endsWith('.metadata.json')) {
+    // User passed the metadata file directly — use it as-is
+    metaPath = filePath;
+  } else {
+    const dir = dirname(filePath);
+    const base = basename(filePath, extname(filePath));
+    metaPath = join(dir, `${base}.metadata.json`);
+  }
 
   let meta;
   try {
@@ -226,6 +301,16 @@ async function pushSingleFile(filePath, client, options, modifyKey = null, trans
     process.exit(1);
   }
 
+  // Toe-stepping check for single-file push
+  if (isToeStepping(options) && meta.UID) {
+    const baseline = await loadAppJsonBaseline();
+    if (baseline) {
+      const appConfig = await loadAppConfig();
+      const proceed = await checkToeStepping([{ meta, metaPath }], client, baseline, options, appConfig?.AppShortName);
+      if (!proceed) return;
+    }
+  }
+
   await pushFromMetadata(meta, metaPath, client, options, null, modifyKey, transactionKey);
 }
 
@@ -298,13 +383,6 @@ async function pushDirectory(dirPath, client, options, modifyKey = null, transac
   const ig = await loadIgnore();
   const metaFiles = await findMetadataFiles(dirPath, ig);
 
-  if (metaFiles.length === 0) {
-    log.warn(`No .metadata.json files found in "${dirPath}".`);
-    return;
-  }
-
-  log.info(`Found ${metaFiles.length} record(s) to push`);
-
   // Load baseline for delta detection
   const baseline = await loadAppJsonBaseline();
 
@@ -398,17 +476,51 @@ async function pushDirectory(dirPath, client, options, modifyKey = null, transac
     toPush.push({ meta, metaPath, changedColumns, isNew: isNewRecord });
   }
 
-  if (toPush.length === 0 && outputCompoundFiles.length === 0) {
-    log.info('No changes to push');
+  // Toe-stepping: check for server-side conflicts before submitting
+  if (isToeStepping(options) && baseline && toPush.length > 0) {
+    const toCheck = toPush.filter(item => !item.isNew);
+    if (toCheck.length > 0) {
+      const appConfig = await loadAppConfig();
+      const proceed = await checkToeStepping(toCheck, client, baseline, options, appConfig?.AppShortName);
+      if (!proceed) return;
+    }
+  }
+
+  // ── Bin entity push: check if directory maps to a bin ──────────────
+  const binPushItems = [];
+  try {
+    const structure = await loadStructureFile();
+    const relDir = relative(process.cwd(), dirPath).replace(/\\/g, '/');
+    const binEntry = findBinByPath(relDir, structure);
+    if (binEntry && binEntry.uid && baseline) {
+      const changedBinCols = detectBinChanges(binEntry, baseline);
+      if (changedBinCols.length > 0) {
+        const appConfig = await loadAppConfig();
+        const binMeta = synthesizeBinMetadata(binEntry, appConfig.AppID);
+        binPushItems.push({ meta: binMeta, binEntry, changedColumns: changedBinCols });
+        log.info(`Bin "${binEntry.name}" has ${changedBinCols.length} changed column(s): ${changedBinCols.join(', ')}`);
+      }
+    }
+  } catch { /* structure file missing or bin lookup failed — skip */ }
+
+  if (toPush.length === 0 && outputCompoundFiles.length === 0 && binPushItems.length === 0) {
+    if (metaFiles.length === 0) {
+      log.warn(`No .metadata.json files found in "${dirPath}".`);
+    } else {
+      log.info('No changes to push');
+    }
     return;
   }
 
+  log.info(`Found ${metaFiles.length} record(s) to push`);
+
   // Pre-flight ticket validation (only if no --ticket flag)
-  const totalRecords = toPush.length + outputCompoundFiles.length;
+  const totalRecords = toPush.length + outputCompoundFiles.length + binPushItems.length;
   if (!options.ticket && totalRecords > 0) {
     const recordSummary = [
       ...toPush.map(r => basename(r.metaPath, '.metadata.json')),
       ...outputCompoundFiles.map(r => basename(r.metaPath, '.json')),
+      ...binPushItems.map(r => `bin:${r.meta.Name}`),
     ].join(', ');
     const ticketCheck = await checkStoredTicket(options, `${totalRecords} record(s): ${recordSummary}`);
     if (ticketCheck.cancel) {
@@ -497,6 +609,28 @@ async function pushDirectory(dirPath, client, options, modifyKey = null, transac
     }
   }
 
+  // Process bin entity changes
+  for (const binItem of binPushItems) {
+    try {
+      // Synthesize a temporary metadata file path for pushFromMetadata
+      // (bin records have no .metadata.json — we pass the data inline)
+      const success = await pushBinEntity(binItem.meta, binItem.changedColumns, client, options, modifyKey, transactionKey);
+      if (success) {
+        succeeded++;
+      } else {
+        failed++;
+      }
+    } catch (err) {
+      log.error(`Failed bin push: ${binItem.meta.Name} — ${err.message}`);
+      failed++;
+    }
+  }
+
+  // Clear server cache so subsequent GETs (diff, pull, toe-stepping) return fresh data
+  if (successfulPushes.length > 0) {
+    await client.voidCache();
+  }
+
   // Update baseline after successful pushes
   if (baseline && successfulPushes.length > 0) {
     await updateBaselineAfterPush(baseline, successfulPushes);
@@ -505,6 +639,140 @@ async function pushDirectory(dirPath, client, options, modifyKey = null, transac
   log.info(`Push complete: ${succeeded} succeeded, ${failed} failed, ${skipped} skipped`);
 }
 
+/**
+ * Push a bin entity record (synthesized metadata, no .metadata.json file).
+ * Uses pushFromMetadata with a temporary in-memory metadata path.
+ */
+async function pushBinEntity(binMeta, changedColumns, client, options, modifyKey = null, transactionKey = 'RowUID') {
+  const entity = binMeta._entity;
+  const uid = binMeta.UID;
+  const id = binMeta._id;
+
+  // Determine row key
+  let rowKeyPrefix, rowKeyValue;
+  if (uid) {
+    rowKeyPrefix = 'RowUID';
+    rowKeyValue = uid;
+  } else if (id) {
+    rowKeyPrefix = 'RowID';
+    rowKeyValue = id;
+  } else {
+    log.warn(`Bin "${binMeta.Name}" has no UID or ID — skipping`);
+    return false;
+  }
+
+  const dataExprs = [];
+  for (const col of changedColumns) {
+    const value = binMeta[col];
+    const strValue = value !== null && value !== undefined ? String(value) : '';
+    dataExprs.push(`${rowKeyPrefix}:${rowKeyValue};column:${entity}.${col}=${strValue}`);
+  }
+
+  if (dataExprs.length === 0) {
+    log.warn(`Nothing to push for bin "${binMeta.Name}"`);
+    return false;
+  }
+
+  log.info(`Pushing bin "${binMeta.Name}" (${entity}:${rowKeyValue}) — ${dataExprs.length} changed field(s)`);
+
+  const extraParams = { '_confirm': options.confirm || 'true' };
+  if (options.ticket) extraParams['_OverrideTicketID'] = options.ticket;
+  if (modifyKey) extraParams['_modify_key'] = modifyKey;
+  const cachedUser = getSessionUserOverride();
+  if (cachedUser) extraParams['_OverrideUserID'] = cachedUser;
+
+  const body = await buildInputBody(dataExprs, extraParams);
+  const result = await client.postUrlEncoded('/api/input/submit', body);
+
+  formatResponse(result, { json: options.json, jq: options.jq, verbose: options.verbose });
+
+  if (!result.successful) {
+    return false;
+  }
+
+  log.success(`  Pushed bin "${binMeta.Name}"`);
+  return true;
+}
+
+/**
+ * Push records by UID(s). Searches metadata files and structure.json bins.
+ */
+async function pushByUIDs(uids, client, options, modifyKey = null, transactionKey = 'RowUID') {
+  const matches = await findByUID(uids);
+
+  if (matches.length === 0) {
+    log.error(`No records found for UID(s): ${uids.join(', ')}`);
+    process.exit(1);
+  }
+
+  // Report unmatched UIDs
+  const foundUids = new Set(matches.map(m => m.uid));
+  for (const uid of uids) {
+    if (!foundUids.has(uid)) {
+      log.warn(`UID not found: ${uid}`);
+    }
+  }
+
+  const baseline = await loadAppJsonBaseline();
+
+  // Toe-stepping check for UID-targeted push
+  if (isToeStepping(options) && baseline) {
+    const toCheck = [];
+    for (const match of matches) {
+      if (match.metaPath && match.meta) {
+        toCheck.push({ meta: match.meta, metaPath: match.metaPath });
+      }
+    }
+    if (toCheck.length > 0) {
+      const appConfig = await loadAppConfig();
+      const proceed = await checkToeStepping(toCheck, client, baseline, options, appConfig?.AppShortName);
+      if (!proceed) return;
+    }
+  }
+
+  let succeeded = 0;
+  let failed = 0;
+
+  for (const match of matches) {
+    if (match.metaPath) {
+      // Regular record — push via pushSingleFile path
+      try {
+        const success = await pushSingleFile(match.metaPath, client, options, modifyKey, transactionKey);
+        if (success !== false) succeeded++;
+        else failed++;
+      } catch (err) {
+        log.error(`Failed to push ${match.uid}: ${err.message}`);
+        failed++;
+      }
+    } else if (match.binEntry) {
+      // Bin entity — detect changes and push
+      try {
+        const changedCols = baseline
+          ? detectBinChanges(match.binEntry, baseline)
+          : ['Name', 'Path', 'ParentBinID'];
+
+        if (changedCols.length === 0) {
+          log.dim(`  Bin "${match.binEntry.name}" — no changes detected`);
+          continue;
+        }
+
+        const appConfig = await loadAppConfig();
+        const binMeta = synthesizeBinMetadata(match.binEntry, appConfig.AppID);
+        const success = await pushBinEntity(binMeta, changedCols, client, options, modifyKey, transactionKey);
+        if (success) succeeded++;
+        else failed++;
+      } catch (err) {
+        log.error(`Failed to push bin ${match.uid}: ${err.message}`);
+        failed++;
+      }
+    }
+  }
+
+  if (matches.length > 1) {
+    log.info(`Push complete: ${succeeded} succeeded, ${failed} failed`);
+  }
+}
+
 /**
  * Submit a new record (add) from metadata that has no UID yet.
  * Builds RowID:add1 expressions, submits, then renames files with the returned ~UID.
@@ -675,40 +943,37 @@ async function pushFromMetadata(meta, metaPath, client, options, changedColumns
   const contentCols = new Set(meta._contentColumns || []);
   const metaDir = dirname(metaPath);
 
-  // Determine the row key prefix and value based on the preset
+  // Determine the row key. TransactionKeyPreset only applies when the record
+  // carries a UID column (core assets). Data records without a UID always use
+  // RowID directly — no preset, no fallback warning.
   let rowKeyPrefix, rowKeyValue;
-  if (transactionKey === 'RowID') {
-    if (id) {
+  const hasUid = uid != null && uid !== '';
+
+  if (hasUid) {
+    // Core asset: honour the TransactionKeyPreset
+    if (transactionKey === 'RowID') {
+      if (!id) throw new Error(`No _id found in ${basename(metaPath)} — required when TransactionKeyPreset is RowID`);
       rowKeyPrefix = 'RowID';
       rowKeyValue = id;
     } else {
-      log.warn(`  ⚠  Preset is RowID but no _id found in ${basename(metaPath)} — falling back to RowUID`);
+      // RowUID (default)
       rowKeyPrefix = 'RowUID';
       rowKeyValue = uid;
     }
   } else {
-    if (uid) {
-      rowKeyPrefix = 'RowUID';
-      rowKeyValue = uid;
-    } else if (id) {
-      log.warn(`  ⚠  Preset is RowUID but no UID found in ${basename(metaPath)} — falling back to RowID`);
-      rowKeyPrefix = 'RowID';
-      rowKeyValue = id;
-    }
-  }
-
-  if (!rowKeyValue) {
-    throw new Error(`No UID or _id found in ${metaPath}`);
+    // Data record: no UID column — always RowID
+    if (!id) throw new Error(`No UID or _id found in ${metaPath}`);
+    rowKeyPrefix = 'RowID';
+    rowKeyValue = id;
   }
   if (!entity) {
     throw new Error(`No _entity found in ${metaPath}`);
   }
 
-  // Detect path mismatch (only for content, media, output, bin entities —
-  // entity-dir types use structural directories unrelated to server Path)
-  if (meta.Path) {
-    await checkPathMismatch(meta, metaPath, entity, options);
-  }
+  // Path mismatch check disabled: the metadata Path column reflects the
+  // server-side path and must not be overwritten by local directory structure.
+  // Local bin/lib directory placement is an organizational choice independent
+  // of the server Path value.
 
   const dataExprs = [];
   let metaUpdated = false;
@@ -720,7 +985,10 @@ async function pushFromMetadata(meta, metaPath, client, options, changedColumns
     if (shouldSkipColumn(key)) continue;
     if (key === 'UID') continue; // UID is the identifier, not a column to update
     if (key === 'children') continue; // Output hierarchy structural field, not a server column
-    if (value === null || value === undefined) continue;
+
+    // Skip null/undefined values UNLESS delta detected them as changed
+    // (user explicitly set a column to null to clear it on server)
+    if ((value === null || value === undefined) && !(columnsToProcess && columnsToProcess.has(key))) continue;
 
     // Delta sync: skip columns not in changedColumns
     if (columnsToProcess && !columnsToProcess.has(key)) continue;
@@ -732,7 +1000,8 @@ async function pushFromMetadata(meta, metaPath, client, options, changedColumns
     // --content-only: skip non-content columns
     if (options.contentOnly && !isContentCol) continue;
 
-    const strValue = String(value);
+    // Null values that passed delta check → send as empty string to clear on server
+    const strValue = (value === null || value === undefined) ? '' : String(value);
 
     if (strValue.startsWith('@')) {
       // @filename reference — resolve to actual file path
@@ -1188,9 +1457,9 @@ async function _submitOutputEntity(entity, physicalEntity, changedColumns, metaD
     if (col === 'UID' || col === 'children') continue;
 
     const val = entity[col];
-    if (val === null || val === undefined) continue;
 
-    const strValue = String(val);
+    // Null values in changedColumns → send empty string to clear on server
+    const strValue = (val === null || val === undefined) ? '' : String(val);
     if (isReference(strValue)) {
       const refPath = resolveReferencePath(strValue, metaDir);
       dataExprs.push(`${rowKeyPrefix}:${rowKeyValue};column:${physicalEntity}.${col}@${refPath}`);
@@ -1281,7 +1550,13 @@ async function updateBaselineAfterPush(baseline, successfulPushes) {
 
     for (const col of columnsToUpdate) {
       const value = meta[col];
-      if (value === null || value === undefined) continue;
+
+      // Null/undefined values: store null in baseline (field was cleared)
+      if (value === null || value === undefined) {
+        baselineEntry[col] = null;
+        modified = true;
+        continue;
+      }
 
       const strValue = String(value);
 

package/src/commands/rm.js

@@ -6,6 +6,7 @@ import { formatError } from '../lib/formatter.js';
 import { addDeleteEntry, removeAppJsonReference } from '../lib/config.js';
 import { findMetadataFiles } from '../lib/diff.js';
 import { loadStructureFile, findBinByPath, findChildBins, BINS_DIR } from '../lib/structure.js';
+import { runPendingMigrations } from '../lib/migrations.js';
 
 export const rmCommand = new Command('rm')
   .description('Remove a file or directory locally and stage server deletions for the next dbo push')
@@ -13,8 +14,10 @@ export const rmCommand = new Command('rm')
   .option('-f, --force', 'Skip confirmation prompts')
   .option('--keep-local', 'Only stage server deletion, do not delete local files')
   .option('--hard', 'Immediately delete local files (no Trash; legacy behavior)')
+  .option('--no-migrate', 'Skip pending migrations for this invocation')
   .action(async (targetPath, options) => {
     try {
+      await runPendingMigrations(options);
       const pathStat = await stat(targetPath).catch(() => null);
       if (!pathStat) {
         log.error(`Path not found: "${targetPath}"`);

package/src/commands/status.js

@@ -5,10 +5,12 @@ import { access } from 'fs/promises';
 import { join } from 'path';
 import { homedir } from 'os';
 import { log } from '../lib/logger.js';
+import { runPendingMigrations, countPendingMigrations } from '../lib/migrations.js';
 
 export const statusCommand = new Command('status')
   .description('Show current DBO CLI configuration and session status')
-  .action(async () => {
+  .option('--no-migrate', 'Skip pending migrations for this invocation')
+  .action(async (options) => {
     try {
       const initialized = await isInitialized();
       const config = await loadConfig();
@@ -40,6 +42,15 @@ export const statusCommand = new Command('status')
       const transactionKeyPreset = await loadTransactionKeyPreset();
       log.label('Transaction Key', transactionKeyPreset || '(not set — defaults to RowUID)');
 
+      // Run pending migrations (no-op if --no-migrate)
+      await runPendingMigrations(options);
+
+      // Report pending count (after running, so completed ones are excluded)
+      const pending = await countPendingMigrations();
+      if (pending > 0) {
+        log.label('Pending migrations', `${pending} (will run on next command; use --no-migrate to skip)`);
+      }
+
       // Display plugin status
       const scopes = await getAllPluginScopes();
       const pluginNames = Object.keys(scopes);

package/src/commands/sync.js

@@ -3,11 +3,14 @@ import { log } from '../lib/logger.js';
 import { loadConfig, loadAppConfig, saveAppJsonBaseline } from '../lib/config.js';
 import { DboClient } from '../lib/client.js';
 import { decodeBase64Fields } from './clone.js';
+import { runPendingMigrations } from '../lib/migrations.js';
 
 export const syncCommand = new Command('sync')
   .description('Synchronise local state with the server')
   .option('--baseline', 'Re-fetch server state and update .dbo/.app_baseline.json (does not modify local files)')
+  .option('--no-migrate', 'Skip pending migrations for this invocation')
   .action(async (options) => {
+    await runPendingMigrations(options);
     if (!options.baseline) {
       log.warn('No sync mode specified. Use --baseline to reset the baseline file.');
       process.exit(1);

package/src/lib/client.js

@@ -123,6 +123,16 @@ export class DboClient {
     return this._parseResponse(response);
   }
 
+  /**
+   * Clear the server-side cache. Must be called after POST transactions so that
+   * subsequent GET requests (diff, pull, toe-stepping) return fresh data.
+   */
+  async voidCache() {
+    try {
+      await this.request('/?voidcache=true');
+    } catch { /* best-effort — don't block on failure */ }
+  }
+
   /**
    * Fetch a URL and return the raw response as a Buffer (for binary downloads).
    */

package/src/lib/config.js

@@ -525,6 +525,37 @@ export async function getAllPluginScopes() {
   return result;
 }
 
+// ─── Migration tracking (config.local.json._completedMigrations) ──────────
+
+/**
+ * Load the list of completed migration IDs from .dbo/config.local.json.
+ * Returns an empty array if the file does not exist or the key is absent.
+ * @returns {Promise<string[]>}
+ */
+export async function loadCompletedMigrations() {
+  try {
+    const local = await loadLocalConfig();
+    const ids = local._completedMigrations;
+    return Array.isArray(ids) ? ids : [];
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Append a migration ID to .dbo/config.local.json._completedMigrations.
+ * Deduplicates: if the ID is already present, no-op.
+ * @param {string} id - Three-digit migration ID, e.g. '001'
+ */
+export async function saveCompletedMigration(id) {
+  const local = await loadLocalConfig();
+  const existing = new Set(Array.isArray(local._completedMigrations) ? local._completedMigrations : []);
+  if (existing.has(id)) return; // already recorded — idempotent
+  existing.add(id);
+  local._completedMigrations = [...existing].sort();
+  await saveLocalConfig(local);
+}
+
 // ─── Output Hierarchy Filename Preferences ────────────────────────────────
 
 /**