@dboio/cli 0.9.8 → 0.11.1

package/src/commands/push.js

@@ -1,21 +1,24 @@
 import { Command } from 'commander';
-import { readFile, stat, writeFile, rename as fsRename, mkdir } from 'fs/promises';
+import { readFile, readdir, stat, writeFile, rename as fsRename, mkdir, access } from 'fs/promises';
 import { join, dirname, basename, extname, relative } from 'path';
 import { DboClient } from '../lib/client.js';
 import { buildInputBody, checkSubmitErrors, getSessionUserOverride } from '../lib/input-parser.js';
 import { formatResponse, formatError } from '../lib/formatter.js';
 import { log } from '../lib/logger.js';
 import { shouldSkipColumn } from '../lib/columns.js';
-import { loadConfig, loadSynchronize, saveSynchronize, loadAppJsonBaseline, saveAppJsonBaseline, hasBaseline } from '../lib/config.js';
+import { loadConfig, loadAppConfig, loadSynchronize, saveSynchronize, loadAppJsonBaseline, saveAppJsonBaseline, hasBaseline } from '../lib/config.js';
 import { checkStoredTicket, applyStoredTicketToSubmission, clearRecordTicket, clearGlobalTicket } from '../lib/ticketing.js';
 import { checkModifyKey, isModifyKeyError, handleModifyKeyError } from '../lib/modify-key.js';
 import { resolveTransactionKey } from '../lib/transaction-key.js';
 import { setFileTimestamps } from '../lib/timestamps.js';
-import { stripUidFromFilename, renameToUidConvention, hasUidInFilename } from '../lib/filenames.js';
-import { findMetadataFiles } from '../lib/diff.js';
+import { stripUidFromFilename, renameToUidConvention, hasUidInFilename, buildUidFilename } from '../lib/filenames.js';
+import { findMetadataFiles, findFileInProject, findByUID } from '../lib/diff.js';
 import { loadIgnore } from '../lib/ignore.js';
-import { detectChangedColumns, findBaselineEntry } from '../lib/delta.js';
-import { BINS_DIR, ENTITY_DIR_NAMES } from '../lib/structure.js';
+import { detectChangedColumns, findBaselineEntry, detectOutputChanges, getAllUserColumns, isReference, resolveReferencePath, detectBinChanges, synthesizeBinMetadata } from '../lib/delta.js';
+import { BINS_DIR, ENTITY_DIR_NAMES, loadStructureFile, findBinByPath } from '../lib/structure.js';
+import { ensureTrashIcon } from '../lib/folder-icon.js';
+import { checkToeStepping } from '../lib/toe-stepping.js';
+import { runPendingMigrations } from '../lib/migrations.js';
 
 /**
  * Resolve an @reference file path to an absolute filesystem path.
@@ -28,6 +31,15 @@ function resolveAtReference(refFile, metaDir) {
   }
   return join(metaDir, refFile);
 }
+/**
+ * Resolve whether toe-stepping is enabled.
+ * --toe-stepping false (or '0', 'no') disables the server conflict check.
+ */
+function isToeStepping(options) {
+  const v = String(options.toeStepping ?? 'true').toLowerCase();
+  return v !== 'false' && v !== '0' && v !== 'no';
+}
+
 import { ENTITY_DEPENDENCIES } from '../lib/dependencies.js';
 
 export const pushCommand = new Command('push')
@@ -39,13 +51,16 @@ export const pushCommand = new Command('push')
   .option('--meta-only', 'Only push metadata changes, skip file content')
   .option('--content-only', 'Only push file content, skip metadata columns')
   .option('-y, --yes', 'Auto-accept all prompts (path refactoring, etc.)')
+  .option('--toe-stepping <value>', 'Check for server conflicts before push: true (default) or false', 'true')
   .option('--row-key <type>', 'Override row key type for this invocation (RowUID or RowID)')
   .option('--json', 'Output raw JSON')
   .option('--jq <expr>', 'Filter JSON response')
   .option('-v, --verbose', 'Show HTTP request details')
   .option('--domain <host>', 'Override domain')
+  .option('--no-migrate', 'Skip pending migrations for this invocation')
   .action(async (targetPath, options) => {
     try {
+      await runPendingMigrations(options);
       const client = new DboClient({ domain: options.domain, verbose: options.verbose });
 
       // ModifyKey guard — check once before any submissions
@@ -62,7 +77,62 @@ export const pushCommand = new Command('push')
       // Process pending deletions from synchronize.json
       await processPendingDeletes(client, options, modifyKey, transactionKey);
 
-      const pathStat = await stat(targetPath);
+      // ── Resolution order ──────────────────────────────────────────
+      // 1. Commas → UID list
+      // 2. stat() → file/directory (existing behaviour)
+      // 3. stat fails:
+      //    a. No extension + no path separator → search by UID
+      //    b. Otherwise → bare filename search via findFileInProject()
+
+      // 1. Comma-separated → treat as UID list
+      if (targetPath.includes(',')) {
+        const uids = targetPath.split(',').map(u => u.trim()).filter(Boolean);
+        await pushByUIDs(uids, client, options, modifyKey, transactionKey);
+        return;
+      }
+
+      // 2. Try stat (existing path)
+      let pathStat;
+      try {
+        pathStat = await stat(targetPath);
+      } catch {
+        // stat failed — try smart resolution
+        const hasPathSep = targetPath.includes('/') || targetPath.includes('\\');
+        const hasExt = extname(targetPath) !== '';
+
+        if (!hasPathSep && !hasExt) {
+          // 3a. Looks like a UID (no extension, no path separator)
+          await pushByUIDs([targetPath], client, options, modifyKey, transactionKey);
+          return;
+        }
+
+        if (!hasPathSep) {
+          // 3b. Bare filename — search project
+          const matches = await findFileInProject(targetPath);
+          if (matches.length === 1) {
+            const resolved = matches[0];
+            log.dim(`  Found: ${relative(process.cwd(), resolved)}`);
+            const resolvedStat = await stat(resolved);
+            if (resolvedStat.isDirectory()) {
+              await pushDirectory(resolved, client, options, modifyKey, transactionKey);
+            } else {
+              await pushSingleFile(resolved, client, options, modifyKey, transactionKey);
+            }
+            return;
+          } else if (matches.length > 1) {
+            log.error(`Multiple matches for "${targetPath}":`);
+            for (const m of matches) {
+              log.plain(`  ${relative(process.cwd(), m)}`);
+            }
+            log.info('Please specify the full path.');
+            process.exit(1);
+          }
+        }
+
+        // No match found
+        log.error(`Path not found: "${targetPath}"`);
+        process.exit(1);
+      }
 
       if (pathStat.isDirectory()) {
         await pushDirectory(targetPath, client, options, modifyKey, transactionKey);
@@ -101,37 +171,16 @@ async function processPendingDeletes(client, options, modifyKey = null, transact
     try {
       const result = await client.postUrlEncoded('/api/input/submit', body);
 
-      // Retry with prompted params if needed
-      const errorResult = await checkSubmitErrors(result);
-      if (errorResult) {
-        if (errorResult.skipRecord) {
-          log.warn(`  Skipping deletion of "${entry.name}"`);
-          remaining.push(entry);
-          continue;
-        }
-        if (errorResult.skipAll) {
-          log.warn(`  Skipping deletion of "${entry.name}" and all remaining`);
-          remaining.push(entry);
-          // Push all remaining entries too
-          const currentIdx = sync.delete.indexOf(entry);
-          for (let i = currentIdx + 1; i < sync.delete.length; i++) {
-            remaining.push(sync.delete[i]);
-          }
-          break;
-        }
-        const params = errorResult.retryParams || errorResult;
-        Object.assign(extraParams, params);
-        const retryBody = await buildInputBody([entry.expression], extraParams);
-        const retryResponse = await client.postUrlEncoded('/api/input/submit', retryBody);
-        if (retryResponse.successful) {
-          log.success(`  Deleted "${entry.name}" from server`);
-          deletedUids.push(entry.UID);
-        } else {
-          log.error(`  Failed to delete "${entry.name}"`);
-          formatResponse(retryResponse, { json: options.json, jq: options.jq, verbose: options.verbose });
-          remaining.push(entry);
-        }
-      } else if (result.successful) {
+      // Deletes never require ticketing — treat ticket-only errors as success
+      const deleteMessages = (result.messages || result.data?.Messages || [])
+        .filter(m => typeof m === 'string');
+      const isTicketOnlyError = !result.successful
+        && deleteMessages.length > 0
+        && deleteMessages.every(m => m.includes('ticket_error') || m.includes('ticket_lookup'));
+      const deleteOk = result.successful || isTicketOnlyError;
+
+      if (deleteOk) {
+        if (isTicketOnlyError) log.dim('  (Ticket error ignored for delete)');
         log.success(`  Deleted "${entry.name}" from server`);
         deletedUids.push(entry.UID);
       } else {
@@ -222,6 +271,11 @@ async function moveWillDeleteToTrash(entry) {
       log.warn(`  Could not move to trash: ${from} — ${err.message}`);
     }
   }
+
+  // Re-apply trash icon if files were moved (self-heals after user clears trash)
+  if (filesToMove.length > 0) {
+    await ensureTrashIcon(trashDir);
+  }
 }
 
 /**
@@ -229,9 +283,15 @@ async function moveWillDeleteToTrash(entry) {
  */
 async function pushSingleFile(filePath, client, options, modifyKey = null, transactionKey = 'RowUID') {
   // Find the metadata file
-  const dir = dirname(filePath);
-  const base = basename(filePath, extname(filePath));
-  const metaPath = join(dir, `${base}.metadata.json`);
+  let metaPath;
+  if (filePath.endsWith('.metadata.json')) {
+    // User passed the metadata file directly — use it as-is
+    metaPath = filePath;
+  } else {
+    const dir = dirname(filePath);
+    const base = basename(filePath, extname(filePath));
+    metaPath = join(dir, `${base}.metadata.json`);
+  }
 
   let meta;
   try {
@@ -241,23 +301,88 @@ async function pushSingleFile(filePath, client, options, modifyKey = null, trans
     process.exit(1);
   }
 
+  // Toe-stepping check for single-file push
+  if (isToeStepping(options) && meta.UID) {
+    const baseline = await loadAppJsonBaseline();
+    if (baseline) {
+      const appConfig = await loadAppConfig();
+      const proceed = await checkToeStepping([{ meta, metaPath }], client, baseline, options, appConfig?.AppShortName);
+      if (!proceed) return;
+    }
+  }
+
   await pushFromMetadata(meta, metaPath, client, options, null, modifyKey, transactionKey);
 }
 
+/**
+ * Ensure manifest.json at project root has companion metadata in bins/app/.
+ * If manifest.json exists but no manifest*.metadata.json is in bins/app/,
+ * auto-create the metadata so the push flow picks it up.
+ */
+async function ensureManifestMetadata() {
+  // Check if manifest.json exists at project root
+  try {
+    await access(join(process.cwd(), 'manifest.json'));
+  } catch {
+    return; // No manifest.json — nothing to do
+  }
+
+  // Check if bins/app/ already has metadata that references @/manifest.json.
+  // A filename-only check (startsWith('manifest')) is insufficient because
+  // the metadata may have been renamed with a ~UID suffix or prefixed with
+  // __WILL_DELETE__.  Instead, scan actual metadata content for the reference.
+  const binsAppDir = join(process.cwd(), 'bins', 'app');
+  try {
+    const entries = await readdir(binsAppDir);
+    const metaEntries = entries.filter(e => e.endsWith('.metadata.json'));
+    for (const entry of metaEntries) {
+      try {
+        const raw = await readFile(join(binsAppDir, entry), 'utf8');
+        const parsed = JSON.parse(raw);
+        if (parsed.Content === '@/manifest.json') return; // Already tracked
+      } catch { /* skip unreadable files */ }
+    }
+  } catch {
+    // bins/app/ doesn't exist — will create it
+  }
+
+  // Auto-create manifest.metadata.json
+  const appConfig = await loadAppConfig();
+  const structure = await loadStructureFile();
+  const appBin = findBinByPath('app', structure);
+
+  await mkdir(binsAppDir, { recursive: true });
+
+  const meta = {
+    _entity: 'content',
+    _contentColumns: ['Content'],
+    Content: '@/manifest.json',
+    Path: 'manifest.json',
+    Name: 'manifest.json',
+    Extension: 'JSON',
+    Public: 1,
+    Active: 1,
+    Title: 'PWA Manifest',
+  };
+
+  if (appBin) meta.BinID = appBin.binId;
+  if (appConfig.AppID) meta.AppID = appConfig.AppID;
+
+  const metaPath = join(binsAppDir, 'manifest.metadata.json');
+  await writeFile(metaPath, JSON.stringify(meta, null, 2) + '\n');
+  log.info('Auto-created manifest.metadata.json for manifest.json');
+}
+
 /**
  * Push all records found in a directory (recursive)
  */
 async function pushDirectory(dirPath, client, options, modifyKey = null, transactionKey = 'RowUID') {
+  // Auto-create manifest.metadata.json if manifest.json exists at root without companion metadata
+  await ensureManifestMetadata();
+
   const ig = await loadIgnore();
   const metaFiles = await findMetadataFiles(dirPath, ig);
 
-  if (metaFiles.length === 0) {
-    log.warn(`No .metadata.json files found in "${dirPath}".`);
-    return;
-  }
-
-  log.info(`Found ${metaFiles.length} record(s) to push`);
-
   // Load baseline for delta detection
   const baseline = await loadAppJsonBaseline();
 
@@ -267,6 +392,7 @@ async function pushDirectory(dirPath, client, options, modifyKey = null, transac
 
   // Collect metadata with detected changes
   const toPush = [];
+  const outputCompoundFiles = [];
   let skipped = 0;
 
   for (const metaPath of metaFiles) {
@@ -279,18 +405,21 @@ async function pushDirectory(dirPath, client, options, modifyKey = null, transac
       continue;
     }
 
-    if (!meta.UID && !meta._id) {
-      log.warn(`Skipping "${metaPath}": no UID or _id found`);
+    if (!meta._entity) {
+      log.warn(`Skipping "${metaPath}": no _entity found`);
       skipped++;
       continue;
     }
 
-    if (!meta._entity) {
-      log.warn(`Skipping "${metaPath}": no _entity found`);
-      skipped++;
+    // Compound output files: handle root + all inline children together
+    // These have _entity='output' and inline children under .children
+    if (meta._entity === 'output' && meta.children) {
+      outputCompoundFiles.push({ meta, metaPath });
       continue;
     }
 
+    const isNewRecord = !meta.UID && !meta._id;
+
     // Verify @file references exist
     const contentCols = meta._contentColumns || [];
     let missingFiles = false;
@@ -329,9 +458,9 @@ async function pushDirectory(dirPath, client, options, modifyKey = null, transac
       if (contentIgnored) { skipped++; continue; }
     }
 
-    // Detect changed columns (delta detection)
+    // Detect changed columns (delta detection) — skip for new records
     let changedColumns = null;
-    if (baseline) {
+    if (!isNewRecord && baseline) {
       try {
         changedColumns = await detectChangedColumns(metaPath, baseline);
         if (changedColumns.length === 0) {
@@ -344,18 +473,56 @@ async function pushDirectory(dirPath, client, options, modifyKey = null, transac
       }
     }
 
-    toPush.push({ meta, metaPath, changedColumns });
+    toPush.push({ meta, metaPath, changedColumns, isNew: isNewRecord });
   }
 
-  if (toPush.length === 0) {
-    log.info('No changes to push');
+  // Toe-stepping: check for server-side conflicts before submitting
+  if (isToeStepping(options) && baseline && toPush.length > 0) {
+    const toCheck = toPush.filter(item => !item.isNew);
+    if (toCheck.length > 0) {
+      const appConfig = await loadAppConfig();
+      const proceed = await checkToeStepping(toCheck, client, baseline, options, appConfig?.AppShortName);
+      if (!proceed) return;
+    }
+  }
+
+  // ── Bin entity push: check if directory maps to a bin ──────────────
+  const binPushItems = [];
+  try {
+    const structure = await loadStructureFile();
+    const relDir = relative(process.cwd(), dirPath).replace(/\\/g, '/');
+    const binEntry = findBinByPath(relDir, structure);
+    if (binEntry && binEntry.uid && baseline) {
+      const changedBinCols = detectBinChanges(binEntry, baseline);
+      if (changedBinCols.length > 0) {
+        const appConfig = await loadAppConfig();
+        const binMeta = synthesizeBinMetadata(binEntry, appConfig.AppID);
+        binPushItems.push({ meta: binMeta, binEntry, changedColumns: changedBinCols });
+        log.info(`Bin "${binEntry.name}" has ${changedBinCols.length} changed column(s): ${changedBinCols.join(', ')}`);
+      }
+    }
+  } catch { /* structure file missing or bin lookup failed — skip */ }
+
+  if (toPush.length === 0 && outputCompoundFiles.length === 0 && binPushItems.length === 0) {
+    if (metaFiles.length === 0) {
+      log.warn(`No .metadata.json files found in "${dirPath}".`);
+    } else {
+      log.info('No changes to push');
+    }
     return;
   }
 
+  log.info(`Found ${metaFiles.length} record(s) to push`);
+
   // Pre-flight ticket validation (only if no --ticket flag)
-  if (!options.ticket && toPush.length > 0) {
-    const recordSummary = toPush.map(r => basename(r.metaPath, '.metadata.json')).join(', ');
-    const ticketCheck = await checkStoredTicket(options, `${toPush.length} record(s): ${recordSummary}`);
+  const totalRecords = toPush.length + outputCompoundFiles.length + binPushItems.length;
+  if (!options.ticket && totalRecords > 0) {
+    const recordSummary = [
+      ...toPush.map(r => basename(r.metaPath, '.metadata.json')),
+      ...outputCompoundFiles.map(r => basename(r.metaPath, '.json')),
+      ...binPushItems.map(r => `bin:${r.meta.Name}`),
+    ].join(', ');
+    const ticketCheck = await checkStoredTicket(options, `${totalRecords} record(s): ${recordSummary}`);
     if (ticketCheck.cancel) {
       log.info('Submission cancelled');
       return;
@@ -366,19 +533,48 @@ async function pushDirectory(dirPath, client, options, modifyKey = null, transac
     }
   }
 
-  // Sort by dependency level: children first (ascending level) for add/edit operations
-  toPush.sort((a, b) => {
+  // Separate new records (adds) from existing records (edits)
+  const toAdd = toPush.filter(item => item.isNew);
+  const toEdit = toPush.filter(item => !item.isNew);
+
+  // Sort each group by dependency level
+  const sortByDependency = (a, b) => {
     const levelA = ENTITY_DEPENDENCIES[a.meta._entity] || 0;
     const levelB = ENTITY_DEPENDENCIES[b.meta._entity] || 0;
     return levelA - levelB;
-  });
+  };
+  toAdd.sort(sortByDependency);
+  toEdit.sort(sortByDependency);
 
-  // Process in dependency order
   let succeeded = 0;
   let failed = 0;
   const successfulPushes = [];
 
-  for (const item of toPush) {
+  // Process adds first
+  if (toAdd.length > 0) {
+    log.info(`Adding ${toAdd.length} new record(s)...`);
+  }
+  for (const item of toAdd) {
+    try {
+      const success = await addFromMetadata(item.meta, item.metaPath, client, options, modifyKey);
+      if (success) {
+        succeeded++;
+        successfulPushes.push(item);
+      } else {
+        failed++;
+      }
+    } catch (err) {
+      if (err.message === 'SKIP_ALL') {
+        log.info('Skipping remaining records');
+        break;
+      }
+      log.error(`Failed to add: ${item.metaPath} — ${err.message}`);
+      failed++;
+    }
+  }
+
+  // Then process edits
+  for (const item of toEdit) {
     try {
       const success = await pushFromMetadata(item.meta, item.metaPath, client, options, item.changedColumns, modifyKey, transactionKey);
       if (success) {
@@ -397,6 +593,44 @@ async function pushDirectory(dirPath, client, options, modifyKey = null, transac
     }
   }
 
+  // Process compound output files (root + inline children)
+  for (const { meta, metaPath } of outputCompoundFiles) {
+    try {
+      const result = await pushOutputCompound(meta, metaPath, client, options, baseline, modifyKey, transactionKey);
+      if (result.pushed > 0) {
+        succeeded++;
+        successfulPushes.push({ meta, metaPath, changedColumns: null });
+      } else {
+        skipped++;
+      }
+    } catch (err) {
+      log.error(`Failed compound output push: ${metaPath} — ${err.message}`);
+      failed++;
+    }
+  }
+
+  // Process bin entity changes
+  for (const binItem of binPushItems) {
+    try {
+      // Synthesize a temporary metadata file path for pushFromMetadata
+      // (bin records have no .metadata.json — we pass the data inline)
+      const success = await pushBinEntity(binItem.meta, binItem.changedColumns, client, options, modifyKey, transactionKey);
+      if (success) {
+        succeeded++;
+      } else {
+        failed++;
+      }
+    } catch (err) {
+      log.error(`Failed bin push: ${binItem.meta.Name} — ${err.message}`);
+      failed++;
+    }
+  }
+
+  // Clear server cache so subsequent GETs (diff, pull, toe-stepping) return fresh data
+  if (successfulPushes.length > 0) {
+    await client.voidCache();
+  }
+
   // Update baseline after successful pushes
   if (baseline && successfulPushes.length > 0) {
     await updateBaselineAfterPush(baseline, successfulPushes);
@@ -405,6 +639,294 @@ async function pushDirectory(dirPath, client, options, modifyKey = null, transac
   log.info(`Push complete: ${succeeded} succeeded, ${failed} failed, ${skipped} skipped`);
 }
 
+/**
+ * Push a bin entity record (synthesized metadata, no .metadata.json file).
+ * Uses pushFromMetadata with a temporary in-memory metadata path.
+ */
+async function pushBinEntity(binMeta, changedColumns, client, options, modifyKey = null, transactionKey = 'RowUID') {
+  const entity = binMeta._entity;
+  const uid = binMeta.UID;
+  const id = binMeta._id;
+
+  // Determine row key
+  let rowKeyPrefix, rowKeyValue;
+  if (uid) {
+    rowKeyPrefix = 'RowUID';
+    rowKeyValue = uid;
+  } else if (id) {
+    rowKeyPrefix = 'RowID';
+    rowKeyValue = id;
+  } else {
+    log.warn(`Bin "${binMeta.Name}" has no UID or ID — skipping`);
+    return false;
+  }
+
+  const dataExprs = [];
+  for (const col of changedColumns) {
+    const value = binMeta[col];
+    const strValue = value !== null && value !== undefined ? String(value) : '';
+    dataExprs.push(`${rowKeyPrefix}:${rowKeyValue};column:${entity}.${col}=${strValue}`);
+  }
+
+  if (dataExprs.length === 0) {
+    log.warn(`Nothing to push for bin "${binMeta.Name}"`);
+    return false;
+  }
+
+  log.info(`Pushing bin "${binMeta.Name}" (${entity}:${rowKeyValue}) — ${dataExprs.length} changed field(s)`);
+
+  const extraParams = { '_confirm': options.confirm || 'true' };
+  if (options.ticket) extraParams['_OverrideTicketID'] = options.ticket;
+  if (modifyKey) extraParams['_modify_key'] = modifyKey;
+  const cachedUser = getSessionUserOverride();
+  if (cachedUser) extraParams['_OverrideUserID'] = cachedUser;
+
+  const body = await buildInputBody(dataExprs, extraParams);
+  const result = await client.postUrlEncoded('/api/input/submit', body);
+
+  formatResponse(result, { json: options.json, jq: options.jq, verbose: options.verbose });
+
+  if (!result.successful) {
+    return false;
+  }
+
+  log.success(`  Pushed bin "${binMeta.Name}"`);
+  return true;
+}
+
+/**
+ * Push records by UID(s). Searches metadata files and structure.json bins.
+ */
+async function pushByUIDs(uids, client, options, modifyKey = null, transactionKey = 'RowUID') {
+  const matches = await findByUID(uids);
+
+  if (matches.length === 0) {
+    log.error(`No records found for UID(s): ${uids.join(', ')}`);
+    process.exit(1);
+  }
+
+  // Report unmatched UIDs
+  const foundUids = new Set(matches.map(m => m.uid));
+  for (const uid of uids) {
+    if (!foundUids.has(uid)) {
+      log.warn(`UID not found: ${uid}`);
+    }
+  }
+
+  const baseline = await loadAppJsonBaseline();
+
+  // Toe-stepping check for UID-targeted push
+  if (isToeStepping(options) && baseline) {
+    const toCheck = [];
+    for (const match of matches) {
+      if (match.metaPath && match.meta) {
+        toCheck.push({ meta: match.meta, metaPath: match.metaPath });
+      }
+    }
+    if (toCheck.length > 0) {
+      const appConfig = await loadAppConfig();
+      const proceed = await checkToeStepping(toCheck, client, baseline, options, appConfig?.AppShortName);
+      if (!proceed) return;
+    }
+  }
+
+  let succeeded = 0;
+  let failed = 0;
+
+  for (const match of matches) {
+    if (match.metaPath) {
+      // Regular record — push via pushSingleFile path
+      try {
+        const success = await pushSingleFile(match.metaPath, client, options, modifyKey, transactionKey);
+        if (success !== false) succeeded++;
+        else failed++;
+      } catch (err) {
+        log.error(`Failed to push ${match.uid}: ${err.message}`);
+        failed++;
+      }
+    } else if (match.binEntry) {
+      // Bin entity — detect changes and push
+      try {
+        const changedCols = baseline
+          ? detectBinChanges(match.binEntry, baseline)
+          : ['Name', 'Path', 'ParentBinID'];
+
+        if (changedCols.length === 0) {
+          log.dim(`  Bin "${match.binEntry.name}" — no changes detected`);
+          continue;
+        }
+
+        const appConfig = await loadAppConfig();
+        const binMeta = synthesizeBinMetadata(match.binEntry, appConfig.AppID);
+        const success = await pushBinEntity(binMeta, changedCols, client, options, modifyKey, transactionKey);
+        if (success) succeeded++;
+        else failed++;
+      } catch (err) {
+        log.error(`Failed to push bin ${match.uid}: ${err.message}`);
+        failed++;
+      }
+    }
+  }
+
+  if (matches.length > 1) {
+    log.info(`Push complete: ${succeeded} succeeded, ${failed} failed`);
+  }
+}
+
+/**
+ * Submit a new record (add) from metadata that has no UID yet.
+ * Builds RowID:add1 expressions, submits, then renames files with the returned ~UID.
+ */
+async function addFromMetadata(meta, metaPath, client, options, modifyKey = null) {
+  const entity = meta._entity;
+  const contentCols = new Set(meta._contentColumns || []);
+  const metaDir = dirname(metaPath);
+
+  const dataExprs = [];
+  const addIndex = 1;
+
+  for (const [key, value] of Object.entries(meta)) {
+    if (shouldSkipColumn(key)) continue;
+    if (key === 'UID') continue;
+    if (value === null || value === undefined) continue;
+
+    const strValue = String(value);
+
+    if (strValue.startsWith('@')) {
+      const refFile = strValue.substring(1);
+      const refPath = resolveAtReference(refFile, metaDir);
+      dataExprs.push(`RowID:add${addIndex};column:${entity}.${key}@${refPath}`);
+    } else {
+      dataExprs.push(`RowID:add${addIndex};column:${entity}.${key}=${strValue}`);
+    }
+  }
+
+  if (dataExprs.length === 0) {
+    log.warn(`Nothing to submit for ${basename(metaPath)}`);
+    return false;
+  }
+
+  log.info(`Adding ${basename(metaPath)} (${entity}) — ${dataExprs.length} field(s)`);
+
+  // Apply stored ticket — add operations always use RowID (not RowUID)
+  let storedTicket = null;
+  if (!options.ticket) {
+    const globalTicket = await (await import('../lib/ticketing.js')).getGlobalTicket();
+    if (globalTicket) {
+      dataExprs.push(`RowID:add${addIndex};column:${entity}._LastUpdatedTicketID=${globalTicket}`);
+      log.dim(`  Applying ticket: ${globalTicket}`);
+      storedTicket = globalTicket;
+    }
+  }
+
+  const extraParams = { '_confirm': options.confirm || 'true' };
+  if (options.ticket) extraParams['_OverrideTicketID'] = options.ticket;
+  else if (storedTicket) extraParams['_OverrideTicketID'] = storedTicket;
+  if (modifyKey) extraParams['_modify_key'] = modifyKey;
+  const cachedUser = getSessionUserOverride();
+  if (cachedUser) extraParams['_OverrideUserID'] = cachedUser;
+
+  let body = await buildInputBody(dataExprs, extraParams);
+  let result = await client.postUrlEncoded('/api/input/submit', body);
+
+  // Reactive ModifyKey retry
+  if (!result.successful && result.messages?.some(m => isModifyKeyError(m))) {
+    const retryMK = await handleModifyKeyError();
+    if (retryMK.cancel) { log.info('Submission cancelled'); return false; }
+    extraParams['_modify_key'] = retryMK.modifyKey;
+    body = await buildInputBody(dataExprs, extraParams);
+    result = await client.postUrlEncoded('/api/input/submit', body);
+  }
+
+  // Retry with prompted params if needed
+  const retryResult = await checkSubmitErrors(result);
+  if (retryResult) {
+    if (retryResult.skipRecord) { log.warn('  Skipping record'); return false; }
+    if (retryResult.skipAll) throw new Error('SKIP_ALL');
+    if (retryResult.ticketExpressions?.length > 0) dataExprs.push(...retryResult.ticketExpressions);
+    const params = retryResult.retryParams || retryResult;
+    Object.assign(extraParams, params);
+    body = await buildInputBody(dataExprs, extraParams);
+    result = await client.postUrlEncoded('/api/input/submit', body);
+  }
+
+  if (!result.successful) {
+    const msgs = result.messages || result.data?.Messages || [];
+    log.error(`Add failed for ${basename(metaPath)}`);
+    if (msgs.length > 0) {
+      for (const m of msgs) log.dim(`  ${typeof m === 'string' ? m : JSON.stringify(m)}`);
+    }
+    return false;
+  }
+
+  // Extract UID from response and rename files to ~uid convention
+  const addResults = result.payload?.Results?.Add || result.data?.Payload?.Results?.Add || [];
+  if (addResults.length > 0) {
+    const returnedUID = addResults[0].UID;
+    const returnedLastUpdated = addResults[0]._LastUpdated;
+
+    if (returnedUID) {
+      meta.UID = returnedUID;
+
+      // Store numeric ID for delete operations (RowID:del<id>)
+      const entityIdKey = entity.charAt(0).toUpperCase() + entity.slice(1) + 'ID';
+      const returnedId = addResults[0][entityIdKey] || addResults[0]._id || addResults[0].ID;
+      if (returnedId) meta._id = returnedId;
+
+      const currentMetaBase = basename(metaPath, '.metadata.json');
+
+      // Guard: don't append UID if it's already in the filename
+      if (hasUidInFilename(currentMetaBase, returnedUID)) {
+        await writeFile(metaPath, JSON.stringify(meta, null, 2) + '\n');
+        log.success(`UID ${returnedUID} already in filename`);
+        return true;
+      }
+
+      const newBase = buildUidFilename(currentMetaBase, returnedUID);
+      const newMetaPath = join(metaDir, `${newBase}.metadata.json`);
+
+      // Update @references in metadata to include ~UID for non-root references
+      for (const col of (meta._contentColumns || [])) {
+        const ref = meta[col];
+        if (ref && String(ref).startsWith('@') && !String(ref).startsWith('@/')) {
+          // Local file reference — rename it too
+          const oldRefFile = String(ref).substring(1);
+          const refExt = extname(oldRefFile);
+          const refBase = basename(oldRefFile, refExt);
+          const newRefBase = buildUidFilename(refBase, returnedUID);
+          const newRefFile = refExt ? `${newRefBase}${refExt}` : newRefBase;
+
+          const oldRefPath = join(metaDir, oldRefFile);
+          const newRefPath = join(metaDir, newRefFile);
+          try {
+            await fsRename(oldRefPath, newRefPath);
+            meta[col] = `@${newRefFile}`;
+          } catch { /* content file may be root-relative */ }
+        }
+      }
+
+      // Rename old metadata file, then write updated content
+      if (metaPath !== newMetaPath) {
+        try { await fsRename(metaPath, newMetaPath); } catch { /* ignore if same */ }
+      }
+      await writeFile(newMetaPath, JSON.stringify(meta, null, 2) + '\n');
+
+      // Set timestamps from server
+      const config = await loadConfig();
+      const serverTz = config.ServerTimezone;
+      if (serverTz && returnedLastUpdated) {
+        try {
+          await setFileTimestamps(newMetaPath, returnedLastUpdated, returnedLastUpdated, serverTz);
+        } catch { /* non-critical */ }
+      }
+
+      log.success(`Added: ${basename(metaPath)} → UID ${returnedUID}`);
+    }
+  }
+
+  return true;
+}
+
 /**
  * Build and submit input expressions from a metadata object
  * @param {Object} meta - Metadata object
@@ -421,40 +943,37 @@ async function pushFromMetadata(meta, metaPath, client, options, changedColumns
   const contentCols = new Set(meta._contentColumns || []);
   const metaDir = dirname(metaPath);
 
-  // Determine the row key prefix and value based on the preset
+  // Determine the row key. TransactionKeyPreset only applies when the record
+  // carries a UID column (core assets). Data records without a UID always use
+  // RowID directly — no preset, no fallback warning.
   let rowKeyPrefix, rowKeyValue;
-  if (transactionKey === 'RowID') {
-    if (id) {
+  const hasUid = uid != null && uid !== '';
+
+  if (hasUid) {
+    // Core asset: honour the TransactionKeyPreset
+    if (transactionKey === 'RowID') {
+      if (!id) throw new Error(`No _id found in ${basename(metaPath)} — required when TransactionKeyPreset is RowID`);
       rowKeyPrefix = 'RowID';
       rowKeyValue = id;
     } else {
-      log.warn(`  ⚠  Preset is RowID but no _id found in ${basename(metaPath)} — falling back to RowUID`);
+      // RowUID (default)
       rowKeyPrefix = 'RowUID';
       rowKeyValue = uid;
     }
   } else {
-    if (uid) {
-      rowKeyPrefix = 'RowUID';
-      rowKeyValue = uid;
-    } else if (id) {
-      log.warn(`  ⚠  Preset is RowUID but no UID found in ${basename(metaPath)} — falling back to RowID`);
-      rowKeyPrefix = 'RowID';
-      rowKeyValue = id;
-    }
-  }
-
-  if (!rowKeyValue) {
-    throw new Error(`No UID or _id found in ${metaPath}`);
+    // Data record: no UID column — always RowID
+    if (!id) throw new Error(`No UID or _id found in ${metaPath}`);
+    rowKeyPrefix = 'RowID';
+    rowKeyValue = id;
   }
   if (!entity) {
     throw new Error(`No _entity found in ${metaPath}`);
   }
 
-  // Detect path mismatch (only for content, media, output, bin entities —
-  // entity-dir types use structural directories unrelated to server Path)
-  if (meta.Path) {
-    await checkPathMismatch(meta, metaPath, entity, options);
-  }
+  // Path mismatch check disabled: the metadata Path column reflects the
+  // server-side path and must not be overwritten by local directory structure.
+  // Local bin/lib directory placement is an organizational choice independent
+  // of the server Path value.
 
   const dataExprs = [];
   let metaUpdated = false;
@@ -466,7 +985,10 @@ async function pushFromMetadata(meta, metaPath, client, options, changedColumns
     if (shouldSkipColumn(key)) continue;
     if (key === 'UID') continue; // UID is the identifier, not a column to update
     if (key === 'children') continue; // Output hierarchy structural field, not a server column
-    if (value === null || value === undefined) continue;
+
+    // Skip null/undefined values UNLESS delta detected them as changed
+    // (user explicitly set a column to null to clear it on server)
+    if ((value === null || value === undefined) && !(columnsToProcess && columnsToProcess.has(key))) continue;
 
     // Delta sync: skip columns not in changedColumns
     if (columnsToProcess && !columnsToProcess.has(key)) continue;
@@ -478,7 +1000,8 @@ async function pushFromMetadata(meta, metaPath, client, options, changedColumns
     // --content-only: skip non-content columns
     if (options.contentOnly && !isContentCol) continue;
 
-    const strValue = String(value);
+    // Null values that passed delta check → send as empty string to clear on server
+    const strValue = (value === null || value === undefined) ? '' : String(value);
 
     if (strValue.startsWith('@')) {
       // @filename reference — resolve to actual file path
@@ -800,6 +1323,194 @@ async function checkPathMismatch(meta, metaPath, entity, options) {
   }
 }
 
+// ─── Compound Output Push ───────────────────────────────────────────────────
+
+const _COMPOUND_DOC_KEYS = ['column', 'join', 'filter'];
+
+/**
+ * Push a compound output file (root + inline children) to the server.
+ * Handles delta detection, dependency ordering, FK preservation,
+ * CustomSQL @reference resolution, and root _lastUpdated stamping.
+ *
+ * @param {Object} meta - Parsed root output JSON
+ * @param {string} metaPath - Absolute path to root output JSON file
+ * @param {DboClient} client - API client
+ * @param {Object} options - Push options
+ * @param {Object} baseline - Loaded baseline
+ * @param {string|null} modifyKey - ModifyKey value
+ * @param {string} transactionKey - RowUID or RowID
+ * @returns {Promise<{ pushed: number }>} - Count of entities pushed
+ */
+async function pushOutputCompound(meta, metaPath, client, options, baseline, modifyKey = null, transactionKey = 'RowUID') {
+  const metaDir = dirname(metaPath);
+
+  // Delta detection for compound output
+  let rootChanges, childChanges;
+  if (baseline) {
+    try {
+      const delta = await detectOutputChanges(metaPath, baseline);
+      rootChanges = delta.root;
+      childChanges = delta.children;
+    } catch (err) {
+      log.warn(`Compound output delta detection failed for ${metaPath}: ${err.message} — performing full push`);
+      rootChanges = getAllUserColumns(meta);
+      childChanges = null; // null = push all children
+    }
+  } else {
+    rootChanges = getAllUserColumns(meta);
+    childChanges = null;
+  }
+
+  const totalChanges = rootChanges.length +
+    (childChanges ? Object.values(childChanges).reduce((s, c) => s + c.length, 0) : 999);
+
+  if (totalChanges === 0) {
+    log.dim(`  Skipping ${basename(metaPath)} — no changes detected`);
+    return { pushed: 0 };
+  }
+
+  // Flatten all inline children with depth annotation
+  const allChildren = [];
+  _flattenOutputChildren(meta.children || {}, allChildren);
+
+  // Separate adds (no baseline entry) from edits
+  const adds = [];
+  const edits = [];
+  for (const child of allChildren) {
+    const entry = baseline ? findBaselineEntry(baseline, child._entity, child.UID) : null;
+    const changes = childChanges ? (childChanges[child.UID] || []) : getAllUserColumns(child);
+    if (!entry) {
+      adds.push({ child, changes: getAllUserColumns(child) });
+    } else if (changes.length > 0) {
+      edits.push({ child, changes });
+    }
+  }
+
+  // Check if root itself is new
+  const rootEntry = baseline ? findBaselineEntry(baseline, 'output', meta.UID) : null;
+  const rootIsNew = !rootEntry;
+
+  let pushed = 0;
+
+  // EDIT ORDER: deepest children first (highest _depth)
+  edits.sort((a, b) => b.child._depth - a.child._depth);
+  for (const { child, changes } of edits) {
+    const success = await _submitOutputEntity(child, child._entity, changes, metaDir, client, options, modifyKey, transactionKey);
+    if (success) pushed++;
+  }
+
+  // ADD ORDER: root first (if new), then children shallowest→deepest
+  if (rootIsNew && rootChanges.length > 0) {
+    const success = await _submitOutputEntity(meta, 'output', rootChanges, metaDir, client, options, modifyKey, transactionKey);
+    if (success) pushed++;
+  }
+  adds.sort((a, b) => a.child._depth - b.child._depth);
+  for (const { child, changes } of adds) {
+    const success = await _submitOutputEntity(child, child._entity, changes, metaDir, client, options, modifyKey, transactionKey);
+    if (success) pushed++;
+  }
+
+  // Always update root (with _lastUpdated) — submit root changes or just touch it
+  if (!rootIsNew && (rootChanges.length > 0 || edits.length > 0 || adds.length > 0)) {
+    const success = await _submitOutputEntity(meta, 'output', rootChanges.length > 0 ? rootChanges : ['Name'], metaDir, client, options, modifyKey, transactionKey);
+    if (success) pushed++;
+  }
+
+  log.info(`Compound output push: ${basename(metaPath)} — ${pushed} entity submission(s)`);
+  return { pushed };
+}
+
+/**
+ * Flatten children object ({ column, join, filter }) into a flat array.
+ * Annotates each child with _depth (1 = direct child of root, 2 = grandchild, etc.)
+ */
+function _flattenOutputChildren(childrenObj, result, depth = 1) {
+  for (const docKey of _COMPOUND_DOC_KEYS) {
+    const entityArray = childrenObj[docKey];
+    if (!Array.isArray(entityArray) || entityArray.length === 0) continue;
+    for (const child of entityArray) {
+      child._depth = depth;
+      result.push(child);
+      if (child.children) _flattenOutputChildren(child.children, result, depth + 1);
+    }
+  }
+}
+
+/**
+ * Submit a single output hierarchy entity to the server.
+ * Resolves @reference values, builds data expressions, and submits.
+ */
+async function _submitOutputEntity(entity, physicalEntity, changedColumns, metaDir, client, options, modifyKey, transactionKey) {
+  const uid = entity.UID;
+  if (!uid) {
+    log.warn(`  Output entity ${physicalEntity} has no UID — skipping`);
+    return false;
+  }
+
+  const rowKeyPrefix = transactionKey === 'RowID' && entity._id ? 'RowID' : 'RowUID';
+  const rowKeyValue = rowKeyPrefix === 'RowID' ? entity._id : uid;
+
+  const dataExprs = [];
+
+  for (const col of changedColumns) {
+    if (shouldSkipColumn(col)) continue;
+    if (col === 'UID' || col === 'children') continue;
+
+    const val = entity[col];
+
+    // Null values in changedColumns → send empty string to clear on server
+    const strValue = (val === null || val === undefined) ? '' : String(val);
+    if (isReference(strValue)) {
+      const refPath = resolveReferencePath(strValue, metaDir);
+      dataExprs.push(`${rowKeyPrefix}:${rowKeyValue};column:${physicalEntity}.${col}@${refPath}`);
+    } else {
+      dataExprs.push(`${rowKeyPrefix}:${rowKeyValue};column:${physicalEntity}.${col}=${strValue}`);
+    }
+  }
+
+  if (dataExprs.length === 0) return false;
+
+  log.info(`  Pushing ${physicalEntity}:${uid} — ${dataExprs.length} field(s)`);
+
+  const storedTicket = await applyStoredTicketToSubmission(dataExprs, physicalEntity, uid, uid, options);
+
+  const extraParams = { '_confirm': options.confirm || 'true' };
+  if (options.ticket) extraParams['_OverrideTicketID'] = options.ticket;
+  else if (storedTicket) extraParams['_OverrideTicketID'] = storedTicket;
+  if (modifyKey) extraParams['_modify_key'] = modifyKey;
+  const cachedUser = getSessionUserOverride();
+  if (cachedUser) extraParams['_OverrideUserID'] = cachedUser;
+
+  const body = await buildInputBody(dataExprs, extraParams);
+  let result = await client.postUrlEncoded('/api/input/submit', body);
+
+  // Reactive ModifyKey retry
+  if (!result.successful && result.messages?.some(m => isModifyKeyError(m))) {
+    const retryMK = await handleModifyKeyError();
+    if (retryMK.cancel) { log.info('Submission cancelled'); return false; }
+    extraParams['_modify_key'] = retryMK.modifyKey;
+    const retryBody = await buildInputBody(dataExprs, extraParams);
+    result = await client.postUrlEncoded('/api/input/submit', retryBody);
+  }
+
+  formatResponse(result, { json: options.json, jq: options.jq, verbose: options.verbose });
+
+  if (!result.successful) return false;
+
+  // Update metadata _LastUpdated from server response
+  try {
+    const editResults = result.payload?.Results?.Edit || result.data?.Payload?.Results?.Edit || [];
+    if (editResults.length > 0) {
+      const updated = editResults[0]._LastUpdated || editResults[0].LastUpdated;
+      if (updated) entity._LastUpdated = updated;
+    }
+  } catch { /* non-critical */ }
+
+  return true;
+}
+
+// ─── Baseline Update ────────────────────────────────────────────────────────
+
 /**
  * Update baseline file (.app.json) after successful pushes.
  * Syncs changed column values and timestamps from metadata to baseline.
@@ -814,11 +1525,14 @@ async function updateBaselineAfterPush(baseline, successfulPushes) {
     const uid = meta.UID || meta._id;
     const entity = meta._entity;
 
-    // Find the baseline entry
-    const baselineEntry = findBaselineEntry(baseline, entity, uid);
+    // Find or create the baseline entry
+    let baselineEntry = findBaselineEntry(baseline, entity, uid);
     if (!baselineEntry) {
-      log.warn(`  Baseline entry not found for ${entity}:${uid} — skipping baseline update`);
-      continue;
+      // New record (from add) — insert into baseline
+      if (!baseline.children) baseline.children = {};
+      if (!Array.isArray(baseline.children[entity])) baseline.children[entity] = [];
+      baselineEntry = { UID: uid };
+      baseline.children[entity].push(baselineEntry);
     }
 
     // Update _LastUpdated and _LastUpdatedUserID from metadata
@@ -836,7 +1550,13 @@ async function updateBaselineAfterPush(baseline, successfulPushes) {
 
     for (const col of columnsToUpdate) {
       const value = meta[col];
-      if (value === null || value === undefined) continue;
+
+      // Null/undefined values: store null in baseline (field was cleared)
+      if (value === null || value === undefined) {
+        baselineEntry[col] = null;
+        modified = true;
+        continue;
+      }
 
       const strValue = String(value);