@dboio/cli 0.6.7 → 0.6.8

package/README.md

@@ -253,6 +253,34 @@ dbo init --domain my-domain.com --app myapp --clone
 
 When cloning an app that was already cloned locally, the CLI detects existing files and compares modification times against the server's `_LastUpdated`. You'll be prompted to overwrite, compare differences, or skip — same as `dbo pull`. Use `-y` to auto-accept all changes.
 
+#### Collision detection
+
+When multiple records would create files at the same path (e.g., a `content` record and a `media` record both named `colors.css`), the CLI detects the collision before writing any files and prompts you to choose which record to keep:
+
+```
+⚠ Collision: 2 records want to create "Bins/app/colors.css"
+? Which record should create this file?
+❯ [content] colors (UID: abc123)
+  [media] colors.css (UID: def456)
+```
+
+The rejected record is automatically staged for deletion in `.dbo/synchronize.json`. Run `dbo push` to delete it from the server.
+
+In non-interactive mode (`-y`), the first record is kept and others are auto-staged for deletion.
+
+#### Stale media cleanup
+
+During media downloads, files returning 404 (no longer exist on the server) are collected as "stale records". After all downloads complete, you'll be prompted to stage them for deletion:
+
+```
+Found 3 stale media record(s) (404 - files no longer exist on server)
+? Stage these 3 stale media records for deletion? (y/N)
+```
+
+This helps keep your app clean by removing database records for media files that have been deleted from the server.
+
+In non-interactive mode (`-y`), stale cleanup is skipped (conservative default).
+
 #### Path resolution
 
 When a content record has both `Path` and `BinID`, the CLI prompts:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dboio/cli",
-  "version": "0.6.7",
+  "version": "0.6.8",
   "description": "CLI for the DBO.io framework",
   "type": "module",
   "bin": {

package/plugins/claude/dbo/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "dbo",
-  "version": "0.6.6",
+  "version": "0.6.8",
   "description": "DBO.io CLI integration for Claude Code",
   "author": {
     "name": "DBO.io"

package/src/commands/clone.js

@@ -2,7 +2,7 @@ import { Command } from 'commander';
 import { readFile, writeFile, mkdir, access } from 'fs/promises';
 import { join, basename, extname } from 'path';
 import { DboClient } from '../lib/client.js';
-import { loadConfig, updateConfigWithApp, loadClonePlacement, saveClonePlacement, ensureGitignore, saveEntityDirPreference, loadEntityDirPreference, saveEntityContentExtractions, loadEntityContentExtractions, saveAppJsonBaseline } from '../lib/config.js';
+import { loadConfig, updateConfigWithApp, loadClonePlacement, saveClonePlacement, ensureGitignore, saveEntityDirPreference, loadEntityDirPreference, saveEntityContentExtractions, loadEntityContentExtractions, saveAppJsonBaseline, addDeleteEntry, loadCollisionResolutions, saveCollisionResolutions, loadSynchronize } from '../lib/config.js';
 import { buildBinHierarchy, resolveBinPath, createDirectories, saveStructureFile, getBinName, findBinByPath, BINS_DIR, DEFAULT_PROJECT_DIRS, ENTITY_DIR_MAP } from '../lib/structure.js';
 import { log } from '../lib/logger.js';
 import { setFileTimestamps } from '../lib/timestamps.js';
@@ -80,6 +80,342 @@ function resolvePathToBinsDir(pathValue, structure) {
   return `${BINS_DIR}/${dirPart}`;
 }
 
+/**
+ * Extract path components for content/generic records (read-only, no file writes).
+ * Replicates logic from processRecord() for collision detection.
+ */
+function resolveRecordPaths(entityName, record, structure, placementPref) {
+  let name = sanitizeFilename(String(record.Name || record.UID || 'untitled'));
+
+  // Determine extension (priority: Extension field > Name > Path)
+  let ext = '';
+  if (record.Extension) {
+    ext = String(record.Extension).toLowerCase();
+  } else {
+    if (record.Name) {
+      const extractedExt = extname(String(record.Name));
+      ext = extractedExt ? extractedExt.substring(1).toLowerCase() : '';
+    }
+    if (!ext && record.Path) {
+      const extractedExt = extname(String(record.Path));
+      ext = extractedExt ? extractedExt.substring(1).toLowerCase() : '';
+    }
+  }
+
+  // Strip double extension
+  if (ext) {
+    const extWithDot = `.${ext}`;
+    if (name.toLowerCase().endsWith(extWithDot)) {
+      name = name.substring(0, name.length - extWithDot.length);
+    }
+  }
+
+  // Resolve directory (BinID vs Path)
+  let dir = BINS_DIR;
+  const hasBinID = record.BinID && structure[record.BinID];
+  const hasPath = record.Path && typeof record.Path === 'string' && record.Path.trim();
+
+  if (hasBinID && hasPath) {
+    dir = placementPref === 'path' ? record.Path : resolveBinPath(record.BinID, structure);
+  } else if (hasBinID) {
+    dir = resolveBinPath(record.BinID, structure);
+  } else if (hasPath) {
+    dir = resolvePathToBinsDir(record.Path, structure);
+  }
+
+  // Clean directory path
+  dir = dir.replace(/^\/+|\/+$/g, '');
+  if (!dir) dir = BINS_DIR;
+  const pathExt = extname(dir);
+  if (pathExt) {
+    dir = dir.substring(0, dir.lastIndexOf('/')) || BINS_DIR;
+  }
+
+  const filename = ext ? `${name}.${ext}` : name;
+  const metaPath = join(dir, `${name}.metadata.json`);
+
+  return { dir, filename, metaPath };
+}
+
+/**
+ * Extract path components for media records.
+ * Replicates logic from processMediaEntries() for collision detection.
+ */
+function resolveMediaPaths(record, structure, placementPref) {
+  const filename = record.Filename || `${record.Name || record.UID}.${(record.Extension || 'bin').toLowerCase()}`;
+  const name = sanitizeFilename(filename.replace(/\.[^.]+$/, ''));
+  const ext = (record.Extension || 'bin').toLowerCase();
+
+  let dir = BINS_DIR;
+  const hasBinID = record.BinID && structure[record.BinID];
+  const hasFullPath = record.FullPath && typeof record.FullPath === 'string';
+
+  let fullPathDir = null;
+  if (hasFullPath) {
+    const stripped = record.FullPath.replace(/^\/+/, '');
+    const lastSlash = stripped.lastIndexOf('/');
+    fullPathDir = lastSlash >= 0 ? stripped.substring(0, lastSlash) : BINS_DIR;
+  }
+
+  if (hasBinID && fullPathDir && fullPathDir !== '.') {
+    dir = placementPref === 'path' ? fullPathDir : resolveBinPath(record.BinID, structure);
+  } else if (hasBinID) {
+    dir = resolveBinPath(record.BinID, structure);
+  } else if (fullPathDir && fullPathDir !== BINS_DIR) {
+    dir = fullPathDir;
+  }
+
+  dir = dir.replace(/^\/+|\/+$/g, '');
+  if (!dir) dir = BINS_DIR;
+
+  const finalFilename = `${name}.${ext}`;
+  const metaPath = join(dir, `${finalFilename}.metadata.json`);
+
+  return { dir, filename: finalFilename, metaPath };
+}
+
+/**
+ * Extract path components for entity-dir records.
+ * Simplified from processEntityDirEntries() for collision detection.
+ */
+function resolveEntityDirPaths(entityName, record, dirName) {
+  let name;
+  if (entityName === 'app_version' && record.Number) {
+    name = sanitizeFilename(String(record.Number));
+  } else if (record.Name) {
+    name = sanitizeFilename(String(record.Name));
+  } else {
+    name = sanitizeFilename(String(record.UID || 'untitled'));
+  }
+
+  const uid = record.UID || 'untitled';
+  const finalName = name === uid ? uid : `${name}.${uid}`;
+  const metaPath = join(dirName, `${finalName}.metadata.json`);
+  return { dir: dirName, filename: finalName, metaPath };
+}
+
+/**
+ * Build global registry of all files that will be created during clone.
+ * Returns Map<filePath, Array<{entity, record, dir, filename, metaPath}>>
+ */
+async function buildFileRegistry(appJson, structure, placementPrefs) {
+  const registry = new Map();
+
+  function addToRegistry(filePath, entity, record, dir, filename, metaPath) {
+    if (!registry.has(filePath)) {
+      registry.set(filePath, []);
+    }
+    registry.get(filePath).push({ entity, record, dir, filename, metaPath });
+  }
+
+  // Process content records
+  for (const record of (appJson.children.content || [])) {
+    const { dir, filename, metaPath } = resolveRecordPaths(
+      'content', record, structure, placementPrefs.contentPlacement
+    );
+    addToRegistry(join(dir, filename), 'content', record, dir, filename, metaPath);
+  }
+
+  // Process media records
+  for (const record of (appJson.children.media || [])) {
+    const { dir, filename, metaPath } = resolveMediaPaths(
+      record, structure, placementPrefs.mediaPlacement
+    );
+    addToRegistry(join(dir, filename), 'media', record, dir, filename, metaPath);
+  }
+
+  // Note: entity-dir records (Extensions/, Data Sources/, etc.) and generic entities
+  // are excluded from collision detection — they use UID-based naming to handle duplicates.
+  // Only content and media records in Bins/ are checked for cross-entity collisions.
+
+  return registry;
+}
+
+/**
+ * Detect collisions and prompt user to choose which record to keep.
+ * Uses stored resolutions from config and pending deletes from synchronize.json
+ * to avoid re-prompting on subsequent clones.
+ * Returns Set of UIDs to skip during processing.
+ */
+async function resolveCollisions(registry, options) {
+  const toDelete = new Set();
+  const savedResolutions = await loadCollisionResolutions();
+  const sync = await loadSynchronize();
+  const pendingDeleteUIDs = new Set((sync.delete || []).map(e => e.UID));
+  const newResolutions = { ...savedResolutions };
+
+  // Find all collisions (paths with >1 record)
+  const collisions = [];
+  for (const [filePath, records] of registry.entries()) {
+    if (records.length > 1) {
+      collisions.push({ filePath, records });
+    }
+  }
+
+  if (collisions.length === 0) return toDelete;
+
+  log.warn(`Found ${collisions.length} file path collision(s)`);
+
+  for (const { filePath, records } of collisions) {
+    // Same-entity duplicates are not cross-entity collisions — handled by UID naming
+    const entities = new Set(records.map(r => r.entity));
+    if (entities.size === 1) {
+      log.dim(`  Same-entity duplicates for "${filePath}" — will use UID naming`);
+      continue;
+    }
+
+    // Check if we have a stored resolution for this path
+    const saved = savedResolutions[filePath];
+    if (saved && records.some(r => r.record.UID === saved.keepUID)) {
+      // Auto-apply stored resolution
+      for (const r of records) {
+        if (r.record.UID !== saved.keepUID) {
+          toDelete.add(r.record.UID);
+        }
+      }
+      log.dim(`  Collision "${filePath}" → keeping ${saved.keepEntity} (saved preference)`);
+      continue;
+    }
+
+    // Check if any record in this collision is already pending deletion
+    const pendingRecord = records.find(r => pendingDeleteUIDs.has(r.record.UID));
+    if (pendingRecord) {
+      toDelete.add(pendingRecord.record.UID);
+      // Store as resolution for future clones
+      const keptRecord = records.find(r => r.record.UID !== pendingRecord.record.UID);
+      if (keptRecord) {
+        newResolutions[filePath] = { keepUID: keptRecord.record.UID, keepEntity: keptRecord.entity };
+      }
+      log.dim(`  Collision "${filePath}" → ${pendingRecord.record.UID} already staged for deletion`);
+      continue;
+    }
+
+    // Non-interactive mode: keep first, skip rest
+    if (options.yes) {
+      for (let i = 1; i < records.length; i++) {
+        toDelete.add(records[i].record.UID);
+      }
+      newResolutions[filePath] = { keepUID: records[0].record.UID, keepEntity: records[0].entity };
+      continue;
+    }
+
+    // Interactive resolution
+    const inquirer = (await import('inquirer')).default;
+
+    log.plain('');
+    log.warn(`Collision: ${records.length} records want to create "${filePath}"`);
+
+    const choices = records.map((r, idx) => {
+      const label = r.record.Name || r.record.Filename || r.record.UID;
+      return {
+        name: `[${r.entity}] ${label} (UID: ${r.record.UID})`,
+        value: idx,
+      };
+    });
+
+    const { keepIdx } = await inquirer.prompt([{
+      type: 'list',
+      name: 'keepIdx',
+      message: 'Which record should create this file?',
+      choices,
+    }]);
+
+    // Store resolution for future clones
+    newResolutions[filePath] = { keepUID: records[keepIdx].record.UID, keepEntity: records[keepIdx].entity };
+
+    // Mark others for deletion
+    for (let i = 0; i < records.length; i++) {
+      if (i !== keepIdx) {
+        toDelete.add(records[i].record.UID);
+      }
+    }
+  }
+
+  // Save resolutions for future clones
+  await saveCollisionResolutions(newResolutions);
+
+  return toDelete;
+}
+
+/**
+ * Stage deletion entries for rejected collision records.
+ * Prompts per-item for confirmation unless -y flag is set.
+ */
+async function stageCollisionDeletions(toDelete, appJson, options) {
+  if (toDelete.size === 0) return;
+
+  // Collect records to potentially stage
+  const toStage = [];
+  for (const [entityName, entries] of Object.entries(appJson.children)) {
+    if (!Array.isArray(entries)) continue;
+
+    for (const record of entries) {
+      if (!toDelete.has(record.UID)) continue;
+
+      // Find RowID
+      let rowId = record._id;
+      if (!rowId) {
+        const entityCap = entityName.charAt(0).toUpperCase() + entityName.slice(1);
+        rowId = record[`${entityCap}ID`];
+      }
+
+      if (!rowId) {
+        log.warn(`Cannot stage ${entityName} ${record.UID}: no RowID`);
+        continue;
+      }
+
+      const name = record.Name || record.Filename || record.UID;
+      toStage.push({ UID: record.UID, RowID: rowId, entity: entityName, name });
+    }
+  }
+
+  if (toStage.length === 0) return;
+
+  // Check which are already staged (skip re-prompting)
+  const sync = await loadSynchronize();
+  const alreadyStaged = new Set((sync.delete || []).map(e => e.UID));
+  const newItems = toStage.filter(item => !alreadyStaged.has(item.UID));
+
+  if (newItems.length === 0) {
+    log.dim(`  All ${toStage.length} collision rejection(s) already staged for deletion`);
+    return;
+  }
+
+  // Non-interactive mode: skip staging
+  if (options.yes) {
+    log.info(`Non-interactive mode: skipping deletion staging for ${newItems.length} rejected record(s)`);
+    return;
+  }
+
+  // Prompt per-item
+  log.info(`${newItems.length} rejected record(s) can be staged for deletion:`);
+  const inquirer = (await import('inquirer')).default;
+  let staged = 0;
+
+  for (const item of newItems) {
+    const { stage } = await inquirer.prompt([{
+      type: 'confirm',
+      name: 'stage',
+      message: `Stage [${item.entity}] "${item.name}" (UID: ${item.UID}) for deletion?`,
+      default: true,
+    }]);
+
+    if (stage) {
+      const expression = `RowID:del${item.RowID};entity:${item.entity}=true`;
+      await addDeleteEntry({ UID: item.UID, RowID: item.RowID, entity: item.entity, name: item.name, expression });
+      log.dim(`  Staged: ${item.entity} "${item.name}"`);
+      staged++;
+    } else {
+      log.dim(`  Skipped: ${item.entity} "${item.name}"`);
+    }
+  }
+
+  if (staged > 0) {
+    log.success(`${staged} record(s) staged in .dbo/synchronize.json`);
+    log.dim('  Run "dbo push" to delete from server');
+  }
+}
+
 export const cloneCommand = new Command('clone')
   .description('Clone an app from DBO.io to a local project structure')
   .argument('[source]', 'Local JSON file path (optional)')
@@ -194,20 +530,30 @@ export async function performClone(source, options = {}) {
     log.dim(`  Set ServerTimezone to ${serverTz} in .dbo/config.json`);
   }
 
-  // Step 5: Process content → files + metadata
+  // Step 4c: Detect and resolve file path collisions
+  log.info('Scanning for file path collisions...');
+  const fileRegistry = await buildFileRegistry(appJson, structure, placementPrefs);
+  const toDeleteUIDs = await resolveCollisions(fileRegistry, options);
+
+  if (toDeleteUIDs.size > 0) {
+    await stageCollisionDeletions(toDeleteUIDs, appJson, options);
+  }
+
+  // Step 5: Process content → files + metadata (skip rejected records)
   const contentRefs = await processContentEntries(
     appJson.children.content || [],
     structure,
     options,
     placementPrefs.contentPlacement,
     serverTz,
+    toDeleteUIDs,
   );
 
-  // Step 5b: Process media → download binary files + metadata
+  // Step 5b: Process media → download binary files + metadata (skip rejected records)
   let mediaRefs = [];
   const mediaEntries = appJson.children.media || [];
   if (mediaEntries.length > 0) {
-    mediaRefs = await processMediaEntries(mediaEntries, structure, options, config, appJson.ShortName, placementPrefs.mediaPlacement, serverTz);
+    mediaRefs = await processMediaEntries(mediaEntries, structure, options, config, appJson.ShortName, placementPrefs.mediaPlacement, serverTz, toDeleteUIDs);
   }
 
   // Step 6: Process other entities (not output, not bin, not content, not media)
@@ -396,7 +742,7 @@ async function updatePackageJson(appJson, config) {
  * Process content entries: write files + metadata, return reference map.
  * Returns array of { uid, metaPath } for app.json reference replacement.
  */
-async function processContentEntries(contents, structure, options, contentPlacement, serverTz) {
+async function processContentEntries(contents, structure, options, contentPlacement, serverTz, skipUIDs = new Set()) {
   if (!contents || contents.length === 0) return [];
 
   const refs = [];
@@ -410,6 +756,10 @@ async function processContentEntries(contents, structure, options, contentPlacem
   log.info(`Processing ${contents.length} content record(s)...`);
 
   for (const record of contents) {
+    if (skipUIDs.has(record.UID)) {
+      log.dim(`  Skipped ${record.Name || record.UID} (collision rejection)`);
+      continue;
+    }
     const ref = await processRecord('content', record, structure, options, usedNames, placementPreference, serverTz, bulkAction);
     if (ref) refs.push(ref);
   }
@@ -465,7 +815,6 @@ async function processEntityDirEntries(entityName, entries, options, serverTz) {
   await mkdir(dirName, { recursive: true });
 
   const refs = [];
-  const usedNames = new Map();
   const bulkAction = { value: null };
   const config = await loadConfig();
 
@@ -614,11 +963,10 @@ async function processEntityDirEntries(entityName, entries, options, serverTz) {
       name = sanitizeFilename(String(record.UID || 'untitled'));
     }
 
-    // Deduplicate filenames
-    const nameKey = `${dirName}/${name}`;
-    const count = usedNames.get(nameKey) || 0;
-    usedNames.set(nameKey, count + 1);
-    const finalName = count > 0 ? `${name}-${count + 1}` : name;
+    // Include UID in filename to ensure uniqueness (multiple records can share the same name)
+    // Convention: <name>.<UID>.metadata.json — unless name === UID, then just <UID>.metadata.json
+    const uid = record.UID || 'untitled';
+    const finalName = name === uid ? uid : `${name}.${uid}`;
 
     const metaPath = join(dirName, `${finalName}.metadata.json`);
 
@@ -755,9 +1103,12 @@ async function processEntityDirEntries(entityName, entries, options, serverTz) {
  * Process media entries: download binary files from server + create metadata.
  * Media uses Filename (not Name) and files are fetched via /api/media/{uid}.
  */
-async function processMediaEntries(mediaRecords, structure, options, config, appShortName, mediaPlacement, serverTz) {
+async function processMediaEntries(mediaRecords, structure, options, config, appShortName, mediaPlacement, serverTz, skipUIDs = new Set()) {
   if (!mediaRecords || mediaRecords.length === 0) return [];
 
+  // Track stale records (404s) for cleanup prompt
+  const staleRecords = [];
+
   // Determine if we can download (need a server connection)
   let canDownload = false;
   let client = null;
@@ -804,6 +1155,12 @@ async function processMediaEntries(mediaRecords, structure, options, config, app
 
   for (const record of mediaRecords) {
     const filename = record.Filename || `${record.Name || record.UID}.${(record.Extension || 'bin').toLowerCase()}`;
+
+    if (skipUIDs.has(record.UID)) {
+      log.dim(`  Skipped ${filename} (collision rejection)`);
+      continue;
+    }
+
     const name = sanitizeFilename(filename.replace(/\.[^.]+$/, '')); // base name without extension
     const ext = (record.Extension || 'bin').toLowerCase();
 
@@ -869,7 +1226,14 @@ async function processMediaEntries(mediaRecords, structure, options, config, app
     const fileKey = `${dir}/${name}.${ext}`;
     const fileCount = usedNames.get(fileKey) || 0;
     usedNames.set(fileKey, fileCount + 1);
-    const dedupName = fileCount > 0 ? `${name}-${fileCount + 1}` : name;
+    let dedupName;
+    if (fileCount > 0) {
+      // Duplicate name — include UID for uniqueness
+      const uid = record.UID || 'untitled';
+      dedupName = name === uid ? uid : `${name}.${uid}`;
+    } else {
+      dedupName = name;
+    }
     const finalFilename = `${dedupName}.${ext}`;
     // Metadata: use name.ext as base to avoid collisions between formats
     // e.g. KaTeX_SansSerif-Italic.woff.metadata.json vs KaTeX_SansSerif-Italic.woff2.metadata.json
@@ -954,11 +1318,26 @@ async function processMediaEntries(mediaRecords, structure, options, config, app
       log.success(`Downloaded ${filePath} (${sizeKB} KB)`);
       downloaded++;
     } catch (err) {
-      log.warn(`Failed to download ${filename}`);
-      log.dim(`  UID: ${record.UID}`);
-      log.dim(`  URL: /api/media/${record.UID}`);
-      if (record.FullPath) log.dim(`  FullPath: ${record.FullPath}`);
-      log.dim(`  Error: ${err.message}`);
+      // Check if error is 404 (stale record)
+      const is404 = /Download failed: 404/.test(err.message);
+
+      if (is404) {
+        log.warn(`Stale media: ${filename} (404 - file no longer exists)`);
+        staleRecords.push({
+          UID: record.UID,
+          RowID: record._id || record.MediaID,
+          filename,
+          fullPath: record.FullPath,
+          record,
+        });
+      } else {
+        log.warn(`Failed to download ${filename}`);
+        log.dim(`  UID: ${record.UID}`);
+        log.dim(`  URL: /api/media/${record.UID}`);
+        if (record.FullPath) log.dim(`  FullPath: ${record.FullPath}`);
+        log.dim(`  Error: ${err.message}`);
+      }
+
       failed++;
       continue; // Skip metadata if download failed
     }
@@ -987,6 +1366,41 @@ async function processMediaEntries(mediaRecords, structure, options, config, app
   }
 
   log.info(`Media: ${downloaded} downloaded, ${failed} failed`);
+
+  // Prompt for stale record cleanup
+  if (staleRecords.length > 0 && !options.yes) {
+    log.plain('');
+    log.info(`Found ${staleRecords.length} stale media record(s) (404 - files no longer exist on server)`);
+
+    const inquirer = (await import('inquirer')).default;
+    const { cleanup } = await inquirer.prompt([{
+      type: 'confirm',
+      name: 'cleanup',
+      message: `Stage these ${staleRecords.length} stale media records for deletion?`,
+      default: false, // Conservative default
+    }]);
+
+    if (cleanup) {
+      for (const stale of staleRecords) {
+        const expression = `RowID:del${stale.RowID};entity:media=true`;
+        await addDeleteEntry({
+          UID: stale.UID,
+          RowID: stale.RowID,
+          entity: 'media',
+          name: stale.filename,
+          expression,
+        });
+        log.dim(`  Staged: ${stale.filename}`);
+      }
+      log.success('Stale media records staged in .dbo/synchronize.json');
+      log.dim('  Run "dbo push" to delete from server');
+    } else {
+      log.info('Skipped stale media cleanup');
+    }
+  } else if (staleRecords.length > 0 && options.yes) {
+    log.info(`Non-interactive mode: skipping stale cleanup for ${staleRecords.length} record(s)`);
+  }
+
   return refs;
 }
 
@@ -1084,11 +1498,18 @@ async function processRecord(entityName, record, structure, options, usedNames,
 
   await mkdir(dir, { recursive: true });
 
-  // Deduplicate filenames
+  // Deduplicate filenames — use UID naming when duplicates exist
   const nameKey = `${dir}/${name}`;
   const count = usedNames.get(nameKey) || 0;
   usedNames.set(nameKey, count + 1);
-  const finalName = count > 0 ? `${name}-${count + 1}` : name;
+  let finalName;
+  if (count > 0) {
+    // Duplicate name — include UID for uniqueness
+    const uid = record.UID || 'untitled';
+    finalName = name === uid ? uid : `${name}.${uid}`;
+  } else {
+    finalName = name;
+  }
 
   // Write content file if Content column has data
   const contentValue = record.Content;
@@ -1307,8 +1728,8 @@ function decodeBase64Fields(obj) {
   // Process each property
   for (const [key, value] of Object.entries(obj)) {
     if (value && typeof value === 'object') {
-      // Check if it's a base64 encoded value
-      if (!Array.isArray(value) && value.encoding === 'base64' && typeof value.value === 'string') {
+      // Check if it's a base64 encoded value (handles both value: string and value: null)
+      if (!Array.isArray(value) && value.encoding === 'base64') {
         // Decode using existing resolveContentValue function
         obj[key] = resolveContentValue(value);
       } else {

package/src/commands/push.js

@@ -151,7 +151,6 @@ async function pushDirectory(dirPath, client, options) {
 
   // Load baseline for delta detection
   const baseline = await loadAppJsonBaseline();
-  const config = await loadConfig();
 
   if (!baseline) {
     log.warn('No .app.json baseline found — performing full push (run "dbo clone" to enable delta sync)');
@@ -205,7 +204,7 @@ async function pushDirectory(dirPath, client, options) {
     let changedColumns = null;
     if (baseline) {
       try {
-        changedColumns = await detectChangedColumns(metaPath, baseline, config);
+        changedColumns = await detectChangedColumns(metaPath, baseline);
         if (changedColumns.length === 0) {
           log.dim(`  Skipping ${basename(metaPath)} — no changes detected`);
           skipped++;

package/src/lib/config.js

@@ -286,6 +286,37 @@ export async function loadEntityContentExtractions(entityKey) {
   }
 }
 
+/**
+ * Save collision resolutions to .dbo/config.json.
+ * Maps file paths to the UID of the record the user chose to keep.
+ *
+ * @param {Object} resolutions - { "Bins/app/file.css": { keepUID: "abc", keepEntity: "content" } }
+ */
+export async function saveCollisionResolutions(resolutions) {
+  await mkdir(dboDir(), { recursive: true });
+  let existing = {};
+  try {
+    existing = JSON.parse(await readFile(configPath(), 'utf8'));
+  } catch { /* no existing config */ }
+  existing.CollisionResolutions = resolutions;
+  await writeFile(configPath(), JSON.stringify(existing, null, 2) + '\n');
+}
+
+/**
+ * Load collision resolutions from .dbo/config.json.
+ *
+ * @returns {Object} - { "Bins/app/file.css": { keepUID: "abc", keepEntity: "content" } }
+ */
+export async function loadCollisionResolutions() {
+  try {
+    const raw = await readFile(configPath(), 'utf8');
+    const config = JSON.parse(raw);
+    return config.CollisionResolutions || {};
+  } catch {
+    return {};
+  }
+}
+
 /**
  * Save user profile fields (FirstName, LastName, Email) into credentials.json.
  */

package/src/lib/delta.js

@@ -84,10 +84,9 @@ export async function compareFileContent(filePath, baselineValue) {
  *
  * @param {string} metaPath - Path to metadata.json file
  * @param {Object} baseline - The baseline JSON
- * @param {Object} config - CLI config (for resolving file paths)
  * @returns {Promise<string[]>} - Array of changed column names
  */
-export async function detectChangedColumns(metaPath, baseline, config) {
+export async function detectChangedColumns(metaPath, baseline) {
   // Load current metadata
   const metaRaw = await readFile(metaPath, 'utf8');
   const metadata = JSON.parse(metaRaw);
@@ -160,27 +159,24 @@ function shouldSkipColumn(columnName) {
 }
 
 /**
- * Check if a value is a @reference object.
+ * Check if a value is a @reference (string starting with @).
  *
  * @param {*} value - Value to check
  * @returns {boolean} - True if reference
  */
 function isReference(value) {
-  return value &&
-         typeof value === 'object' &&
-         !Array.isArray(value) &&
-         value['@reference'] !== undefined;
+  return typeof value === 'string' && value.startsWith('@');
 }
 
 /**
  * Resolve a @reference path to absolute file path.
  *
- * @param {Object} reference - Reference object with @reference property
+ * @param {string} reference - Reference string starting with @ (e.g., "@file.html")
  * @param {string} baseDir - Base directory containing metadata
  * @returns {string} - Absolute file path
  */
 function resolveReferencePath(reference, baseDir) {
-  const refPath = reference['@reference'];
+  const refPath = reference.substring(1); // Strip leading @
   return join(baseDir, refPath);
 }