@dboio/cli 0.13.2 → 0.15.1

package/src/commands/clone.js

@@ -6,14 +6,15 @@ 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, 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, buildContentFileName, stripUidFromFilename, hasUidInFilename, detectLegacyDotUid } from '../lib/filenames.js';
+import { buildUidFilename, buildContentFileName, buildMetaFilename, isMetadataFile, parseMetaFilename, stripUidFromFilename, hasUidInFilename } from '../lib/filenames.js';
 import { setFileTimestamps, parseServerDate } from '../lib/timestamps.js';
 import { getLocalSyncTime, isServerNewer, hasLocalModifications, promptChangeDetection, inlineDiffAndMerge, isDiffable, loadBaselineForComparison, resetBaselineCache, findMetadataFiles } from '../lib/diff.js';
 import { loadIgnore } from '../lib/ignore.js';
 import { checkDomainChange } from '../lib/domain-guard.js';
-import { applyTrashIcon, ensureTrashIcon } from '../lib/folder-icon.js';
+import { applyTrashIcon, ensureTrashIcon, tagProjectFiles } from '../lib/tagging.js';
 import { loadMetadataTemplates, saveMetadataTemplates, getTemplateCols, setTemplateCols, buildTemplateFromCloneRecord } from '../lib/metadata-templates.js';
 import { runPendingMigrations } from '../lib/migrations.js';
+import { upsertDeployEntry } from '../lib/deploy-config.js';
 
 /**
  * Resolve a column value that may be base64-encoded.
@@ -284,9 +285,8 @@ export function resolveRecordPaths(entityName, record, structure, placementPref)
   const uid = String(record.UID || record._id || 'untitled');
   // Companion: natural name, no UID
   const filename = sanitizeFilename(buildContentFileName(record, uid));
-  // Metadata: still uses ~UID
-  const metaBase = buildUidFilename(name, uid);
-  const metaPath = join(dir, `${metaBase}.metadata.json`);
+  // Metadata: name.metadata~uid.json
+  const metaPath = join(dir, buildMetaFilename(name, uid));
 
   return { dir, filename, metaPath };
 }
@@ -315,10 +315,10 @@ export function resolveMediaPaths(record, structure) {
   dir = dir.replace(/^\/+|\/+$/g, '');
   if (!dir) dir = BINS_DIR;
 
-  // Metadata: name~uid.ext.metadata.json (unchanged format)
+  // Metadata: name.ext.metadata~uid.json
   const uid = String(record.UID || record._id || 'untitled');
-  const metaBase = buildUidFilename(name, uid);
-  const metaPath = join(dir, `${metaBase}.${ext}.metadata.json`);
+  const naturalMediaBase = `${name}.${ext}`;
+  const metaPath = join(dir, buildMetaFilename(naturalMediaBase, uid));
 
   return { dir, filename: companionFilename, metaPath };
 }
@@ -326,6 +326,9 @@ export function resolveMediaPaths(record, structure) {
 /**
  * Extract path components for entity-dir records.
  * Simplified from processEntityDirEntries() for collision detection.
+ *
+ * Returns `name` (natural, no ~UID) for companion files and
+ * `metaPath` (with ~UID) for the metadata file.
  */
 export function resolveEntityDirPaths(entityName, record, dirName) {
   let name;
@@ -338,9 +341,8 @@ export function resolveEntityDirPaths(entityName, record, dirName) {
   }
 
   const uid = record.UID || 'untitled';
-  const finalName = buildUidFilename(name, uid);
-  const metaPath = join(dirName, `${finalName}.metadata.json`);
-  return { dir: dirName, filename: finalName, metaPath };
+  const metaPath = join(dirName, buildMetaFilename(name, uid));
+  return { dir: dirName, name, metaPath };
 }
 
 /**
@@ -513,7 +515,7 @@ async function trashOrphanedLegacyCompanions() {
         continue;
       }
 
-      if (entry.name.endsWith('.metadata.json')) {
+      if (isMetadataFile(entry.name)) {
         // Read metadata and collect all @references
         try {
           const meta = JSON.parse(await readFile(full, 'utf8'));
@@ -598,9 +600,9 @@ async function buildFileRegistry(appJson, structure, placementPrefs) {
     registry.get(filePath).push(entry);
   }
 
-  // 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.
+  // Note: entity-dir records (Extensions/, Data Sources/, etc.) use natural names for
+  // companion files with -N suffix collision resolution handled inline during processing.
+  // Only content and media records in Bins/ are checked for cross-entity collisions here.
 
   return registry;
 }
@@ -1288,6 +1290,9 @@ export async function performClone(source, options = {}) {
   // Step 9: Trash orphaned legacy ~UID companion files that no metadata references
   await trashOrphanedLegacyCompanions();
 
+  // Step 10: Tag project files with sync status (best-effort, non-blocking)
+  tagProjectFiles({ verbose: false }).catch(() => {});
+
   log.plain('');
   const verb = options.pullMode ? 'Pull' : 'Clone';
   log.success(entityFilter ? `${verb} complete! (filtered: ${options.entity})` : `${verb} complete!`);
@@ -1570,6 +1575,7 @@ async function processEntityDirEntries(entityName, entries, options, serverTz) {
   const refs = [];
   const bulkAction = { value: null };
   const legacyRenameAction = { value: null }; // 'rename_all' | 'skip_all' | null
+  const usedNames = new Map(); // name → count, for collision resolution
   const config = await loadConfig();
 
   // Determine filename column: saved preference, or prompt, or default
@@ -1717,19 +1723,27 @@ async function processEntityDirEntries(entityName, entries, options, serverTz) {
       name = sanitizeFilename(String(record.UID || 'untitled'));
     }
 
-    // Include UID in filename via tilde convention to ensure uniqueness
+    // Resolve name collisions: second+ record with same name gets -1, -2, etc.
     const uid = record.UID || 'untitled';
-    const finalName = buildUidFilename(name, uid);
-
-    const metaPath = join(dirName, `${finalName}.metadata.json`);
-
-    // Legacy dot-separator detection: rename <name>.<uid>.metadata.json → <name>~<uid>.metadata.json
-    const legacyMetaPath = join(dirName, `${name}.${uid}.metadata.json`);
-    if (!await fileExists(metaPath) && await fileExists(legacyMetaPath)) {
+    const nameKey = name;
+    const count = usedNames.get(nameKey) || 0;
+    usedNames.set(nameKey, count + 1);
+    if (count > 0) name = `${name}-${count}`;
+
+    // Metadata: name.metadata~uid.json; companion files use natural name
+    const metaPath = join(dirName, buildMetaFilename(name, uid));
+
+    // Legacy detection: rename old-format metadata files to new convention
+    const legacyDotMetaPath = join(dirName, `${name}.${uid}.metadata.json`);
+    const legacyTildeMetaPath = join(dirName, `${buildUidFilename(name, uid)}.metadata.json`);
+    const legacyPath = !await fileExists(metaPath) && await fileExists(legacyDotMetaPath) ? legacyDotMetaPath
+      : !await fileExists(metaPath) && await fileExists(legacyTildeMetaPath) ? legacyTildeMetaPath
+      : null;
+    if (legacyPath) {
       if (options.yes || legacyRenameAction.value === 'rename_all') {
         const { rename: fsRename } = await import('fs/promises');
-        await fsRename(legacyMetaPath, metaPath);
-        log.dim(`  Auto-renamed: ${basename(legacyMetaPath)} → ${basename(metaPath)}`);
+        await fsRename(legacyPath, metaPath);
+        log.dim(`  Auto-renamed: ${basename(legacyPath)} → ${basename(metaPath)}`);
       } else if (legacyRenameAction.value === 'skip_all') {
         // skip silently
       } else {
@@ -1737,7 +1751,7 @@ async function processEntityDirEntries(entityName, entries, options, serverTz) {
         const { action } = await inquirer.prompt([{
           type: 'list',
           name: 'action',
-          message: `Found legacy filename "${basename(legacyMetaPath)}" — rename to "${basename(metaPath)}"?`,
+          message: `Found legacy filename "${basename(legacyPath)}" — rename to "${basename(metaPath)}"?`,
           choices: [
             { name: 'Yes', value: 'rename' },
             { name: 'Rename all remaining', value: 'rename_all' },
@@ -1747,8 +1761,8 @@ async function processEntityDirEntries(entityName, entries, options, serverTz) {
         }]);
         if (action === 'rename' || action === 'rename_all') {
           const { rename: fsRename } = await import('fs/promises');
-          await fsRename(legacyMetaPath, metaPath);
-          log.success(`  Renamed: ${basename(legacyMetaPath)} → ${basename(metaPath)}`);
+          await fsRename(legacyPath, metaPath);
+          log.success(`  Renamed: ${basename(legacyPath)} → ${basename(metaPath)}`);
           if (action === 'rename_all') legacyRenameAction.value = 'rename_all';
         } else {
           if (action === 'skip_all') legacyRenameAction.value = 'skip_all';
@@ -1765,7 +1779,7 @@ async function processEntityDirEntries(entityName, entries, options, serverTz) {
     const entityMetaExists = await fileExists(metaPath) && !await fileExists(willDeleteEntityMeta);
     if (entityMetaExists && !options.yes && !hasNewExtractions) {
       if (bulkAction.value === 'skip_all') {
-        log.dim(`  Skipped ${finalName}`);
+        log.dim(`  Skipped ${name}`);
         refs.push({ uid: record.UID, metaPath });
         continue;
       }
@@ -1787,22 +1801,22 @@ async function processEntityDirEntries(entityName, entries, options, serverTz) {
         if (serverNewer) {
           // Incomplete metadata (no _LastUpdated) from dbo add — auto-accept without prompting
           if (localMissingLastUpdated) {
-            log.dim(`  Completing metadata: ${finalName}`);
+            log.dim(`  Completing metadata: ${name}`);
             // Fall through to write
           } else {
-            const action = await promptChangeDetection(finalName, record, configWithTz, {
+            const action = await promptChangeDetection(name, record, configWithTz, {
               serverDate,
               localDate: localSyncTime,
             });
 
             if (action === 'skip') {
-              log.dim(`  Skipped ${finalName}`);
+              log.dim(`  Skipped ${name}`);
               refs.push({ uid: record.UID, metaPath });
               continue;
             }
             if (action === 'skip_all') {
               bulkAction.value = 'skip_all';
-              log.dim(`  Skipped ${finalName}`);
+              log.dim(`  Skipped ${name}`);
               refs.push({ uid: record.UID, metaPath });
               continue;
             }
@@ -1818,20 +1832,20 @@ async function processEntityDirEntries(entityName, entries, options, serverTz) {
         } else {
           const locallyModified = await hasLocalModifications(metaPath, configWithTz);
           if (locallyModified) {
-            const action = await promptChangeDetection(finalName, record, configWithTz, {
+            const action = await promptChangeDetection(name, record, configWithTz, {
               localIsNewer: true,
               serverDate,
               localDate: localSyncTime,
             });
 
             if (action === 'skip') {
-              log.dim(`  Kept local: ${finalName}`);
+              log.dim(`  Kept local: ${name}`);
               refs.push({ uid: record.UID, metaPath });
               continue;
             }
             if (action === 'skip_all') {
               bulkAction.value = 'skip_all';
-              log.dim(`  Kept local: ${finalName}`);
+              log.dim(`  Kept local: ${name}`);
               refs.push({ uid: record.UID, metaPath });
               continue;
             }
@@ -1844,7 +1858,7 @@ async function processEntityDirEntries(entityName, entries, options, serverTz) {
               continue;
             }
           } else {
-            log.dim(`  Up to date: ${finalName}`);
+            log.dim(`  Up to date: ${name}`);
             refs.push({ uid: record.UID, metaPath });
             continue;
           }
@@ -1864,9 +1878,10 @@ async function processEntityDirEntries(entityName, entries, options, serverTz) {
       if (extractInfo) {
         const isBase64 = value && typeof value === 'object' && !Array.isArray(value) && value.encoding === 'base64';
         const decoded = isBase64 ? (resolveContentValue(value) ?? '') : (value ?? '');
-        const colFileName = `${finalName}.${key}.${extractInfo.ext}`;
+        const colFileName = `${name}.${key}.${extractInfo.ext}`;
         const colFilePath = join(dirName, colFileName);
         await writeFile(colFilePath, decoded);
+        await upsertDeployEntry(colFilePath, record.UID, entityName, key);
         meta[key] = `@${colFileName}`;
         extractedContentCols.push(key);
 
@@ -2198,6 +2213,7 @@ async function processExtensionEntries(entries, structure, options, serverTz) {
     const { filenameCol, contentColsToExtract } = descriptorPrefs.get(descriptor);
     const useRootDoc = (descriptor === 'documentation' && docPlacement === 'root');
     const mdColInfo = useRootDoc ? contentColsToExtract.find(c => c.ext === 'md') : null;
+    const usedNames = new Map(); // name → count, for collision resolution within this descriptor group
 
     log.info(`Processing ${records.length} "${descriptor}" extension(s) → ${dir}/`);
 
@@ -2212,17 +2228,27 @@ async function processExtensionEntries(entries, structure, options, serverTz) {
         name = sanitizeFilename(String(record.UID || 'untitled'));
       }
 
+      // Resolve name collisions: second+ record with same name gets -1, -2, etc.
       const uid = record.UID || 'untitled';
-      const finalName = buildUidFilename(name, uid);
-      const metaPath = join(dir, `${finalName}.metadata.json`);
-
-      // Legacy dot-separator detection: rename <name>.<uid>.metadata.json → <name>~<uid>.metadata.json
-      const legacyExtMetaPath = join(dir, `${name}.${uid}.metadata.json`);
-      if (!await fileExists(metaPath) && await fileExists(legacyExtMetaPath)) {
+      const nameKey = name;
+      const nameCount = usedNames.get(nameKey) || 0;
+      usedNames.set(nameKey, nameCount + 1);
+      if (nameCount > 0) name = `${name}-${nameCount}`;
+
+      // Metadata: name.metadata~uid.json; companion files use natural name
+      const metaPath = join(dir, buildMetaFilename(name, uid));
+
+      // Legacy detection: rename old-format metadata files to new convention
+      const legacyDotExtMetaPath = join(dir, `${name}.${uid}.metadata.json`);
+      const legacyTildeExtMetaPath = join(dir, `${buildUidFilename(name, uid)}.metadata.json`);
+      const legacyExtPath = !await fileExists(metaPath) && await fileExists(legacyDotExtMetaPath) ? legacyDotExtMetaPath
+        : !await fileExists(metaPath) && await fileExists(legacyTildeExtMetaPath) ? legacyTildeExtMetaPath
+        : null;
+      if (legacyExtPath) {
         if (options.yes || legacyRenameAction.value === 'rename_all') {
           const { rename: fsRename } = await import('fs/promises');
-          await fsRename(legacyExtMetaPath, metaPath);
-          log.dim(`  Auto-renamed: ${basename(legacyExtMetaPath)} → ${basename(metaPath)}`);
+          await fsRename(legacyExtPath, metaPath);
+          log.dim(`  Auto-renamed: ${basename(legacyExtPath)} → ${basename(metaPath)}`);
         } else if (legacyRenameAction.value === 'skip_all') {
           // skip silently
         } else {
@@ -2230,7 +2256,7 @@ async function processExtensionEntries(entries, structure, options, serverTz) {
           const { action } = await inquirer.prompt([{
             type: 'list',
             name: 'action',
-            message: `Found legacy filename "${basename(legacyExtMetaPath)}" — rename to "${basename(metaPath)}"?`,
+            message: `Found legacy filename "${basename(legacyExtPath)}" — rename to "${basename(metaPath)}"?`,
             choices: [
               { name: 'Yes', value: 'rename' },
               { name: 'Rename all remaining', value: 'rename_all' },
@@ -2240,8 +2266,8 @@ async function processExtensionEntries(entries, structure, options, serverTz) {
           }]);
           if (action === 'rename' || action === 'rename_all') {
             const { rename: fsRename } = await import('fs/promises');
-            await fsRename(legacyExtMetaPath, metaPath);
-            log.success(`  Renamed: ${basename(legacyExtMetaPath)} → ${basename(metaPath)}`);
+            await fsRename(legacyExtPath, metaPath);
+            log.success(`  Renamed: ${basename(legacyExtPath)} → ${basename(metaPath)}`);
             if (action === 'rename_all') legacyRenameAction.value = 'rename_all';
           } else {
             if (action === 'skip_all') legacyRenameAction.value = 'skip_all';
@@ -2282,7 +2308,7 @@ async function processExtensionEntries(entries, structure, options, serverTz) {
       const extMetaExists = await fileExists(metaPath) && !await fileExists(willDeleteExtMeta);
       if (extMetaExists && !options.yes && !hasNewExtractions) {
         if (bulkAction.value === 'skip_all') {
-          log.dim(`  Skipped ${finalName}`);
+          log.dim(`  Skipped ${name}`);
           refs.push({ uid: record.UID, metaPath });
           continue;
         }
@@ -2293,7 +2319,7 @@ async function processExtensionEntries(entries, structure, options, serverTz) {
           const serverDate = parseServerDate(record._LastUpdated, serverTz);
 
           if (serverNewer) {
-            const action = await promptChangeDetection(finalName, record, cfgWithTz, { serverDate, localDate: localSyncTime });
+            const action = await promptChangeDetection(name, record, cfgWithTz, { serverDate, localDate: localSyncTime });
             if (action === 'skip') { refs.push({ uid: record.UID, metaPath }); continue; }
             if (action === 'skip_all') { bulkAction.value = 'skip_all'; refs.push({ uid: record.UID, metaPath }); continue; }
             if (action === 'overwrite_all') { bulkAction.value = 'overwrite_all'; }
@@ -2301,13 +2327,13 @@ async function processExtensionEntries(entries, structure, options, serverTz) {
           } else {
             const localModified = await hasLocalModifications(metaPath, cfgWithTz);
             if (localModified) {
-              const action = await promptChangeDetection(finalName, record, cfgWithTz, { localIsNewer: true, serverDate, localDate: localSyncTime });
+              const action = await promptChangeDetection(name, record, cfgWithTz, { localIsNewer: true, serverDate, localDate: localSyncTime });
               if (action === 'skip') { refs.push({ uid: record.UID, metaPath }); continue; }
               if (action === 'skip_all') { bulkAction.value = 'skip_all'; refs.push({ uid: record.UID, metaPath }); continue; }
               if (action === 'overwrite_all') { bulkAction.value = 'overwrite_all'; }
               if (action === 'compare') { await inlineDiffAndMerge(record, metaPath, cfgWithTz, { localIsNewer: true }); refs.push({ uid: record.UID, metaPath }); continue; }
             } else {
-              log.dim(`  Up to date: ${finalName}`);
+              log.dim(`  Up to date: ${name}`);
               refs.push({ uid: record.UID, metaPath });
               continue;
             }
@@ -2334,13 +2360,14 @@ async function processExtensionEntries(entries, structure, options, serverTz) {
             colFilePath = join(DOCUMENTATION_DIR, docFileName);
             refValue = `@/${DOCUMENTATION_DIR}/${docFileName}`;
           } else {
-            const colFileName = `${finalName}.${key}.${extractInfo.ext}`;
+            const colFileName = `${name}.${key}.${extractInfo.ext}`;
             colFilePath = join(dir, colFileName);
             refValue = `@${colFileName}`;
           }
 
           meta[key] = refValue;
           await writeFile(colFilePath, decoded);
+          await upsertDeployEntry(colFilePath, record.UID, 'extension', key);
           extractedCols.push(key);
           if (serverTz) {
             try { await setFileTimestamps(colFilePath, record._CreatedOn, record._LastUpdated, serverTz); } catch {}
@@ -2498,9 +2525,9 @@ async function processMediaEntries(mediaRecords, structure, options, config, app
     const uid = String(record.UID || record._id || 'untitled');
     const finalFilename = resolvedFilenames.get(record.UID) || sanitizeFilename(filename);
     const filePath = join(dir, finalFilename);
-    // Metadata: name~uid.ext.metadata.json (unchanged format)
-    const metaBase = buildUidFilename(name, uid);
-    const metaPath = join(dir, `${metaBase}.${ext}.metadata.json`);
+    // Metadata: name.ext.metadata~uid.json
+    const naturalMediaBase = `${name}.${ext}`;
+    const metaPath = join(dir, buildMetaFilename(naturalMediaBase, uid));
     // usedNames retained for tracking
     const fileKey = `${dir}/${name}.${ext}`;
     usedNames.set(fileKey, (usedNames.get(fileKey) || 0) + 1);
@@ -2671,6 +2698,7 @@ async function processMediaEntries(mediaRecords, structure, options, config, app
     meta._mediaFile = `@${finalFilename}`;
 
     await writeFile(metaPath, JSON.stringify(meta, null, 2) + '\n');
+    await upsertDeployEntry(filePath, record.UID, 'media', 'File');
     log.dim(`  → ${metaPath}`);
 
     // Set file timestamps from server dates (independent try-catch so one failure
@@ -2742,7 +2770,6 @@ async function processRecord(entityName, record, structure, options, usedNames,
     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]) {
@@ -2753,7 +2780,7 @@ async function processRecord(entityName, record, structure, options, usedNames,
       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 probeMeta = join(probeDir, buildMetaFilename(sanitized, uid));
       const raw = await readFile(probeMeta, 'utf8');
       const localMeta = JSON.parse(raw);
       // Extract extension from Content @reference (e.g. "@Name~uid.html")
@@ -2842,8 +2869,7 @@ async function processRecord(entityName, record, structure, options, usedNames,
   const uid = String(record.UID || record._id || 'untitled');
   // Companion: natural name, no UID (use collision-resolved override if available)
   const fileName = filenameOverride || sanitizeFilename(buildContentFileName(record, uid));
-  // Metadata: still uses ~UID
-  const metaBase = buildUidFilename(name, uid);
+  // Metadata: name.metadata~uid.json
   // usedNames retained for non-UID edge case tracking
   const nameKey = `${dir}/${name}`;
   usedNames.set(nameKey, (usedNames.get(nameKey) || 0) + 1);
@@ -2856,7 +2882,7 @@ async function processRecord(entityName, record, structure, options, usedNames,
   );
 
   const filePath = join(dir, fileName);
-  const metaPath = join(dir, `${metaBase}.metadata.json`);
+  const metaPath = join(dir, buildMetaFilename(name, uid));
 
   // Rename legacy ~UID companion files to natural names if needed
   if (await fileExists(metaPath)) {
@@ -2961,6 +2987,7 @@ async function processRecord(entityName, record, structure, options, usedNames,
   if (hasContent) {
     const decoded = resolveContentValue(contentValue) ?? '';
     await writeFile(filePath, decoded);
+    await upsertDeployEntry(filePath, record.UID, entityName, 'Content');
     log.success(`Saved ${filePath}`);
   }
 
@@ -2976,11 +3003,12 @@ async function processRecord(entityName, record, structure, options, usedNames,
       // Other base64 columns — decode and store inline or as reference
       const decoded = resolveContentValue(value);
       if (decoded && decoded.length > 200) {
-        // Large value: save as separate file
+        // Large value: save as separate file (natural name, no ~UID)
         const colExt = guessExtensionForColumn(key);
-        const colFileName = `${metaBase}-${key.toLowerCase()}.${colExt}`;
+        const colFileName = `${name}-${key.toLowerCase()}.${colExt}`;
         const colFilePath = join(dir, colFileName);
         await writeFile(colFilePath, decoded);
+        await upsertDeployEntry(colFilePath, record.UID, entityName, key);
         meta[key] = `@${colFileName}`;
         if (!meta._contentColumns) meta._contentColumns = [];
         meta._contentColumns.push(key);
@@ -3233,17 +3261,11 @@ async function resolveOutputFilenameColumns(appJson, options) {
 export function buildOutputFilename(entityType, node, filenameCol, parentChain = []) {
   const uid = node.UID || '';
   const rawName = node[filenameCol];
-  const name = rawName ? sanitizeFilename(String(rawName)) : '';
+  const name = rawName ? sanitizeFilename(String(rawName)) : uid;
 
-  // Build this entity's segment
-  let segment;
-  if (entityType === 'output') {
-    // 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}`;
-  }
+  // Root output: use natural name only (UID goes to .metadata~uid.json, not the stem)
+  // Child entities: docName only, no ~uid (index determines uniqueness)
+  const segment = entityType === 'output' ? name : entityType;
 
   const allSegments = [...parentChain, segment];
   return allSegments.join('.');
@@ -3257,18 +3279,21 @@ 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 "Sales~abc", entity "output_value", uid "col1"
- *   → "Sales~abc.column~col1"
+ * Uses array index for uniqueness (index 0 = no suffix, index N = "-N" suffix).
+ *
+ * e.g. rootStem "Sales", entity "output_value", index 0 → "Sales.column"
+ *      rootStem "Sales", entity "output_value", index 1 → "Sales.column-1"
  *
- * @param {string} rootStem - Root output file stem (no extension)
+ * @param {string} rootStem - Root output natural name (e.g. "Sales")
  * @param {string} physicalEntity - Physical entity name ('output_value', etc.)
- * @param {string} uid - Child entity UID
+ * @param {number} index - Zero-based position of this child in its array
  * @param {string} [parentChainStem] - Already-built ancestor stem (for nested children)
  * @returns {string}
  */
-export function getChildCompanionStem(rootStem, physicalEntity, uid, parentChainStem = rootStem) {
+export function getChildCompanionStem(rootStem, physicalEntity, index, parentChainStem = rootStem) {
   const docName = INLINE_DOC_NAMES[physicalEntity] || physicalEntity;
-  return `${parentChainStem}.${docName}~${uid}`;
+  const suffix = index === 0 ? '' : `-${index}`;
+  return `${parentChainStem}.${docName}${suffix}`;
 }
 
 /**
@@ -3305,6 +3330,7 @@ async function extractCustomSqlIfNeeded(entityObj, companionStem, outputDir, ser
   const companionName = `${companionStem}.CustomSQL.sql`;
   const companionPath = join(outputDir, companionName);
   await writeFile(companionPath, hasContent ? decoded : '', 'utf8');
+  await upsertDeployEntry(companionPath, entityObj.UID || entityObj._uid, 'output', 'CustomSQL');
   entityObj.CustomSQL = `@${companionName}`;
   entityObj._contentColumns = entityObj._contentColumns || [];
   if (!entityObj._contentColumns.includes('CustomSQL')) {
@@ -3350,7 +3376,8 @@ async function buildInlineOutputChildren(parentObj, node, rootStem, outputDir, s
 
     if (!Array.isArray(entityArray) || entityArray.length === 0) continue;
 
-    for (const child of entityArray) {
+    for (let childIdx = 0; childIdx < entityArray.length; childIdx++) {
+      const child = entityArray[childIdx];
       // Build a clean copy without tree-internal fields
       const childObj = { ...child };
       delete childObj._children;
@@ -3366,8 +3393,8 @@ async function buildInlineOutputChildren(parentObj, node, rootStem, outputDir, s
       // Ensure _entity is set to physical entity name (for push routing)
       childObj._entity = physicalKey;
 
-      // Compute companion stem for this child
-      const childStem = getChildCompanionStem(rootStem, physicalKey, child.UID, parentStem);
+      // Compute companion stem for this child (index-based, not UID-based)
+      const childStem = getChildCompanionStem(rootStem, physicalKey, childIdx, parentStem);
 
       // Extract CustomSQL if needed
       const companionFile = await extractCustomSqlIfNeeded(childObj, childStem, outputDir, serverTz);
@@ -3419,8 +3446,8 @@ async function trashOrphanedChildFiles(outputDir, rootStem) {
         log.dim(`  Trashed orphaned child file: ${f}`);
       } catch { /* non-critical */ }
     }
-    // Also trash the legacy root file itself (_output~Name~UID.json or .metadata.json) if new format exists
-    if (matchesLegacy === false && (f === `${legacyStem}.json` || f === `${legacyStem}.metadata.json`)) {
+    // Also trash the legacy root file itself (_output~Name~UID.json or .metadata.json)
+    if (!matchesCurrent && (f === `${legacyStem}.json` || f === `${legacyStem}.metadata.json`)) {
       if (!trashCreated) {
         await mkdir(trashDir, { recursive: true });
         trashCreated = true;
@@ -3447,10 +3474,16 @@ async function trashOrphanedChildFiles(outputDir, rootStem) {
  * @returns {Object} - { segments: [{entity, name, uid}], rootOutputUid, entityType, uid }
  */
 export function parseOutputHierarchyFile(filename) {
-  // Strip .metadata.json or legacy .json extension
+  // Strip metadata or .json extension
   let base = filename;
-  if (base.endsWith('.metadata.json')) base = base.substring(0, base.length - 14);
-  else if (base.endsWith('.json')) base = base.substring(0, base.length - 5);
+  const metaParsed = parseMetaFilename(filename);
+  if (metaParsed) {
+    base = metaParsed.naturalBase;
+  } else if (base.endsWith('.metadata.json')) {
+    base = base.substring(0, base.length - 14);
+  } else if (base.endsWith('.json')) {
+    base = base.substring(0, base.length - 5);
+  }
 
   // Split into segments by finding entity type boundaries
   // Entity types are: output~ (or legacy _output~), column~, join~, filter~
@@ -3571,15 +3604,26 @@ async function processOutputHierarchy(appJson, structure, options, serverTz) {
 
     await mkdir(binDir, { recursive: true });
 
-    // Build root output filename
+    // Build root output filename (natural name, no UID in stem)
     const rootBasename = buildOutputFilename('output', output, filenameCols.output);
-    let rootMetaPath = join(binDir, `${rootBasename}.metadata.json`);
+    const rootUid = output.UID || '';
+    let rootMetaPath = join(binDir, buildMetaFilename(rootBasename, rootUid));
 
-    // Legacy fallback: if old .json exists but new .metadata.json doesn't, rename in-place
+    // Legacy fallback: rename old-format metadata to new convention
+    const legacyTildeOutputMeta = join(binDir, `${rootBasename}~${rootUid}.metadata.json`);
     const legacyJsonPath = join(binDir, `${rootBasename}.json`);
-    if (!await fileExists(rootMetaPath) && await fileExists(legacyJsonPath)) {
-      await rename(legacyJsonPath, rootMetaPath);
-      log.dim(`  Renamed ${rootBasename}.json → ${rootBasename}.metadata.json`);
+    const legacyOutputMeta = join(binDir, `${rootBasename}.metadata.json`);
+    if (!await fileExists(rootMetaPath)) {
+      if (await fileExists(legacyTildeOutputMeta)) {
+        await rename(legacyTildeOutputMeta, rootMetaPath);
+        log.dim(`  Renamed ${basename(legacyTildeOutputMeta)} → ${basename(rootMetaPath)}`);
+      } else if (await fileExists(legacyOutputMeta)) {
+        await rename(legacyOutputMeta, rootMetaPath);
+        log.dim(`  Renamed ${basename(legacyOutputMeta)} → ${basename(rootMetaPath)}`);
+      } else if (await fileExists(legacyJsonPath)) {
+        await rename(legacyJsonPath, rootMetaPath);
+        log.dim(`  Renamed ${rootBasename}.json → ${basename(rootMetaPath)}`);
+      }
     }
 
     // Detect old-format files that need migration to inline children format.

package/src/commands/deploy.js

@@ -57,10 +57,17 @@ export const deployCommand = new Command('deploy')
         process.exit(1);
       }
 
+      // If name doesn't match a key directly, try scanning by UID value
+      let resolvedName = name;
+      if (name && !manifest.deployments[name]) {
+        const byUid = Object.entries(manifest.deployments).find(([, v]) => v && v.uid === name);
+        if (byUid) resolvedName = byUid[0];
+      }
+
       const entries = options.all
         ? Object.entries(manifest.deployments)
-        : name
-          ? [[name, manifest.deployments[name]]]
+        : resolvedName
+          ? [[resolvedName, manifest.deployments[resolvedName]]]
           : [];
 
       if (entries.length === 0 || (entries.length === 1 && !entries[0][1])) {

package/src/commands/diff.js

@@ -14,7 +14,7 @@ import {
 } from '../lib/diff.js';
 import { fetchServerRecordsBatch } from '../lib/toe-stepping.js';
 import { findBaselineEntry } from '../lib/delta.js';
-import { findMetadataForCompanion } from '../lib/filenames.js';
+import { isMetadataFile, parseMetaFilename, findMetadataForCompanion } from '../lib/filenames.js';
 import { runPendingMigrations } from '../lib/migrations.js';
 
 export const diffCommand = new Command('diff')
@@ -82,7 +82,7 @@ export const diffCommand = new Command('diff')
       let bulkAction = null;
 
       for (const metaPath of metaFiles) {
-        const metaBase = basename(metaPath, '.metadata.json');
+        const metaBase = parseMetaFilename(basename(metaPath))?.naturalBase ?? basename(metaPath, '.metadata.json');
 
         const result = await compareRecord(metaPath, config, serverRecordsMap);
 
@@ -204,7 +204,7 @@ async function resolveTargetToMetaFiles(targetPath) {
     pathStat = await stat(targetPath);
   } catch {
     // Maybe it's a file without extension — try finding metadata
-    const metaPath = targetPath.endsWith('.metadata.json')
+    const metaPath = (isMetadataFile(basename(targetPath)) || targetPath.endsWith('.metadata.json'))
       ? targetPath
       : `${targetPath}.metadata.json`;
 
@@ -221,7 +221,7 @@ async function resolveTargetToMetaFiles(targetPath) {
   }
 
   // Single file — find its companion metadata
-  if (targetPath.endsWith('.metadata.json')) {
+  if (isMetadataFile(basename(targetPath)) || targetPath.endsWith('.metadata.json')) {
     return [targetPath];
   }