@dboio/cli 0.11.3 → 0.13.2

package/src/commands/diff.js

@@ -14,6 +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 { runPendingMigrations } from '../lib/migrations.js';
 
 export const diffCommand = new Command('diff')
@@ -239,6 +240,9 @@ async function resolveTargetToMetaFiles(targetPath) {
       await stat(mediaMetaPath);
       return [mediaMetaPath];
     } catch {
+      // Fallback: scan sibling metadata files for @reference match
+      const found = await findMetadataForCompanion(targetPath);
+      if (found) return [found];
       log.warn(`No metadata found for "${targetPath}"`);
       return [];
     }

package/src/commands/init.js

@@ -1,5 +1,5 @@
 import { Command } from 'commander';
-import { mkdir } from 'fs/promises';
+import { mkdir, writeFile, access } from 'fs/promises';
 import { join } from 'path';
 import { isInitialized, hasLegacyConfig, readLegacyConfig, initConfig, saveCredentials, ensureGitignore, saveTransactionKeyPreset, saveTicketSuggestionOutput } from '../lib/config.js';
 import { installOrUpdateClaudeCommands } from './install.js';
@@ -102,7 +102,7 @@ export const initCommand = new Command('init')
       }
 
       // Ensure sensitive files are gitignored
-      await ensureGitignore(['.dbo/credentials.json', '.dbo/cookies.txt', '.dbo/config.local.json', '.dbo/ticketing.local.json', '.dbo/errors.log', 'trash/', 'Icon\\r']);
+      await ensureGitignore(['.dbo/credentials.json', '.dbo/cookies.txt', '.dbo/config.local.json', '.dbo/ticketing.local.json', '.dbo/scripts.local.json', '.dbo/errors.log', 'trash/', 'Icon\\r']);
 
       const createdIgnore = await createDboignore();
       if (createdIgnore) log.dim('  Created .dboignore');
@@ -114,6 +114,20 @@ export const initCommand = new Command('init')
       }
       log.dim('  Created .claude/ directory structure');
 
+      // Create empty scripts.json and scripts.local.json if they don't exist
+      const emptyScripts = JSON.stringify({ scripts: {}, targets: {}, entities: {} }, null, 2) + '\n';
+      const dboDir = join(process.cwd(), '.dbo');
+      const scriptsPath = join(dboDir, 'scripts.json');
+      const scriptsLocalPath = join(dboDir, 'scripts.local.json');
+      try { await access(scriptsPath); } catch {
+        await writeFile(scriptsPath, emptyScripts);
+        log.dim('  Created .dbo/scripts.json');
+      }
+      try { await access(scriptsLocalPath); } catch {
+        await writeFile(scriptsLocalPath, emptyScripts);
+        log.dim('  Created .dbo/scripts.local.json');
+      }
+
       log.success(`Initialized .dbo/ for ${domain}`);
 
       // Authenticate early so the session is ready for subsequent operations

package/src/commands/input.js

@@ -60,8 +60,10 @@ export const inputCommand = new Command('input')
       if (modifyKeyResult.modifyKey) extraParams['_modify_key'] = modifyKeyResult.modifyKey;
 
       // Check if data expressions include AppID; if not and config has one, prompt
+      // Skip AppID prompt for delete-only submissions — deletes don't need it
       const allDataText = options.data.join(' ');
-      const hasAppId = /\.AppID[=@]/.test(allDataText) || /AppID=/.test(allDataText);
+      const isDeleteOnly = options.data.every(d => /RowID:del\d+/.test(d));
+      const hasAppId = isDeleteOnly || /\.AppID[=@]/.test(allDataText) || /AppID=/.test(allDataText);
       if (!hasAppId) {
         const appConfig = await loadAppConfig();
         if (appConfig.AppID) {

package/src/commands/mv.js

@@ -13,6 +13,7 @@ import {
   BINS_DIR
 } from '../lib/structure.js';
 import { findMetadataFiles } from '../lib/diff.js';
+import { findMetadataForCompanion } from '../lib/filenames.js';
 import { runPendingMigrations } from '../lib/migrations.js';
 
 export const mvCommand = new Command('mv')
@@ -507,14 +508,21 @@ async function checkNameConflict(fileName, targetDir, options) {
  */
 async function mvFile(sourceFile, targetBinId, structure, options) {
   // Resolve metadata
-  const metaPath = resolveMetaPath(sourceFile);
+  let metaPath = resolveMetaPath(sourceFile);
   let meta;
   try {
     meta = JSON.parse(await readFile(metaPath, 'utf8'));
   } catch {
-    log.error(`No metadata found for "${sourceFile}"`);
-    log.dim('  Use "dbo content pull" or "dbo output --save" to create metadata files.');
-    process.exit(1);
+    const found = await findMetadataForCompanion(sourceFile);
+    if (found) {
+      metaPath = found;
+      try { meta = JSON.parse(await readFile(metaPath, 'utf8')); } catch {}
+    }
+    if (!meta) {
+      log.error(`No metadata found for "${basename(sourceFile)}"`);
+      log.dim('  Use "dbo pull" to create metadata files.');
+      process.exit(1);
+    }
   }
 
   const entity = meta._entity;

package/src/commands/push.js

@@ -6,12 +6,13 @@ import { buildInputBody, checkSubmitErrors, getSessionUserOverride } from '../li
 import { formatResponse, formatError } from '../lib/formatter.js';
 import { log } from '../lib/logger.js';
 import { shouldSkipColumn } from '../lib/columns.js';
-import { loadConfig, loadAppConfig, loadSynchronize, saveSynchronize, loadAppJsonBaseline, saveAppJsonBaseline, hasBaseline } from '../lib/config.js';
+import { loadConfig, loadAppConfig, loadSynchronize, saveSynchronize, loadAppJsonBaseline, saveAppJsonBaseline, hasBaseline, loadScripts, loadScriptsLocal } from '../lib/config.js';
+import { mergeScriptsConfig, resolveHooks, buildHookEnv, runBuildLifecycle, runPushLifecycle } from '../lib/scripts.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, buildUidFilename } from '../lib/filenames.js';
+import { stripUidFromFilename, renameToUidConvention, hasUidInFilename, findMetadataForCompanion } from '../lib/filenames.js';
 import { findMetadataFiles, findFileInProject, findByUID } from '../lib/diff.js';
 import { loadIgnore } from '../lib/ignore.js';
 import { detectChangedColumns, findBaselineEntry, detectOutputChanges, getAllUserColumns, isReference, resolveReferencePath, detectBinChanges, synthesizeBinMetadata } from '../lib/delta.js';
@@ -19,6 +20,7 @@ import { BINS_DIR, ENTITY_DIR_NAMES, loadStructureFile, findBinByPath } from '..
 import { ensureTrashIcon } from '../lib/folder-icon.js';
 import { checkToeStepping } from '../lib/toe-stepping.js';
 import { runPendingMigrations } from '../lib/migrations.js';
+import { findUnaddedFiles, detectBinFile, submitAdd } from './add.js';
 
 /**
  * Resolve an @reference file path to an absolute filesystem path.
@@ -42,9 +44,16 @@ function isToeStepping(options) {
 
 import { ENTITY_DEPENDENCIES } from '../lib/dependencies.js';
 
+async function loadAndMergeScripts() {
+  const base = await loadScripts();
+  const local = await loadScriptsLocal();
+  if (!base && !local) return null;
+  return mergeScriptsConfig(base, local);
+}
+
 export const pushCommand = new Command('push')
   .description('Push local files back to DBO.io using metadata from pull')
-  .argument('<path>', 'File or directory to push')
+  .argument('[path]', 'File or directory to push (default: current directory)')
   .option('-C, --confirm <value>', 'Commit: true (default) or false', 'true')
   .option('--ticket <id>', 'Override ticket ID')
   .option('--modify-key <key>', 'Provide ModifyKey directly (skips interactive prompt)')
@@ -58,7 +67,9 @@ export const pushCommand = new Command('push')
   .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) => {
+  .option('--no-scripts', 'Bypass all script hooks; run default push pipeline unconditionally')
+  .option('--no-build', 'Skip the build phase (prebuild/build/postbuild); run push phase only')
+  .action(async (targetPath = ".", options) => {
     try {
       await runPendingMigrations(options);
       const client = new DboClient({ domain: options.domain, verbose: options.verbose });
@@ -169,18 +180,29 @@ async function processPendingDeletes(client, options, modifyKey = null, transact
     const body = await buildInputBody([entry.expression], extraParams);
 
     try {
-      const result = await client.postUrlEncoded('/api/input/submit', body);
-
-      // 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)');
+      let result = await client.postUrlEncoded('/api/input/submit', body);
+
+      // Retry with prompted params if needed (ticket, repo mismatch, user)
+      if (!result.successful) {
+        const retryResult = await checkSubmitErrors(result, { rowUid: entry.UID });
+        if (retryResult) {
+          if (retryResult.skipRecord) { remaining.push(entry); continue; }
+          if (retryResult.skipAll) break;
+          if (retryResult.ticketExpressions?.length > 0) {
+            // Re-build body with ticket expressions added to the delete expression
+            const allExprs = [entry.expression, ...retryResult.ticketExpressions];
+            const retryParams = { ...extraParams, ...(retryResult.retryParams || retryResult) };
+            const retryBody = await buildInputBody(allExprs, retryParams);
+            result = await client.postUrlEncoded('/api/input/submit', retryBody);
+          } else {
+            const retryParams = { ...extraParams, ...(retryResult.retryParams || retryResult) };
+            const retryBody = await buildInputBody([entry.expression], retryParams);
+            result = await client.postUrlEncoded('/api/input/submit', retryBody);
+          }
+        }
+      }
+
+      if (result.successful) {
         log.success(`  Deleted "${entry.name}" from server`);
         deletedUids.push(entry.UID);
       } else {
@@ -297,8 +319,35 @@ async function pushSingleFile(filePath, client, options, modifyKey = null, trans
   try {
     meta = JSON.parse(await readFile(metaPath, 'utf8'));
   } catch {
-    log.error(`No metadata found at "${metaPath}". Pull the record first with "dbo content pull" or "dbo output --save".`);
-    process.exit(1);
+    // Direct metadata path not found — search by @reference
+    const found = await findMetadataForCompanion(filePath);
+    if (found) {
+      metaPath = found;
+      try { meta = JSON.parse(await readFile(metaPath, 'utf8')); } catch {}
+    }
+    if (!meta) {
+      // Try auto-detecting as a bin content/media file and add it first
+      const binMeta = await detectBinFile(filePath);
+      if (binMeta) {
+        log.info(`No metadata found — auto-adding "${basename(filePath)}" first`);
+        try {
+          await submitAdd(binMeta.meta, binMeta.metaPath, filePath, client, options);
+          // After successful add, re-read the metadata (now has UID)
+          metaPath = binMeta.metaPath;
+          // The metadata file may have been renamed with ~UID, so scan for it
+          const updatedMeta = await findMetadataForCompanion(filePath);
+          if (updatedMeta) metaPath = updatedMeta;
+          meta = JSON.parse(await readFile(metaPath, 'utf8'));
+          log.info(`Successfully added — now pushing updates`);
+        } catch (err) {
+          log.error(`Auto-add failed for "${basename(filePath)}": ${err.message}`);
+          process.exit(1);
+        }
+      } else {
+        log.error(`No metadata found for "${basename(filePath)}". Pull the record first with "dbo pull".`);
+        process.exit(1);
+      }
+    }
   }
 
   // Toe-stepping check for single-file push
@@ -311,6 +360,41 @@ async function pushSingleFile(filePath, client, options, modifyKey = null, trans
     }
   }
 
+  // ── Script hooks ────────────────────────────────────────────────────
+  if (options.scripts !== false) {
+    const scriptsConfig = await loadAndMergeScripts();
+    if (scriptsConfig) {
+      const relPath = relative(process.cwd(), filePath).replace(/\\/g, '/');
+      const entityType = meta._entity || '';
+      const hooks = resolveHooks(relPath, entityType, scriptsConfig);
+      const cfg = await loadConfig();
+      const app = await loadAppConfig();
+      const env = buildHookEnv(relPath, entityType, { ...app, domain: cfg.domain });
+
+      // Build phase
+      if (options.build !== false && (hooks.prebuild !== undefined || hooks.build !== undefined || hooks.postbuild !== undefined)) {
+        log.dim(`  Running build hooks for ${basename(filePath)}...`);
+        const buildOk = await runBuildLifecycle(hooks, env, process.cwd());
+        if (!buildOk) {
+          log.error(`Build hook failed for "${basename(filePath)}" — aborting push`);
+          process.exit(1);
+        }
+      }
+
+      // Push phase
+      const pushResult = await runPushLifecycle(hooks, env, process.cwd());
+      if (pushResult.failed) {
+        log.error(`Push hook failed for "${basename(filePath)}" — aborting`);
+        process.exit(1);
+      }
+      if (!pushResult.runDefault) {
+        log.dim(`  Skipped default push for "${basename(filePath)}" (custom push hook handled it)`);
+        return;
+      }
+    }
+  }
+  // ── End script hooks ────────────────────────────────────────────────
+
   await pushFromMetadata(meta, metaPath, client, options, null, modifyKey, transactionKey);
 }
 /**
@@ -328,13 +412,16 @@ async function ensureManifestMetadata() {
 
   // Scan the entire project for any metadata file that already references manifest.json.
   // This prevents creating duplicates when the metadata lives in an unexpected location.
+  // Check both @/manifest.json (root-relative) and @manifest.json (local) references,
+  // as well as Path: manifest.json which indicates a server record for this file.
   const ig = await loadIgnore();
   const allMeta = await findMetadataFiles(process.cwd(), ig);
   for (const metaPath of allMeta) {
     try {
       const raw = await readFile(metaPath, 'utf8');
       const parsed = JSON.parse(raw);
-      if (parsed.Content === '@/manifest.json') return; // Already tracked
+      if (parsed.Content === '@/manifest.json' || parsed.Content === '@manifest.json') return;
+      if (parsed.Path === 'manifest.json' || parsed.Path === '/manifest.json') return;
     } catch { /* skip unreadable */ }
   }
 
@@ -373,10 +460,116 @@ async function pushDirectory(dirPath, client, options, modifyKey = null, transac
   // Auto-create manifest.metadata.json if manifest.json exists at root without companion metadata
   await ensureManifestMetadata();
 
+  // ── Auto-add: detect un-added files and create+submit them before push ──
   const ig = await loadIgnore();
+  const justAddedUIDs = new Set(); // Track UIDs added in this invocation — skip from push loop
+
+  const unadded = await findUnaddedFiles(dirPath, ig);
+  if (unadded.length > 0) {
+    // Filter to files that detectBinFile can auto-classify (content/media in bins)
+    const autoAddable = [];
+    for (const filePath of unadded) {
+      const binMeta = await detectBinFile(filePath);
+      if (binMeta) autoAddable.push({ filePath, ...binMeta });
+    }
+
+    if (autoAddable.length > 0) {
+      log.info(`Found ${autoAddable.length} new file(s) to add before push:`);
+      for (const { filePath } of autoAddable) {
+        log.plain(`  ${relative(process.cwd(), filePath)}`);
+      }
+
+      const doAdd = async () => {
+        for (const { meta, metaPath, filePath } of autoAddable) {
+          try {
+            await submitAdd(meta, metaPath, filePath, client, options);
+            // After submitAdd, meta.UID is set if successful
+            if (meta.UID) justAddedUIDs.add(meta.UID);
+          } catch (err) {
+            log.error(`Failed to add ${relative(process.cwd(), filePath)}: ${err.message}`);
+          }
+        }
+      };
+
+      if (!options.yes) {
+        const inquirer = (await import('inquirer')).default;
+        const { proceed } = await inquirer.prompt([{
+          type: 'confirm',
+          name: 'proceed',
+          message: `Add ${autoAddable.length} file(s) to the server before pushing?`,
+          default: true,
+        }]);
+        if (!proceed) {
+          log.dim('Skipping auto-add — continuing with push');
+        } else {
+          await doAdd();
+        }
+      } else {
+        await doAdd();
+      }
+      if (justAddedUIDs.size > 0) log.plain('');
+    }
+  }
+
   const metaFiles = await findMetadataFiles(dirPath, ig);
 
-  // Load baseline for delta detection
+  // ── Load scripts config early (before delta detection) ──────────────
+  // Build hooks must run BEFORE delta detection so compiled output files
+  // (SASS → CSS, Rollup → JS, etc.) are on disk when changes are detected.
+  let scriptsConfig = null;
+  let appConfigForHooks = null;
+  if (options.scripts !== false) {
+    scriptsConfig = await loadAndMergeScripts();
+    if (scriptsConfig) {
+      const cfg = await loadConfig();
+      const app = await loadAppConfig();
+      appConfigForHooks = { ...app, domain: cfg.domain };
+    }
+  }
+
+  // ── Run build phase upfront (before delta detection) ────────────────
+  if (scriptsConfig && options.build !== false) {
+    const globalPrebuild = scriptsConfig.scripts?.prebuild;
+    const globalBuild = scriptsConfig.scripts?.build;
+    const globalPostbuild = scriptsConfig.scripts?.postbuild;
+    const globalHasAnyBuild = globalPrebuild !== undefined || globalBuild !== undefined || globalPostbuild !== undefined;
+
+    // 1. Run global build hooks once
+    if (globalHasAnyBuild) {
+      const globalHooks = { prebuild: globalPrebuild, build: globalBuild, postbuild: globalPostbuild };
+      const env = buildHookEnv('', '', appConfigForHooks);
+      log.dim('  Running global build hooks...');
+      const ok = await runBuildLifecycle(globalHooks, env, process.cwd());
+      if (!ok) {
+        log.error('Global build hook failed — aborting push');
+        process.exit(1);
+      }
+    }
+
+    // 2. Run per-target/entity build hooks for each metadata file
+    //    (only when the resolved hook differs from the global — avoids re-running global)
+    for (const metaPath of metaFiles) {
+      let meta;
+      try { meta = JSON.parse(await readFile(metaPath, 'utf8')); } catch { continue; }
+      const relPath = relative(process.cwd(), metaPath.replace(/\.metadata\.json$/, '')).replace(/\\/g, '/');
+      const entityType = meta._entity || '';
+      const hooks = resolveHooks(relPath, entityType, scriptsConfig);
+      const hasNonGlobalBuild = (hooks.prebuild !== undefined && hooks.prebuild !== globalPrebuild)
+        || (hooks.build !== undefined && hooks.build !== globalBuild)
+        || (hooks.postbuild !== undefined && hooks.postbuild !== globalPostbuild);
+      if (hasNonGlobalBuild) {
+        const env = buildHookEnv(relPath, entityType, appConfigForHooks);
+        log.dim(`  Build hooks: ${relPath}`);
+        const ok = await runBuildLifecycle(hooks, env, process.cwd());
+        if (!ok) {
+          log.error(`Build hook failed for "${basename(metaPath)}" — aborting push`);
+          process.exit(1);
+        }
+      }
+    }
+  }
+
+  // Load baseline for delta detection (after build hooks so compiled files are on disk)
   const baseline = await loadAppJsonBaseline();
 
   if (!baseline) {
@@ -404,6 +597,12 @@ async function pushDirectory(dirPath, client, options, modifyKey = null, transac
       continue;
     }
 
+    // Skip records that were just auto-added in this invocation — they're already on the server
+    if (meta.UID && justAddedUIDs.has(meta.UID)) {
+      log.dim(`  Skipped (just added): ${basename(metaPath)}`);
+      continue;
+    }
+
     // Compound output files: handle root + all inline children together
     // These have _entity='output' and inline children under .children
     if (meta._entity === 'output' && meta.children) {
@@ -556,6 +755,19 @@ async function pushDirectory(dirPath, client, options, modifyKey = null, transac
   }
   for (const item of toAdd) {
     try {
+      // Run push hooks for this item (build hooks already ran upfront)
+      if (scriptsConfig) {
+        const relPath = relative(process.cwd(), item.metaPath.replace(/\.metadata\.json$/, '')).replace(/\\/g, '/');
+        const entityType = item.meta._entity || '';
+        const hooks = resolveHooks(relPath, entityType, scriptsConfig);
+        if (hooks.prepush !== undefined || hooks.push !== undefined || hooks.postpush !== undefined) {
+          const env = buildHookEnv(relPath, entityType, appConfigForHooks);
+          const pushResult = await runPushLifecycle(hooks, env, process.cwd());
+          if (pushResult.failed) { log.error(`Push hook failed for "${basename(item.metaPath)}" — aborting`); failed++; break; }
+          if (!pushResult.runDefault) { succeeded++; successfulPushes.push(item); continue; }
+        }
+      }
+
       const success = await addFromMetadata(item.meta, item.metaPath, client, options, modifyKey);
       if (success) {
         succeeded++;
@@ -576,6 +788,19 @@ async function pushDirectory(dirPath, client, options, modifyKey = null, transac
   // Then process edits
   for (const item of toEdit) {
     try {
+      // Run push hooks for this item (build hooks already ran upfront)
+      if (scriptsConfig) {
+        const relPath = relative(process.cwd(), item.metaPath.replace(/\.metadata\.json$/, '')).replace(/\\/g, '/');
+        const entityType = item.meta._entity || '';
+        const hooks = resolveHooks(relPath, entityType, scriptsConfig);
+        if (hooks.prepush !== undefined || hooks.push !== undefined || hooks.postpush !== undefined) {
+          const env = buildHookEnv(relPath, entityType, appConfigForHooks);
+          const pushResult = await runPushLifecycle(hooks, env, process.cwd());
+          if (pushResult.failed) { log.error(`Push hook failed for "${basename(item.metaPath)}" — aborting`); failed++; break; }
+          if (!pushResult.runDefault) { succeeded++; successfulPushes.push(item); continue; }
+        }
+      }
+
       const success = await pushFromMetadata(item.meta, item.metaPath, client, options, item.changedColumns, modifyKey, transactionKey);
       if (success) {
         succeeded++;
@@ -866,66 +1091,31 @@ async function addFromMetadata(meta, metaPath, client, options, modifyKey = null
     return false;
   }
 
-  // Extract UID from response and rename files to ~uid convention
+  // Extract UID from response and rename metadata 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;
-      }
+    // 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 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 */ }
-        }
-      }
+    // Write _LastUpdated back to meta so baseline gets it
+    if (returnedLastUpdated) meta._LastUpdated = returnedLastUpdated;
 
-      // 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');
+    if (returnedUID) {
+      meta.UID = returnedUID;
 
-      // 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 */ }
-      }
+
+      // Rename metadata file to ~UID convention; companions keep natural names
+      const renameResult = await renameToUidConvention(meta, metaPath, returnedUID, returnedLastUpdated, serverTz);
+
+      // Propagate updated meta back (renameToUidConvention creates a new object)
+      Object.assign(meta, renameResult.updatedMeta);
 
       log.success(`Added: ${basename(metaPath)} → UID ${returnedUID}`);
     }
@@ -1469,6 +1659,11 @@ async function _submitOutputEntity(entity, physicalEntity, changedColumns, metaD
     const strValue = (val === null || val === undefined) ? '' : String(val);
     if (isReference(strValue)) {
       const refPath = resolveReferencePath(strValue, metaDir);
+      // Skip missing companion files (e.g. empty CustomSQL not extracted by clone)
+      try { await access(refPath); } catch {
+        log.dim(`  Skipping ${col} — companion file not found: ${basename(refPath)}`);
+        continue;
+      }
       dataExprs.push(`${rowKeyPrefix}:${rowKeyValue};column:${physicalEntity}.${col}@${refPath}`);
     } else {
       dataExprs.push(`${rowKeyPrefix}:${rowKeyValue};column:${physicalEntity}.${col}=${strValue}`);

package/src/commands/rm.js

@@ -5,6 +5,7 @@ import { log } from '../lib/logger.js';
 import { formatError } from '../lib/formatter.js';
 import { addDeleteEntry, removeAppJsonReference } from '../lib/config.js';
 import { findMetadataFiles } from '../lib/diff.js';
+import { findMetadataForCompanion } from '../lib/filenames.js';
 import { loadStructureFile, findBinByPath, findChildBins, BINS_DIR } from '../lib/structure.js';
 import { runPendingMigrations } from '../lib/migrations.js';
 
@@ -156,14 +157,26 @@ async function rmFileRecord(metaPath, options, { skipPrompt = false } = {}) {
  * Remove a single file (entry point for non-directory rm).
  */
 async function rmFile(filePath, options) {
-  const metaPath = resolveMetaPath(filePath);
+  let metaPath = resolveMetaPath(filePath);
 
   let meta;
   try {
     meta = JSON.parse(await readFile(metaPath, 'utf8'));
   } catch {
-    log.error(`No metadata found at "${metaPath}". Cannot determine record to delete.`);
-    process.exit(1);
+    // Direct metadata path not found — search by @reference
+    const found = await findMetadataForCompanion(filePath);
+    if (found) {
+      metaPath = found;
+      try {
+        meta = JSON.parse(await readFile(metaPath, 'utf8'));
+      } catch {
+        log.error(`Could not read metadata at "${metaPath}".`);
+        process.exit(1);
+      }
+    } else {
+      log.error(`No metadata found for "${basename(filePath)}". Cannot determine record to delete.`);
+      process.exit(1);
+    }
   }
 
   const entity = meta._entity;