@dboio/cli 0.10.1 → 0.11.1

package/src/commands/clone.js

@@ -1,17 +1,18 @@
 import { Command } from 'commander';
-import { readFile, writeFile, mkdir, access, readdir, rename } from 'fs/promises';
+import { readFile, writeFile, appendFile, mkdir, access, readdir, rename } from 'fs/promises';
 import { join, basename, extname, dirname } from 'path';
 import { fileURLToPath } from 'url';
 import { DboClient } from '../lib/client.js';
 import { loadConfig, updateConfigWithApp, loadClonePlacement, saveClonePlacement, ensureGitignore, saveEntityDirPreference, loadEntityDirPreference, saveEntityContentExtractions, loadEntityContentExtractions, saveAppJsonBaseline, addDeleteEntry, loadCollisionResolutions, saveCollisionResolutions, loadSynchronize, saveSynchronize, saveAppModifyKey, loadTransactionKeyPreset, saveTransactionKeyPreset, loadOutputFilenamePreference, saveOutputFilenamePreference, saveCloneSource, loadCloneSource, saveDescriptorFilenamePreference, loadDescriptorFilenamePreference, saveDescriptorContentExtractions, loadDescriptorContentExtractions, saveExtensionDocumentationMDPlacement, loadExtensionDocumentationMDPlacement } from '../lib/config.js';
-import { buildBinHierarchy, resolveBinPath, createDirectories, saveStructureFile, getBinName, findBinByPath, BINS_DIR, DEFAULT_PROJECT_DIRS, ENTITY_DIR_NAMES, OUTPUT_ENTITY_MAP, OUTPUT_HIERARCHY_ENTITIES, EXTENSION_DESCRIPTORS_DIR, EXTENSION_UNSUPPORTED_DIR, DOCUMENTATION_DIR, buildDescriptorMapping, saveDescriptorMapping, loadDescriptorMapping, resolveExtensionSubDir } from '../lib/structure.js';
+import { buildBinHierarchy, resolveBinPath, createDirectories, saveStructureFile, findBinByPath, BINS_DIR, DEFAULT_PROJECT_DIRS, SCAFFOLD_DIRS, ENTITY_DIR_NAMES, OUTPUT_ENTITY_MAP, OUTPUT_HIERARCHY_ENTITIES, EXTENSION_DESCRIPTORS_DIR, EXTENSION_UNSUPPORTED_DIR, DOCUMENTATION_DIR, buildDescriptorMapping, saveDescriptorMapping, loadDescriptorMapping, resolveExtensionSubDir, resolveEntityDirPath } from '../lib/structure.js';
 import { log } from '../lib/logger.js';
 import { buildUidFilename, detectLegacyDotUid } from '../lib/filenames.js';
 import { setFileTimestamps, parseServerDate } from '../lib/timestamps.js';
-import { getLocalSyncTime, isServerNewer, hasLocalModifications, promptChangeDetection, inlineDiffAndMerge, isDiffable } from '../lib/diff.js';
+import { getLocalSyncTime, isServerNewer, hasLocalModifications, promptChangeDetection, inlineDiffAndMerge, isDiffable, loadBaselineForComparison, resetBaselineCache } from '../lib/diff.js';
 import { checkDomainChange } from '../lib/domain-guard.js';
 import { applyTrashIcon, ensureTrashIcon } from '../lib/folder-icon.js';
 import { loadMetadataTemplates, saveMetadataTemplates, getTemplateCols, setTemplateCols, buildTemplateFromCloneRecord } from '../lib/metadata-templates.js';
+import { runPendingMigrations } from '../lib/migrations.js';
 
 /**
  * Resolve a column value that may be base64-encoded.
@@ -154,28 +155,15 @@ export function resolveRecordPaths(entityName, record, structure, placementPref)
  * Extract path components for media records.
  * Replicates logic from processMediaEntries() for collision detection.
  */
-export function resolveMediaPaths(record, structure, placementPref) {
+export function resolveMediaPaths(record, structure) {
   const filename = record.Filename || `${record.Name || record.UID}.${(record.Extension || 'bin').toLowerCase()}`;
   const name = sanitizeFilename(filename.replace(/\.[^.]+$/, ''));
   const ext = (record.Extension || 'bin').toLowerCase();
 
+  // Always place media by BinID; fall back to bins/ root
   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) {
+  if (record.BinID && structure[record.BinID]) {
     dir = resolveBinPath(record.BinID, structure);
-  } else if (fullPathDir && fullPathDir !== BINS_DIR) {
-    dir = fullPathDir;
   }
 
   dir = dir.replace(/^\/+|\/+$/g, '');
@@ -233,9 +221,7 @@ async function buildFileRegistry(appJson, structure, placementPrefs) {
 
   // Process media records
   for (const record of (appJson.children.media || [])) {
-    const { dir, filename, metaPath } = resolveMediaPaths(
-      record, structure, placementPrefs.mediaPlacement
-    );
+    const { dir, filename, metaPath } = resolveMediaPaths(record, structure);
     addToRegistry(join(dir, filename), 'media', record, dir, filename, metaPath);
   }
 
@@ -443,8 +429,10 @@ export const cloneCommand = new Command('clone')
   .option('-y, --yes', 'Auto-accept all prompts')
   .option('--media-placement <placement>', 'Set media placement: fullpath or binpath (default: bin)')
   .option('-v, --verbose', 'Show HTTP request details')
+  .option('--no-migrate', 'Skip pending migrations for this invocation')
   .action(async (source, options) => {
     try {
+      await runPendingMigrations(options);
       await performClone(source, options);
     } catch (err) {
       log.error(err.message);
@@ -743,27 +731,12 @@ export async function performClone(source, options = {}) {
     }
   }
 
-  // Prompt for TransactionKeyPreset if not already set (skip in pull mode)
+  // Auto-set TransactionKeyPreset to RowUID if not already set (skip in pull mode)
   if (!options.pullMode) {
     const existingPreset = await loadTransactionKeyPreset();
     if (!existingPreset) {
-      if (options.yes || !process.stdin.isTTY) {
-        await saveTransactionKeyPreset('RowUID');
-        log.dim('  TransactionKeyPreset: RowUID (default)');
-      } else {
-        const inquirer = (await import('inquirer')).default;
-        const { preset } = await inquirer.prompt([{
-          type: 'list',
-          name: 'preset',
-          message: 'Which row key should the CLI use when building input expressions?',
-          choices: [
-            { name: 'RowUID (recommended — stable across domains)', value: 'RowUID' },
-            { name: 'RowID (numeric IDs)', value: 'RowID' },
-          ],
-        }]);
-        await saveTransactionKeyPreset(preset);
-        log.dim(`  TransactionKeyPreset: ${preset}`);
-      }
+      await saveTransactionKeyPreset('RowUID');
+      log.dim('  TransactionKeyPreset: RowUID');
     }
   }
 
@@ -777,59 +750,32 @@ export async function performClone(source, options = {}) {
   const structure = buildBinHierarchy(bins, appJson.AppID);
 
   if (!options.pullMode) {
-    for (const dir of DEFAULT_PROJECT_DIRS) {
+    for (const dir of SCAFFOLD_DIRS) {
       await mkdir(dir, { recursive: true });
     }
 
-    // Create media sub-directories for this app:
-    //   media/<ShortName>/app/  — app-level media assets
-    //   media/<ShortName>/user/ — user-uploaded media
-    const appShortName = appJson.ShortName;
-    const mediaSubs = [];
-    if (appShortName) {
-      const mediaDirs = [
-        `media/${appShortName}/app`,
-        `media/${appShortName}/user`,
-      ];
-      for (const sub of mediaDirs) {
-        await mkdir(sub, { recursive: true });
-        mediaSubs.push(sub);
-      }
-    }
-
     // Best-effort: apply trash icon
     await applyTrashIcon(join(process.cwd(), 'trash'));
 
     const createdDirs = await createDirectories(structure);
     await saveStructureFile(structure);
 
-    const totalDirs = DEFAULT_PROJECT_DIRS.length + mediaSubs.length + createdDirs.length;
+    const totalDirs = SCAFFOLD_DIRS.length + createdDirs.length;
     log.success(`Created ${totalDirs} director${totalDirs === 1 ? 'y' : 'ies'}`);
-    for (const d of DEFAULT_PROJECT_DIRS) log.dim(`  ${d}/`);
-    for (const d of mediaSubs) log.dim(`  ${d}/`);
+    for (const d of SCAFFOLD_DIRS) log.dim(`  ${d}/`);
     for (const d of createdDirs) log.dim(`  ${d}/`);
 
-    // Warn about legacy mixed-case directories from pre-0.9.1
-    const LEGACY_DIR_MAP = {
-      'Bins':        'bins',
-      'Automations': 'automation',
-      'App Versions': 'app_version',
-      'Documentation': 'docs',
-      'Sites':       'site',
-      'Extensions':  'extension',
-      'Data Sources': 'data_source',
-      'Groups':      'group',
-      'Integrations': 'integration',
-      'Trash':       'trash',
-      'Src':         'src',
-    };
-    for (const [oldName, newName] of Object.entries(LEGACY_DIR_MAP)) {
+    // Warn about legacy root-level entity directories
+    const LEGACY_ENTITY_DIRS = [
+      'bins', 'extension', 'automation', 'app_version', 'entity',
+      'entity_column', 'entity_column_value', 'integration', 'security',
+      'security_column', 'data_source', 'group', 'site', 'redirect',
+    ];
+    for (const oldName of LEGACY_ENTITY_DIRS) {
       try {
         await access(join(process.cwd(), oldName));
-        log.warn(`Legacy directory detected: "${oldName}/" — rename it to "${newName}/" for the new convention.`);
-      } catch {
-        // does not exist — no warning needed
-      }
+        log.warn(`Legacy directory detected: "${oldName}/" — run \`dbo\` to trigger automatic migration to lib/${oldName}/`);
+      } catch { /* does not exist — no warning needed */ }
     }
   } else {
     // Pull mode: reuse existing structure, just ensure dirs exist for new bins
@@ -838,7 +784,7 @@ export async function performClone(source, options = {}) {
   }
 
   // Step 4b: Determine placement preferences (from config or prompt)
-  const placementPrefs = await resolvePlacementPreferences(appJson, options);
+  const placementPrefs = await resolvePlacementPreferences();
 
   // Ensure ServerTimezone is set in config (default: America/Los_Angeles for DBO.io)
   let serverTz = config.ServerTimezone;
@@ -867,6 +813,10 @@ export async function performClone(source, options = {}) {
     }
   }
 
+  // Pre-load previous baseline for fast _LastUpdated string comparison in isServerNewer.
+  // This prevents false-positive "server newer" prompts caused by timezone conversion drift.
+  await loadBaselineForComparison();
+
   // Step 5: Process content → files + metadata (skip rejected records)
   let contentRefs = [];
   if (!entityFilter || entityFilter.has('content')) {
@@ -890,7 +840,7 @@ export async function performClone(source, options = {}) {
   if (!entityFilter || entityFilter.has('media')) {
     const mediaEntries = appJson.children.media || [];
     if (mediaEntries.length > 0) {
-      mediaRefs = await processMediaEntries(mediaEntries, structure, options, config, appJson.ShortName, placementPrefs.mediaPlacement, serverTz, toDeleteUIDs);
+      mediaRefs = await processMediaEntries(mediaEntries, structure, options, config, appJson.ShortName, serverTz, toDeleteUIDs);
     }
   }
 
@@ -921,15 +871,9 @@ export async function performClone(source, options = {}) {
       if (refs.length > 0) {
         otherRefs[entityName] = refs;
       }
-    } else if (ENTITY_DIR_NAMES.has(entityName)) {
-      // Entity types with project directories — process into their directory
-      const refs = await processEntityDirEntries(entityName, entries, options, serverTz);
-      if (refs.length > 0) {
-        otherRefs[entityName] = refs;
-      }
     } else {
-      // Other entity types — process into Bins/ (requires BinID)
-      const refs = await processGenericEntries(entityName, entries, structure, options, placementPrefs.contentPlacement, serverTz);
+      // All remaining entities → project directory named after entity
+      const refs = await processEntityDirEntries(entityName, entries, options, serverTz);
       if (refs.length > 0) {
         otherRefs[entityName] = refs;
       }
@@ -947,6 +891,7 @@ export async function performClone(source, options = {}) {
   // Step 8: Create .dbo/.app_baseline.json baseline for delta tracking (skip in entity-filter mode to avoid overwriting)
   if (!entityFilter) {
     await saveBaselineFile(appJson);
+    resetBaselineCache(); // invalidate so next operation reloads the fresh baseline
   }
 
   log.plain('');
@@ -982,87 +927,20 @@ export function resolveEntityFilter(entityArg) {
 }
 
 /**
- * Resolve placement preferences from config or prompt the user.
- * Returns { contentPlacement, mediaPlacement } where values are 'path'|'bin'|'ask'|null
+ * Resolve placement preferences from config.
+ * Content defaults to 'bin'. Media always uses BinID (no placement preference).
+ * Returns { contentPlacement } where value is 'path'|'bin'.
  */
-async function resolvePlacementPreferences(appJson, options) {
-  // Load saved preferences from config
+async function resolvePlacementPreferences() {
   const saved = await loadClonePlacement();
-  let contentPlacement = saved.contentPlacement;
-  let mediaPlacement = saved.mediaPlacement;
-
-  // Pull mode: use saved preferences or default to 'bin', no prompts
-  if (options.pullMode) {
-    return {
-      contentPlacement: contentPlacement || 'bin',
-      mediaPlacement: mediaPlacement || 'bin',
-    };
-  }
-
-  // --media-placement flag takes precedence over saved config
-  if (options.mediaPlacement) {
-    mediaPlacement = options.mediaPlacement === 'fullpath' ? 'fullpath' : 'bin';
-    await saveClonePlacement({ contentPlacement: contentPlacement || 'bin', mediaPlacement });
-    log.dim(`  MediaPlacement set to "${mediaPlacement}" via flag`);
-  }
-
-  const hasContent = (appJson.children.content || []).length > 0;
-
-  // If -y flag, default to bin placement (no prompts)
-  if (options.yes) {
-    return {
-      contentPlacement: contentPlacement || 'bin',
-      mediaPlacement: mediaPlacement || 'bin',
-    };
-  }
-
-  // If both are already set in config, use them
-  if (contentPlacement && mediaPlacement) {
-    return { contentPlacement, mediaPlacement };
-  }
-
-  const inquirer = (await import('inquirer')).default;
-  const prompts = [];
-
-  // Only prompt for contentPlacement — media placement is NOT prompted interactively
-  if (!contentPlacement && hasContent) {
-    prompts.push({
-      type: 'list',
-      name: 'contentPlacement',
-      message: 'How should content files be placed?',
-      choices: [
-        { name: 'Save all in BinID directory', value: 'bin' },
-        { name: 'Save all in their specified Path directory', value: 'path' },
-        { name: 'Ask for every file that has both', value: 'ask' },
-      ],
-    });
-  }
-
-  // Media placement: no interactive prompt — default to 'bin'
-  if (!mediaPlacement) {
-    mediaPlacement = 'bin';
-  }
-
-  if (prompts.length > 0) {
-    const answers = await inquirer.prompt(prompts);
-    contentPlacement = contentPlacement || answers.contentPlacement || 'bin';
-  }
-
-  // Resolve defaults for any still-unset values
-  contentPlacement = contentPlacement || 'bin';
-  mediaPlacement = mediaPlacement || 'bin';
+  const contentPlacement = saved.contentPlacement || 'bin';
 
-  // Always persist resolved values — not just when prompts were shown.
-  // This ensures defaults are saved even when the app has no content/media yet,
-  // so subsequent clones that do have records skip the prompts.
-  if (!saved.contentPlacement || !saved.mediaPlacement) {
-    await saveClonePlacement({ contentPlacement, mediaPlacement });
-    if (prompts.length > 0) {
-      log.dim('  Saved placement preferences to .dbo/config.json');
-    }
+  // Persist default if not yet saved
+  if (!saved.contentPlacement) {
+    await saveClonePlacement({ contentPlacement });
   }
 
-  return { contentPlacement, mediaPlacement };
+  return { contentPlacement };
 }
 
 /**
@@ -1157,7 +1035,31 @@ async function fetchAppFromServer(appShortName, options, config) {
   }
 
   if (!appRecord) {
+    // Empty payload can mean either a genuinely missing app OR an expired session
+    // (some servers return 200 + empty data instead of 401 when not authenticated).
+    // Offer re-login as an option so the user doesn't have to guess.
     spinner.fail(`No app found with ShortName "${appShortName}"`);
+
+    if (process.stdin.isTTY) {
+      log.warn('If your session has expired, re-logging in may fix this.');
+      const inquirer = (await import('inquirer')).default;
+      const { action } = await inquirer.prompt([{
+        type: 'list',
+        name: 'action',
+        message: 'How would you like to proceed?',
+        choices: [
+          { name: 'Re-login and retry (session may have expired)', value: 'relogin' },
+          { name: 'Abort', value: 'abort' },
+        ],
+      }]);
+      if (action === 'relogin') {
+        const { performLogin } = await import('./login.js');
+        await performLogin(options.domain || config.domain);
+        log.info('Retrying app fetch...');
+        return fetchAppFromServer(appShortName, options, config);
+      }
+    }
+
     throw new Error(`No app found with ShortName "${appShortName}"`);
   }
 
@@ -1257,39 +1159,7 @@ async function processContentEntries(contents, structure, options, contentPlacem
 }
 
 /**
- * Process non-content, non-output entities.
- * Only handles entries with a BinID.
- */
-async function processGenericEntries(entityName, entries, structure, options, contentPlacement, serverTz) {
-  if (!entries || entries.length === 0) return [];
-
-  const refs = [];
-  const usedNames = new Map();
-  const placementPreference = {
-    value: (contentPlacement === 'path' || contentPlacement === 'bin') ? contentPlacement : null,
-  };
-  const bulkAction = { value: null };
-  let processed = 0;
-
-  for (const record of entries) {
-    if (!record.BinID) continue; // Skip entries without BinID
-
-    const ref = await processRecord(entityName, record, structure, options, usedNames, placementPreference, serverTz, bulkAction);
-    if (ref) {
-      refs.push(ref);
-      processed++;
-    }
-  }
-
-  if (processed > 0) {
-    log.info(`Processed ${processed} ${entityName} record(s)`);
-  }
-
-  return refs;
-}
-
-/**
- * Process entity-dir entries: entities that map to DEFAULT_PROJECT_DIRS.
+ * Process entity-dir entries: entities that get their own project directory.
  * These don't require a BinID — they go directly into their project directory
  * (e.g., Extensions/, Data Sources/, etc.)
  *
@@ -1298,8 +1168,7 @@ async function processGenericEntries(entityName, entries, structure, options, co
 async function processEntityDirEntries(entityName, entries, options, serverTz) {
   if (!entries || entries.length === 0) return [];
 
-  const dirName = entityName;
-  if (!ENTITY_DIR_NAMES.has(entityName)) return [];
+  const dirName = resolveEntityDirPath(entityName);
 
   await mkdir(dirName, { recursive: true });
 
@@ -1509,7 +1378,7 @@ async function processEntityDirEntries(entityName, entries, options, serverTz) {
       if (bulkAction.value !== 'overwrite_all') {
         const configWithTz = { ...config, ServerTimezone: serverTz };
         const localSyncTime = await getLocalSyncTime(metaPath);
-        const serverNewer = isServerNewer(localSyncTime, record._LastUpdated, configWithTz);
+        const serverNewer = isServerNewer(localSyncTime, record._LastUpdated, configWithTz, 'content', record.UID);
         const serverDate = parseServerDate(record._LastUpdated, serverTz);
 
         if (serverNewer) {
@@ -1986,7 +1855,7 @@ async function processExtensionEntries(entries, structure, options, serverTz) {
         if (bulkAction.value !== 'overwrite_all') {
           const cfgWithTz = { ...config, ServerTimezone: serverTz };
           const localSyncTime = await getLocalSyncTime(metaPath);
-          const serverNewer = isServerNewer(localSyncTime, record._LastUpdated, cfgWithTz);
+          const serverNewer = isServerNewer(localSyncTime, record._LastUpdated, cfgWithTz, 'extension', record.UID);
           const serverDate = parseServerDate(record._LastUpdated, serverTz);
 
           if (serverNewer) {
@@ -2090,7 +1959,7 @@ async function processExtensionEntries(entries, structure, 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, skipUIDs = new Set()) {
+async function processMediaEntries(mediaRecords, structure, options, config, appShortName, serverTz, skipUIDs = new Set()) {
   if (!mediaRecords || mediaRecords.length === 0) return [];
 
   // Track stale records (404s) for cleanup prompt
@@ -2104,7 +1973,7 @@ async function processMediaEntries(mediaRecords, structure, options, config, app
   for (const record of mediaRecords) {
     if (skipUIDs.has(record.UID)) continue;
 
-    const { metaPath: scanMetaPath } = resolveMediaPaths(record, structure, mediaPlacement === 'fullpath' ? 'path' : mediaPlacement === 'bin' ? 'bin' : null);
+    const { metaPath: scanMetaPath } = resolveMediaPaths(record, structure);
     const scanExists = await fileExists(scanMetaPath);
 
     if (!scanExists) {
@@ -2117,7 +1986,7 @@ async function processMediaEntries(mediaRecords, structure, options, config, app
       // Existing file — check if server is newer
       const configWithTz = { ...config, ServerTimezone: serverTz };
       const localSyncTime = await getLocalSyncTime(scanMetaPath);
-      const serverNewer = isServerNewer(localSyncTime, record._LastUpdated, configWithTz);
+      const serverNewer = isServerNewer(localSyncTime, record._LastUpdated, configWithTz, 'media', record.UID);
       if (serverNewer) {
         needsDownload.push(record);
       } else {
@@ -2166,10 +2035,6 @@ async function processMediaEntries(mediaRecords, structure, options, config, app
 
   const refs = [];
   const usedNames = new Map();
-  // Map config values: 'fullpath' → 'path' (used internally), 'bin' → 'bin', 'ask' → null
-  const placementPreference = {
-    value: mediaPlacement === 'fullpath' ? 'path' : mediaPlacement === 'bin' ? 'bin' : null,
-  };
   const mediaBulkAction = { value: null };
   let downloaded = 0;
   let failed = 0;
@@ -2187,57 +2052,10 @@ async function processMediaEntries(mediaRecords, structure, options, config, app
     const name = sanitizeFilename(filename.replace(/\.[^.]+$/, '')); // base name without extension
     const ext = (record.Extension || 'bin').toLowerCase();
 
-    // Determine target directory (default: bins/ for items without explicit placement)
+    // Always place media by BinID; fall back to bins/ root when BinID is missing
     let dir = BINS_DIR;
-    const hasBinID = record.BinID && structure[record.BinID];
-    const hasFullPath = record.FullPath && typeof record.FullPath === 'string';
-
-    // Parse directory from FullPath: strip leading / and remove filename
-    // FullPath like /media/operator/app/assets/gfx/logo.png → media/operator/app/assets/gfx/
-    // These are valid project-relative paths (media/, dir/ are real directories)
-    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 !== '.' && !options.yes) {
-      if (placementPreference.value) {
-        dir = placementPreference.value === 'path'
-          ? fullPathDir
-          : resolveBinPath(record.BinID, structure);
-      } else {
-        const binPath = resolveBinPath(record.BinID, structure);
-        const binName = getBinName(record.BinID, structure);
-        const inquirer = (await import('inquirer')).default;
-
-        const { placement } = await inquirer.prompt([{
-          type: 'list',
-          name: 'placement',
-          message: `Where do you want me to place ${filename}?`,
-          choices: [
-            { name: `Into the FullPath of ${fullPathDir}`, value: 'path' },
-            { name: `Into the BinID of ${record.BinID} (${binName} → ${binPath})`, value: 'bin' },
-            { name: `Place this and all further files by FullPath`, value: 'all_path' },
-            { name: `Place this and all further files by BinID`, value: 'all_bin' },
-          ],
-        }]);
-
-        if (placement === 'all_path') {
-          placementPreference.value = 'path';
-          dir = fullPathDir;
-        } else if (placement === 'all_bin') {
-          placementPreference.value = 'bin';
-          dir = binPath;
-        } else {
-          dir = placement === 'path' ? fullPathDir : binPath;
-        }
-      }
-    } else if (hasBinID) {
+    if (record.BinID && structure[record.BinID]) {
       dir = resolveBinPath(record.BinID, structure);
-    } else if (fullPathDir && fullPathDir !== BINS_DIR) {
-      dir = fullPathDir;
     }
 
     dir = dir.replace(/^\/+|\/+$/g, '');
@@ -2270,7 +2088,7 @@ async function processMediaEntries(mediaRecords, structure, options, config, app
         // with how setFileTimestamps set the mtime — the two must use the same timezone.
         const configWithTz = { ...config, ServerTimezone: serverTz };
         const localSyncTime = await getLocalSyncTime(metaPath);
-        const serverNewer = isServerNewer(localSyncTime, record._LastUpdated, configWithTz);
+        const serverNewer = isServerNewer(localSyncTime, record._LastUpdated, configWithTz, 'media', record.UID);
         const serverDate = parseServerDate(record._LastUpdated, serverTz);
         const diffable = isDiffable(ext);
 
@@ -2342,9 +2160,25 @@ async function processMediaEntries(mediaRecords, structure, options, config, app
       }
     }
 
-    // Download the file
+    // Download the file with fallback chain: /media/ → /dir/ → /api/media/
+    //   1. FullPath directly (e.g. /media/todoes/App/assets/file.ttf)
+    //   2. /dir/ route (FullPath with /media/ prefix stripped → appShortName/bins/filename)
+    //   3. /api/media/{uid} (UID-based endpoint as last resort)
     try {
-      const buffer = await client.getBuffer(`/api/media/${record.UID}`);
+      const urls = buildMediaDownloadUrls(record);
+      let buffer;
+      let usedUrl;
+      for (const url of urls) {
+        try {
+          buffer = await client.getBuffer(url);
+          usedUrl = url;
+          break;
+        } catch (urlErr) {
+          // If this is the last URL in the chain, rethrow
+          if (url === urls[urls.length - 1]) throw urlErr;
+          // Otherwise try next URL
+        }
+      }
       await writeFile(filePath, buffer);
       const sizeKB = (buffer.length / 1024).toFixed(1);
       log.success(`Downloaded ${filePath} (${sizeKB} KB)`);
@@ -2365,11 +2199,23 @@ async function processMediaEntries(mediaRecords, structure, options, config, app
       } 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}`);
       }
 
+      // Append to .dbo/errors.log
+      await appendErrorLog({
+        timestamp: new Date().toISOString(),
+        command: 'clone',
+        entity: 'media',
+        action: 'download',
+        uid: record.UID,
+        rowId: record._id || record.MediaID,
+        filename,
+        fullPath: record.FullPath || null,
+        error: err.message,
+      });
+
       failed++;
       continue; // Skip metadata if download failed
     }
@@ -2402,38 +2248,22 @@ async function processMediaEntries(mediaRecords, structure, options, config, app
 
   log.info(`Media: ${downloaded} downloaded, ${failed} failed, ${upToDateRefs.length} up to date`);
 
-  // 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');
+  // Auto-stage stale records for deletion (404 — files no longer exist on server)
+  if (staleRecords.length > 0) {
+    log.info(`Staging ${staleRecords.length} stale media record(s) for deletion (404)`);
+    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}`);
     }
-  } else if (staleRecords.length > 0 && options.yes) {
-    log.info(`Non-interactive mode: skipping stale cleanup for ${staleRecords.length} record(s)`);
+    log.success('Stale media records staged in .dbo/synchronize.json');
+    log.dim('  Run "dbo push" to delete from server');
   }
 
   return [...upToDateRefs, ...refs];
@@ -2443,7 +2273,7 @@ async function processMediaEntries(mediaRecords, structure, options, config, app
  * Process a single record: determine directory, write content file + metadata.
  * Returns { uid, metaPath } or null.
  */
-async function processRecord(entityName, record, structure, options, usedNames, placementPreference, serverTz, bulkAction = { value: null }) {
+async function processRecord(entityName, record, structure, options, usedNames, _placementPreference, serverTz, bulkAction = { value: null }) {
   let name = sanitizeFilename(String(record.Name || record.UID || 'untitled'));
 
   // Determine file extension (priority: Extension field > Name field > Path field > empty)
@@ -2464,7 +2294,40 @@ async function processRecord(entityName, record, structure, options, usedNames,
       ext = extractedExt ? extractedExt.substring(1).toLowerCase() : '';
     }
   }
-  // If still no extension, ext remains '' (no extension)
+  // If still no extension, check existing local metadata for a previously chosen extension.
+  // On re-clone, the Content @reference in the local metadata already has the extension
+  // the user picked on the first clone (e.g. "@CurrentTask~uid.html" → "html").
+  if (!ext && record.UID) {
+    try {
+      const uid = String(record.UID);
+      const sanitized = sanitizeFilename(String(record.Name || uid || 'untitled'));
+      const probe = buildUidFilename(sanitized, uid);
+      // Resolve the directory the same way the main code does below
+      let probeDir = BINS_DIR;
+      if (record.BinID && structure[record.BinID]) {
+        probeDir = resolveBinPath(record.BinID, structure);
+      } else if (record.Path && typeof record.Path === 'string' && record.Path.trim()) {
+        probeDir = resolvePathToBinsDir(record.Path, structure);
+      }
+      probeDir = probeDir.replace(/^\/+|\/+$/g, '') || BINS_DIR;
+      if (extname(probeDir)) probeDir = probeDir.substring(0, probeDir.lastIndexOf('/')) || BINS_DIR;
+
+      const probeMeta = join(probeDir, `${probe}.metadata.json`);
+      const raw = await readFile(probeMeta, 'utf8');
+      const localMeta = JSON.parse(raw);
+      // Extract extension from Content @reference (e.g. "@Name~uid.html")
+      for (const col of (localMeta._contentColumns || ['Content'])) {
+        const ref = localMeta[col];
+        if (typeof ref === 'string' && ref.startsWith('@')) {
+          const refExt = extname(ref);
+          if (refExt) {
+            ext = refExt.substring(1).toLowerCase();
+            break;
+          }
+        }
+      }
+    } catch { /* no existing metadata — will prompt below */ }
+  }
 
   // If no extension determined and Content column has data, prompt user to choose one
   if (!ext && !options.yes && record.Content) {
@@ -2514,41 +2377,8 @@ async function processRecord(entityName, record, structure, options, usedNames,
   const hasBinID = record.BinID && structure[record.BinID];
   const hasPath = record.Path && typeof record.Path === 'string' && record.Path.trim();
 
-  if (hasBinID && hasPath && !options.yes) {
-    // Check for a saved "all" preference
-    if (placementPreference.value) {
-      dir = placementPreference.value === 'path'
-        ? record.Path
-        : resolveBinPath(record.BinID, structure);
-    } else {
-      // Both BinID and Path — prompt user
-      const binPath = resolveBinPath(record.BinID, structure);
-      const binName = getBinName(record.BinID, structure);
-      const inquirer = (await import('inquirer')).default;
-
-      const { placement } = await inquirer.prompt([{
-        type: 'list',
-        name: 'placement',
-        message: `Where do you want me to place ${name}.${ext}?`,
-        choices: [
-          { name: `Into the Path of ${record.Path}`, value: 'path' },
-          { name: `Into the BinID of ${record.BinID} (${binName} → ${binPath})`, value: 'bin' },
-          { name: `Place this and all further files by Path`, value: 'all_path' },
-          { name: `Place this and all further files by BinID`, value: 'all_bin' },
-        ],
-      }]);
-
-      if (placement === 'all_path') {
-        placementPreference.value = 'path';
-        dir = record.Path;
-      } else if (placement === 'all_bin') {
-        placementPreference.value = 'bin';
-        dir = binPath;
-      } else {
-        dir = placement === 'path' ? record.Path : binPath;
-      }
-    }
-  } else if (hasBinID) {
+  if (hasBinID) {
+    // Always place by BinID when available
     dir = resolveBinPath(record.BinID, structure);
   } else if (hasPath) {
     // BinID is null — resolve Path into a Bins/ location
@@ -2600,7 +2430,7 @@ async function processRecord(entityName, record, structure, options, usedNames,
       const config = await loadConfig();
       const configWithTz = { ...config, ServerTimezone: serverTz };
       const localSyncTime = await getLocalSyncTime(metaPath);
-      const serverNewer = isServerNewer(localSyncTime, record._LastUpdated, configWithTz);
+      const serverNewer = isServerNewer(localSyncTime, record._LastUpdated, configWithTz, entityName, record.UID);
       const serverDate = parseServerDate(record._LastUpdated, serverTz);
 
       if (serverNewer) {
@@ -2929,12 +2759,12 @@ async function resolveOutputFilenameColumns(appJson, options) {
 
 /**
  * Build a filename for an output hierarchy entity.
- * Uses dot-separated hierarchical naming: _output~<name>~<uid>.column~<name>~<uid>.json
+ * Uses dot-separated hierarchical naming: <name>~<uid>.column~<name>~<uid>.json
  *
  * @param {string} entityType - Documentation name: 'output', 'column', 'join', 'filter'
  * @param {Object} node - The entity record
  * @param {string} filenameCol - Column to use for the name portion
- * @param {string[]} parentChain - Array of parent segments: ['_output~name~uid', 'join~name~uid', ...]
+ * @param {string[]} parentChain - Array of parent segments: ['name~uid', 'join~name~uid', ...]
  * @returns {string} - Base filename without extension
  */
 export function buildOutputFilename(entityType, node, filenameCol, parentChain = []) {
@@ -2942,18 +2772,14 @@ export function buildOutputFilename(entityType, node, filenameCol, parentChain =
   const rawName = node[filenameCol];
   const name = rawName ? sanitizeFilename(String(rawName)) : '';
 
-  // Build this entity's segment: <type>~<name>~<uid>
-  // If filenameCol IS the UID, don't double-append it
+  // Build this entity's segment
   let segment;
-  if (!name || name === uid) {
-    segment = `${entityType}~${uid}`;
-  } else {
-    segment = `${entityType}~${name}~${uid}`;
-  }
-
-  // Root output gets _ prefix
   if (entityType === 'output') {
-    segment = `_${segment}`;
+    // Root output: use Name~UID directly (no type prefix)
+    segment = (!name || name === uid) ? uid : `${name}~${uid}`;
+  } else {
+    // Child entities: keep type prefix (column~, join~, filter~)
+    segment = (!name || name === uid) ? `${entityType}~${uid}` : `${entityType}~${name}~${uid}`;
   }
 
   const allSegments = [...parentChain, segment];
@@ -2968,8 +2794,8 @@ const INLINE_DOC_KEYS = ['column', 'join', 'filter'];
 
 /**
  * Build the companion file stem for a child entity within a root output file.
- * e.g. root stem "_output~Sales~abc", entity "output_value", uid "col1"
- *   → "_output~Sales~abc.column~col1"
+ * e.g. root stem "Sales~abc", entity "output_value", uid "col1"
+ *   → "Sales~abc.column~col1"
  *
  * @param {string} rootStem - Root output file stem (no extension)
  * @param {string} physicalEntity - Physical entity name ('output_value', etc.)
@@ -3042,7 +2868,7 @@ async function extractCustomSqlIfNeeded(entityObj, companionStem, outputDir, ser
  *
  * @param {Object} parentObj - The entity object to populate (mutated in place)
  * @param {Object} node - Tree node from buildOutputHierarchyTree (has _children)
- * @param {string} rootStem - Root output file stem (e.g. "_output~Sales~abc")
+ * @param {string} rootStem - Root output file stem (e.g. "Sales~abc")
  * @param {string} outputDir - Directory where root output JSON lives
  * @param {string} serverTz - Server timezone
  * @param {string} [parentStem] - Ancestor stem for compound companion naming
@@ -3102,10 +2928,10 @@ async function buildInlineOutputChildren(parentObj, node, rootStem, outputDir, s
 
 /**
  * Move orphaned old-format child output .json files to /trash.
- * Old format: _output~name~uid.column~name~uid.json (has .column~, .join~, or .filter~ segments)
+ * Old format: name~uid.column~name~uid.json (has .column~, .join~, or .filter~ segments)
  *
  * @param {string} outputDir - Directory containing output files
- * @param {string} rootStem - Root output file stem (e.g. "_output~Sales~abc")
+ * @param {string} rootStem - Root output file stem (e.g. "Sales~abc")
  */
 async function trashOrphanedChildFiles(outputDir, rootStem) {
   let files;
@@ -3113,20 +2939,33 @@ async function trashOrphanedChildFiles(outputDir, rootStem) {
 
   const trashDir = join(process.cwd(), 'trash');
   let trashCreated = false;
+  // Also match legacy _output~ prefix for files from older CLI versions
+  const legacyStem = `_output~${rootStem}`;
 
   for (const f of files) {
-    if (f.startsWith(`${rootStem}.`) && f.endsWith('.json') && !f.includes('.CustomSQL.')) {
-      // Check it's actually an old child file (has .column~, .join~, or .filter~ segment)
-      if (/\.(column|join|filter)~/.test(f)) {
-        if (!trashCreated) {
-          await mkdir(trashDir, { recursive: true });
-          trashCreated = true;
-        }
-        try {
-          await rename(join(outputDir, f), join(trashDir, f));
-          log.dim(`  Trashed orphaned child file: ${f}`);
-        } catch { /* non-critical */ }
+    const matchesCurrent = f.startsWith(`${rootStem}.`);
+    const matchesLegacy = f.startsWith(`${legacyStem}.`);
+    if ((matchesCurrent || matchesLegacy) && /\.(column|join|filter)~/.test(f)) {
+      // Old child file or legacy CustomSQL companion — trash it
+      if (!trashCreated) {
+        await mkdir(trashDir, { recursive: true });
+        trashCreated = true;
       }
+      try {
+        await rename(join(outputDir, f), join(trashDir, f));
+        log.dim(`  Trashed orphaned child file: ${f}`);
+      } catch { /* non-critical */ }
+    }
+    // Also trash the legacy root file itself (_output~Name~UID.json) if new format exists
+    if (matchesLegacy === false && f === `${legacyStem}.json`) {
+      if (!trashCreated) {
+        await mkdir(trashDir, { recursive: true });
+        trashCreated = true;
+      }
+      try {
+        await rename(join(outputDir, f), join(trashDir, f));
+        log.dim(`  Trashed legacy output file: ${f}`);
+      } catch { /* non-critical */ }
     }
   }
 
@@ -3141,7 +2980,7 @@ async function trashOrphanedChildFiles(outputDir, rootStem) {
 /**
  * Parse an output hierarchy filename back into entity relationships.
  *
- * @param {string} filename - e.g. "_output~name~uid.column~name~uid.filter~name~uid.json"
+ * @param {string} filename - e.g. "name~uid.column~name~uid.filter~name~uid.json" (or legacy _output~ prefix)
  * @returns {Object} - { segments: [{entity, name, uid}], rootOutputUid, entityType, uid }
  */
 export function parseOutputHierarchyFile(filename) {
@@ -3150,7 +2989,7 @@ export function parseOutputHierarchyFile(filename) {
   if (base.endsWith('.json')) base = base.substring(0, base.length - 5);
 
   // Split into segments by finding entity type boundaries
-  // Entity types are: _output~, output~, column~, join~, filter~
+  // Entity types are: output~ (or legacy _output~), column~, join~, filter~
   const parts = [];
 
   // First, split by '.' but we need to be careful since names can contain '.'
@@ -3260,39 +3099,12 @@ async function processOutputHierarchy(appJson, structure, options, serverTz) {
   const forceReprocess = !!options.force;
 
   for (const output of tree) {
-    // Resolve bin directory for this output
-    let binDir = null;
-    let chosenBinId = null;
+    // Resolve bin directory: BinID → bins/<path>, null BinID → bins/ root
+    let binDir = BINS_DIR;
     if (output.BinID && structure[output.BinID]) {
       binDir = resolveBinPath(output.BinID, structure);
     }
 
-    if (!binDir) {
-      // No BinID — prompt or default
-      if (!options.yes) {
-        const inquirer = (await import('inquirer')).default;
-        const binChoices = Object.entries(structure).map(([id, entry]) => ({
-          name: `${entry.name} (${entry.fullPath})`,
-          value: id,
-        }));
-
-        if (binChoices.length > 0) {
-          const { binId } = await inquirer.prompt([{
-            type: 'list',
-            name: 'binId',
-            message: `Output "${output.Name || output.UID}" has no BinID. Which bin should it go in?`,
-            choices: binChoices,
-          }]);
-          chosenBinId = Number(binId);
-          binDir = resolveBinPath(chosenBinId, structure);
-        } else {
-          binDir = BINS_DIR;
-        }
-      } else {
-        binDir = BINS_DIR;
-      }
-    }
-
     await mkdir(binDir, { recursive: true });
 
     // Build root output filename
@@ -3329,7 +3141,7 @@ async function processOutputHierarchy(appJson, structure, options, serverTz) {
       }
       if (bulkAction.value !== 'overwrite_all') {
         const localSyncTime = await getLocalSyncTime(rootMetaPath);
-        const serverNewer = isServerNewer(localSyncTime, output._LastUpdated, configWithTz);
+        const serverNewer = isServerNewer(localSyncTime, output._LastUpdated, configWithTz, 'output', output.UID);
         const serverDate = parseServerDate(output._LastUpdated, serverTz);
         if (serverNewer) {
           const action = await promptChangeDetection(rootBasename, output, configWithTz, { serverDate, localDate: localSyncTime });
@@ -3378,12 +3190,6 @@ async function processOutputHierarchy(appJson, structure, options, serverTz) {
     await buildInlineOutputChildren(rootMeta, output, rootBasename, binDir, serverTz);
     // rootMeta now has .children = { column: [...], join: [...], filter: [...] }
 
-    // If user chose a bin for a BinID-less output, store it and mark as modified
-    if (chosenBinId) {
-      rootMeta.BinID = chosenBinId;
-      log.dim(`  Set BinID=${chosenBinId} on "${output.Name || output.UID}" (staged for next push)`);
-    }
-
     await writeFile(rootMetaPath, JSON.stringify(rootMeta, null, 2) + '\n');
     log.success(`Saved ${rootMetaPath}`);
 
@@ -3391,8 +3197,7 @@ async function processOutputHierarchy(appJson, structure, options, serverTz) {
     await trashOrphanedChildFiles(binDir, rootBasename);
 
     // Set file timestamps to server's _LastUpdated so diff detection works.
-    // Skip when chosenBinId is set — keep mtime at "now" so push detects the local edit.
-    if (!chosenBinId && serverTz && (output._CreatedOn || output._LastUpdated)) {
+    if (serverTz && (output._CreatedOn || output._LastUpdated)) {
       try {
         await setFileTimestamps(rootMetaPath, output._CreatedOn, output._LastUpdated, serverTz);
       } catch { /* non-critical */ }
@@ -3569,3 +3374,48 @@ export function decodeBase64Fields(obj) {
     }
   }
 }
+
+// ── Error log ─────────────────────────────────────────────────────────────
+
+const ERROR_LOG_PATH = join('.dbo', 'errors.log');
+
+/**
+ * Append a structured error entry to .dbo/errors.log.
+ * Creates the file if absent. Each entry is one JSON line (JSONL format).
+ */
+async function appendErrorLog(entry) {
+  try {
+    await appendFile(ERROR_LOG_PATH, JSON.stringify(entry) + '\n');
+  } catch {
+    // Best-effort — don't fail the command if logging fails
+  }
+}
+
+/**
+ * Build an ordered list of download URLs for a media record.
+ * Fallback chain: FullPath directly (/media/...) → /dir/ route → /api/media/{uid}
+ *
+ * @param {object} record - Media record with FullPath and UID
+ * @returns {string[]} - URLs to try in order
+ */
+function buildMediaDownloadUrls(record) {
+  const urls = [];
+
+  if (record.FullPath) {
+    // 1. FullPath as-is (e.g. /media/todoes/App/assets/file.ttf)
+    const fullPathUrl = record.FullPath.startsWith('/') ? record.FullPath : `/${record.FullPath}`;
+    urls.push(fullPathUrl);
+
+    // 2. /dir/ route — strip the /media/ prefix so the path starts with appShortName
+    const fp = record.FullPath.startsWith('/') ? record.FullPath.slice(1) : record.FullPath;
+    const dirPath = fp.startsWith('media/') ? fp.slice(6) : fp;
+    urls.push(`/dir/${dirPath}`);
+  }
+
+  // 3. /api/media/{uid} — UID-based endpoint as last resort
+  if (record.UID) {
+    urls.push(`/api/media/${record.UID}`);
+  }
+
+  return urls;
+}