@dboio/cli 0.15.3 → 0.17.0

package/src/commands/init.js

@@ -9,6 +9,10 @@ import { log } from '../lib/logger.js';
 import { checkDomainChange, writeAppJsonDomain } from '../lib/domain-guard.js';
 import { performLogin } from './login.js';
 import { runPendingMigrations } from '../lib/migrations.js';
+import { fetchSchema, saveSchema, SCHEMA_FILE } from '../lib/schema.js';
+import { loadMetadataSchema, saveMetadataSchema, generateMetadataFromSchema } from '../lib/metadata-schema.js';
+import { syncDependencies } from '../lib/dependencies.js';
+import { mergeDependencies } from '../lib/config.js';
 
 export const initCommand = new Command('init')
   .description('Initialize DBO CLI configuration for the current directory')
@@ -25,6 +29,8 @@ export const initCommand = new Command('init')
   .option('--dboignore', 'Create or reset .dboignore to defaults (use with --force to overwrite)')
   .option('--media-placement <placement>', 'Set media placement when cloning: fullpath or binpath (default: bin)')
   .option('--no-migrate', 'Skip pending migrations for this invocation')
+  .option('--no-deps', 'Skip dependency cloning after init')
+  .option('--dependencies <apps>', 'Sync specific dependency apps (comma-separated short-names)')
   .action(async (options) => {
     // Merge --yes into nonInteractive
     if (options.yes) options.nonInteractive = true;
@@ -102,7 +108,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/scripts.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', 'schema.json', '.dbo/dependencies/']);
 
       const createdIgnore = await createDboignore();
       if (createdIgnore) log.dim('  Created .dboignore');
@@ -135,6 +141,41 @@ export const initCommand = new Command('init')
         await performLogin(domain, username);
       }
 
+      // Attempt schema fetch (best-effort — silently skip if not authenticated yet)
+      try {
+        const schemaData = await fetchSchema({ domain, verbose: options.verbose });
+        await saveSchema(schemaData);
+        log.dim(`  Saved ${SCHEMA_FILE}`);
+
+        const existing = await loadMetadataSchema();
+        const updated = generateMetadataFromSchema(schemaData, existing ?? {});
+        await saveMetadataSchema(updated);
+        log.dim(`  Updated .dbo/metadata_schema.json`);
+      } catch (err) {
+        log.warn(`  Could not fetch schema (${err.message}) — run 'dbo clone --schema' after login.`);
+      }
+
+      // Sync dependency apps (e.g., _system) — best-effort, non-blocking
+      if (!options.noDeps) {
+        const explicitDeps = options.dependencies
+          ? options.dependencies.split(',').map(s => s.trim().toLowerCase()).filter(Boolean)
+          : null;
+        if (explicitDeps && explicitDeps.length > 0) {
+          await mergeDependencies(explicitDeps);
+        }
+        try {
+          await syncDependencies({
+            domain,
+            force: explicitDeps ? true : undefined,
+            verbose: options.verbose,
+            systemSchemaPath: join(process.cwd(), SCHEMA_FILE),
+            only: explicitDeps || undefined,
+          });
+        } catch (err) {
+          log.warn(`  Dependency sync failed: ${err.message}`);
+        }
+      }
+
       // TransactionKeyPreset — always RowUID (stable across domains)
       await saveTransactionKeyPreset('RowUID');
       log.dim('  TransactionKeyPreset: RowUID');

package/src/commands/input.js

@@ -2,7 +2,6 @@ import { Command } from 'commander';
 import { DboClient } from '../lib/client.js';
 import { buildInputBody, parseFileArg, checkSubmitErrors } from '../lib/input-parser.js';
 import { formatResponse, formatError } from '../lib/formatter.js';
-import { loadAppConfig } from '../lib/config.js';
 import { checkStoredTicket, clearGlobalTicket } from '../lib/ticketing.js';
 import { checkModifyKey, isModifyKeyError, handleModifyKeyError } from '../lib/modify-key.js';
 import { log } from '../lib/logger.js';
@@ -59,37 +58,8 @@ 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 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) {
-          const inquirer = (await import('inquirer')).default;
-          const { appIdChoice } = await inquirer.prompt([{
-            type: 'list',
-            name: 'appIdChoice',
-            message: `You're submitting data without an AppID, but your config has information about the current App. Do you want me to add that Column information along with your submission?`,
-            choices: [
-              { name: `Yes, use AppID ${appConfig.AppID}`, value: 'use_config' },
-              { name: 'No', value: 'none' },
-              { name: 'Enter custom AppID', value: 'custom' },
-            ],
-          }]);
-          if (appIdChoice === 'use_config') {
-            extraParams['AppID'] = String(appConfig.AppID);
-            log.dim(`  Using AppID ${appConfig.AppID} from config`);
-          } else if (appIdChoice === 'custom') {
-            const { customAppId } = await inquirer.prompt([{
-              type: 'input', name: 'customAppId',
-              message: 'Custom AppID:',
-            }]);
-            if (customAppId.trim()) extraParams['AppID'] = customAppId.trim();
-          }
-        }
-      }
+      // dbo input is a low-level command — don't prompt for AppID.
+      // AppID prompting belongs in push/deploy where it's contextually required.
 
       if (options.file.length > 0) {
         // Multipart mode

package/src/commands/mv.js

@@ -607,8 +607,8 @@ async function mvFile(sourceFile, targetBinId, structure, options) {
   if (newRelativePath) metaUpdates.Path = newRelativePath;
 
   // Update content column references if file was renamed
-  if (conflict.action === 'rename' && finalContentName && meta._contentColumns) {
-    for (const col of meta._contentColumns) {
+  if (conflict.action === 'rename' && finalContentName && (meta._companionReferenceColumns || meta._contentColumns)) {
+    for (const col of (meta._companionReferenceColumns || meta._contentColumns)) {
       if (meta[col] && String(meta[col]).startsWith('@')) {
         metaUpdates[col] = `@${finalContentName}`;
       }
@@ -677,7 +677,7 @@ async function mvFile(sourceFile, targetBinId, structure, options) {
     // Update deploy config: remove old entry (by UID), re-insert with new path + correct key
     await removeDeployEntry(uid);
     if (newContentPath) {
-      const col = (meta._contentColumns || [])[0] || 'Content';
+      const col = (meta._companionReferenceColumns || meta._contentColumns || [])[0] || 'Content';
       await upsertDeployEntry(newContentPath, uid, entity, col);
     } else if (meta._mediaFile && String(meta._mediaFile).startsWith('@')) {
       const movedMediaPath = join(targetDir, String(meta._mediaFile).substring(1));

package/src/commands/push.js

@@ -20,7 +20,7 @@ import { BINS_DIR, ENTITY_DIR_NAMES, loadStructureFile, findBinByPath } from '..
 import { ensureTrashIcon, setFileTag } from '../lib/tagging.js';
 import { checkToeStepping } from '../lib/toe-stepping.js';
 import { runPendingMigrations } from '../lib/migrations.js';
-// AUTO-ADD DISABLED: import { findUnaddedFiles, detectBinFile, submitAdd } from './add.js';
+// AUTO-ADD DISABLED: import { findUnaddedFiles, detectBinFile, submitAdd } from '../lib/insert.js';
 
 /**
  * Resolve an @reference file path to an absolute filesystem path.
@@ -269,7 +269,7 @@ async function moveWillDeleteToTrash(entry) {
     // Read the __WILL_DELETE__ metadata to find associated content files
     const rawMeta = await readFile(willDeleteMeta, 'utf8');
     const deletedMeta = JSON.parse(rawMeta);
-    for (const col of (deletedMeta._contentColumns || [])) {
+    for (const col of (deletedMeta._companionReferenceColumns || deletedMeta._contentColumns || [])) {
       const ref = deletedMeta[col];
       if (ref && String(ref).startsWith('@')) {
         const refFile = String(ref).substring(1);
@@ -439,7 +439,7 @@ async function ensureManifestMetadata() {
 
   const meta = {
     _entity: 'content',
-    _contentColumns: ['Content'],
+    _companionReferenceColumns: ['Content'],
     Content: '@/manifest.json',
     Path: 'manifest.json',
     Name: 'manifest.json',
@@ -535,6 +535,10 @@ async function pushDirectory(dirPath, client, options, modifyKey = null, transac
     log.warn('No .app.json baseline found — performing full push (run "dbo clone" to enable delta sync)');
   }
 
+  // Load server timezone for delta date comparisons
+  const pushConfig = await loadConfig();
+  const serverTz = pushConfig.ServerTimezone || 'America/Los_Angeles';
+
   // Collect metadata with detected changes
   const toPush = [];
   const outputCompoundFiles = [];
@@ -583,7 +587,7 @@ async function pushDirectory(dirPath, client, options, modifyKey = null, transac
     const isNewRecord = !meta.UID && !meta._id;
 
     // Verify @file references exist
-    const contentCols = meta._contentColumns || [];
+    const contentCols = meta._companionReferenceColumns || meta._contentColumns || [];
     let missingFiles = false;
     for (const col of contentCols) {
       const ref = meta[col];
@@ -624,7 +628,7 @@ async function pushDirectory(dirPath, client, options, modifyKey = null, transac
     let changedColumns = null;
     if (!isNewRecord && baseline) {
       try {
-        changedColumns = await detectChangedColumns(metaPath, baseline);
+        changedColumns = await detectChangedColumns(metaPath, baseline, serverTz);
         if (changedColumns.length === 0) {
           log.dim(`  Skipping ${basename(metaPath)} — no changes detected`);
           skipped++;
@@ -1009,7 +1013,7 @@ async function pushByUIDs(uids, client, options, modifyKey = null, transactionKe
  */
 async function addFromMetadata(meta, metaPath, client, options, modifyKey = null) {
   const entity = meta._entity;
-  const contentCols = new Set(meta._contentColumns || []);
+  const contentCols = new Set(meta._companionReferenceColumns || meta._contentColumns || []);
   const metaDir = dirname(metaPath);
 
   const dataExprs = [];
@@ -1135,7 +1139,7 @@ async function pushFromMetadata(meta, metaPath, client, options, changedColumns
   const uid = meta.UID;
   const id = meta._id;
   const entity = meta._entity;
-  const contentCols = new Set(meta._contentColumns || []);
+  const contentCols = new Set(meta._companionReferenceColumns || meta._contentColumns || []);
   const metaDir = dirname(metaPath);
 
   // Determine the row key. TransactionKeyPreset only applies when the record
@@ -1361,7 +1365,7 @@ async function pushFromMetadata(meta, metaPath, client, options, changedColumns
           await writeFile(metaPath, JSON.stringify(meta, null, 2) + '\n');
           await setFileTimestamps(metaPath, meta._CreatedOn, updated, serverTz);
           // Update content file mtime too
-          const contentCols = meta._contentColumns || [];
+          const contentCols = meta._companionReferenceColumns || meta._contentColumns || [];
           for (const col of contentCols) {
             const ref = meta[col];
             if (ref && String(ref).startsWith('@')) {
@@ -1451,7 +1455,7 @@ async function checkPathMismatch(meta, metaPath, entity, options) {
   const metaBase = parseMetaFilename(basename(metaPath))?.naturalBase ?? basename(metaPath, '.metadata.json');
 
   // Find the content file referenced by @filename
-  const contentCols = meta._contentColumns || [];
+  const contentCols = meta._companionReferenceColumns || meta._contentColumns || [];
   let contentFileName = null;
   for (const col of contentCols) {
     const ref = meta[col];

package/src/commands/rm.js

@@ -91,7 +91,7 @@ async function rmFileRecord(metaPath, options, { skipPrompt = false } = {}) {
   const metaDir = dirname(metaPath);
   const localFiles = [metaPath];
 
-  for (const col of (meta._contentColumns || [])) {
+  for (const col of (meta._companionReferenceColumns || meta._contentColumns || [])) {
     const ref = meta[col];
     if (ref && String(ref).startsWith('@')) {
       localFiles.push(join(metaDir, String(ref).substring(1)));
@@ -197,7 +197,7 @@ async function rmFile(filePath, options) {
   // Collect local files for display
   const metaDir = dirname(metaPath);
   const localFiles = [metaPath];
-  for (const col of (meta._contentColumns || [])) {
+  for (const col of (meta._companionReferenceColumns || meta._contentColumns || [])) {
     const ref = meta[col];
     if (ref && String(ref).startsWith('@')) {
       localFiles.push(join(metaDir, String(ref).substring(1)));

package/src/lib/columns.js

@@ -14,6 +14,7 @@ const SKIP_COLUMNS = new Set([
   '_LastUpdatedTicketID',
   '_entity',
   '_contentColumns',
+  '_companionReferenceColumns',
 ]);
 
 /**

package/src/lib/config.js

@@ -66,7 +66,7 @@ export async function readLegacyConfig() {
 
 export async function initConfig(domain) {
   await mkdir(dboDir(), { recursive: true });
-  await writeFile(configPath(), JSON.stringify({ domain }, null, 2) + '\n');
+  await writeFile(configPath(), JSON.stringify({ domain, dependencies: ['_system'] }, null, 2) + '\n');
 }
 
 export async function saveCredentials(username) {
@@ -167,6 +167,88 @@ export async function updateConfigWithApp({ AppID, AppUID, AppName, AppShortName
   await writeFile(configPath(), JSON.stringify(existing, null, 2) + '\n');
 }
 
+// ─── Dependency helpers ───────────────────────────────────────────────────
+
+/**
+ * Get the dependencies array from .dbo/config.json.
+ * Returns ["_system"] if the key is absent.
+ */
+export async function getDependencies() {
+  try {
+    const raw = await readFile(configPath(), 'utf8');
+    const config = JSON.parse(raw);
+    const deps = config.dependencies;
+    if (!Array.isArray(deps)) return ['_system'];
+    if (!deps.includes('_system')) deps.unshift('_system');
+    return deps;
+  } catch {
+    return ['_system'];
+  }
+}
+
+/**
+ * Merge new short-names into the dependencies array (union, no duplicates).
+ * Persists the result to .dbo/config.json.
+ */
+export async function mergeDependencies(shortnames) {
+  await mkdir(dboDir(), { recursive: true });
+  let existing = {};
+  try {
+    existing = JSON.parse(await readFile(configPath(), 'utf8'));
+  } catch { /* no config */ }
+  const current = Array.isArray(existing.dependencies) ? existing.dependencies : ['_system'];
+  for (const s of shortnames) {
+    if (s && !current.includes(s)) current.push(s);
+  }
+  if (!current.includes('_system')) current.unshift('_system');
+  existing.dependencies = current;
+  await writeFile(configPath(), JSON.stringify(existing, null, 2) + '\n');
+  return current;
+}
+
+/**
+ * Replace the full dependencies array in .dbo/config.json.
+ * Always ensures _system is present.
+ */
+export async function setDependencies(shortnames) {
+  await mkdir(dboDir(), { recursive: true });
+  let existing = {};
+  try {
+    existing = JSON.parse(await readFile(configPath(), 'utf8'));
+  } catch { /* no config */ }
+  const deps = [...new Set(['_system', ...shortnames.filter(Boolean)])];
+  existing.dependencies = deps;
+  await writeFile(configPath(), JSON.stringify(existing, null, 2) + '\n');
+}
+
+/**
+ * Get dependencyLastUpdated.<shortname> from .dbo/config.json.
+ * Returns null if absent.
+ */
+export async function getDependencyLastUpdated(shortname) {
+  try {
+    const raw = await readFile(configPath(), 'utf8');
+    const config = JSON.parse(raw);
+    return (config.dependencyLastUpdated && config.dependencyLastUpdated[shortname]) || null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Set dependencyLastUpdated.<shortname> in .dbo/config.json.
+ */
+export async function setDependencyLastUpdated(shortname, timestamp) {
+  await mkdir(dboDir(), { recursive: true });
+  let existing = {};
+  try {
+    existing = JSON.parse(await readFile(configPath(), 'utf8'));
+  } catch { /* no config */ }
+  if (!existing.dependencyLastUpdated) existing.dependencyLastUpdated = {};
+  existing.dependencyLastUpdated[shortname] = timestamp;
+  await writeFile(configPath(), JSON.stringify(existing, null, 2) + '\n');
+}
+
 /**
  * Load app-related fields from .dbo/config.json.
  */

package/src/lib/delta.js

@@ -99,9 +99,10 @@ export async function compareFileContent(filePath, baselineValue) {
  *
  * @param {string} metaPath - Path to metadata.json file
  * @param {Object} baseline - The baseline JSON
+ * @param {string} [serverTz] - Server timezone for date parsing (e.g. 'America/Los_Angeles')
  * @returns {Promise<string[]>} - Array of changed column names
  */
-export async function detectChangedColumns(metaPath, baseline) {
+export async function detectChangedColumns(metaPath, baseline, serverTz) {
   // Load current metadata
   const metaRaw = await readFile(metaPath, 'utf8');
   const metadata = JSON.parse(metaRaw);
@@ -174,7 +175,7 @@ export async function detectChangedColumns(metaPath, baseline) {
     try {
       const mediaStat = await stat(mediaPath);
       const baselineDate = baselineEntry?._LastUpdated
-        ? parseServerDate(baselineEntry._LastUpdated)
+        ? parseServerDate(baselineEntry._LastUpdated, serverTz)
         : null;
       if (baselineDate) {
         // Media file modified after baseline sync point = local change

package/src/lib/dependencies.js

@@ -1,8 +1,22 @@
 /**
- * Dependency management for entity synchronization.
- * Ensures children are processed before parents to maintain referential integrity.
+ * Dependency management for entity synchronization and app dependency cloning.
+ * - Entity ordering: ensures children are processed before parents for referential integrity.
+ * - App dependencies: auto-clone related apps into .dbo/dependencies/<shortname>/.
  */
 
+import { spawn } from 'child_process';
+import { mkdir, symlink, access, readFile, writeFile } from 'fs/promises';
+import { join, resolve, relative, sep } from 'path';
+import { fileURLToPath } from 'url';
+import { DboClient } from './client.js';
+import { log } from './logger.js';
+import {
+  getDependencies, mergeDependencies,
+  getDependencyLastUpdated, setDependencyLastUpdated,
+  loadConfig,
+} from './config.js';
+import { sanitizeFilename } from '../commands/clone.js';
+
 /**
  * Entity dependency hierarchy.
  * Lower levels must be processed before higher levels.
@@ -129,3 +143,204 @@ export function sortEntriesByUid(entries) {
   }
   return entries.slice().sort((a, b) => (a.UID || '').localeCompare(b.UID || ''));
 }
+
+// ─── App Dependency Cloning ───────────────────────────────────────────────
+
+/**
+ * Normalize the app.json Dependencies column into a string[].
+ */
+export function parseDependenciesColumn(value) {
+  if (!value) return [];
+  if (typeof value === 'string') {
+    return value.split(',').map(s => s.trim().toLowerCase()).filter(Boolean);
+  }
+  if (Array.isArray(value)) {
+    return value.map(s => String(s).trim().toLowerCase()).filter(Boolean);
+  }
+  if (typeof value === 'object') {
+    return Object.keys(value).map(k => k.trim().toLowerCase()).filter(Boolean);
+  }
+  return [];
+}
+
+/**
+ * Create symlinks for credentials.json and cookies.txt from parent into checkout.
+ */
+export async function symlinkCredentials(parentDboDir, checkoutDboDir) {
+  await mkdir(checkoutDboDir, { recursive: true });
+  for (const filename of ['credentials.json', 'cookies.txt']) {
+    const src = join(parentDboDir, filename);
+    const dest = join(checkoutDboDir, filename);
+    try { await access(src); } catch { continue; }
+    try { await access(dest); continue; } catch { /* proceed */ }
+    try {
+      await symlink(resolve(src), dest);
+    } catch (err) {
+      if (err.code !== 'EEXIST') log.warn(`  Could not symlink ${filename}: ${err.message}`);
+    }
+  }
+}
+
+/**
+ * Run dbo CLI as a child process in a given directory.
+ */
+export function execDboInDir(dir, args, options = {}) {
+  return new Promise((resolve, reject) => {
+    const dboBin = fileURLToPath(new URL('../../bin/dbo.js', import.meta.url));
+    const quiet = options.quiet || false;
+    const child = spawn(process.execPath, [dboBin, ...args], {
+      cwd: dir,
+      stdio: quiet ? ['ignore', 'pipe', 'pipe'] : 'inherit',
+      env: process.env,
+    });
+    let stderr = '';
+    if (quiet) {
+      child.stdout?.resume(); // drain stdout
+      child.stderr?.on('data', chunk => { stderr += chunk; });
+    }
+    child.on('close', code => {
+      if (code === 0) resolve();
+      else reject(new Error(stderr.trim() || `dbo ${args.join(' ')} exited with code ${code}`));
+    });
+    child.on('error', reject);
+  });
+}
+
+/**
+ * Returns true if the dependency needs a fresh clone.
+ */
+export async function checkDependencyStaleness(shortname, options = {}) {
+  const stored = await getDependencyLastUpdated(shortname);
+  if (!stored) return true; // Never cloned
+
+  const { domain } = await loadConfig();
+  const effectiveDomain = options.domain || domain;
+  const client = new DboClient({ domain: effectiveDomain, verbose: options.verbose });
+
+  const dateStr = stored.substring(0, 10); // YYYY-MM-DD from ISO string
+  const result = await client.get(
+    `/api/app/object/${encodeURIComponent(shortname)}[_LastUpdated]?UpdatedAfter=${dateStr}`
+  );
+  if (!result.ok || !result.data) return false; // Can't determine — assume fresh
+
+  const serverTs = result.data._LastUpdated;
+  if (!serverTs) return false;
+  return new Date(serverTs) > new Date(stored);
+}
+
+/**
+ * Sync dependency apps into .dbo/dependencies/<shortname>/.
+ *
+ * @param {object} options
+ * @param {string}   [options.domain]           - Override domain
+ * @param {boolean}  [options.force]            - Bypass staleness check
+ * @param {boolean}  [options.schema]           - Bypass staleness check (--schema flag)
+ * @param {boolean}  [options.verbose]
+ * @param {string}   [options.systemSchemaPath] - Absolute path to schema.json for _system fast-clone
+ * @param {string[]} [options.only]             - Only sync these short-names
+ * @param {Function} [options._execOverride]    - Override execDboInDir for testing
+ */
+export async function syncDependencies(options = {}) {
+  // Recursive guard: don't run inside a checkout directory
+  const cwd = process.cwd();
+  if (cwd.includes(`${sep}.dbo${sep}dependencies${sep}`)) {
+    log.dim('  Skipping dependency sync (inside a checkout directory)');
+    return;
+  }
+
+  const deps = options.only
+    ? [...new Set(['_system', ...options.only])]
+    : await getDependencies();
+
+  const parentDboDir = join(cwd, '.dbo');
+  const depsRoot = join(parentDboDir, 'dependencies');
+
+  const forceAll = !!(options.force || options.schema);
+  const execFn = options._execOverride || execDboInDir;
+
+  const synced = [];
+  const skipped = [];
+  const failed = [];
+
+  const spinner = log.spinner(`Syncing dependencies [${deps.join(', ')}]`);
+
+  for (const raw of deps) {
+    const shortname = sanitizeFilename(raw.toLowerCase().trim());
+    if (!shortname) continue;
+
+    spinner.update(`Syncing dependency: ${shortname}`);
+
+    const checkoutDir = join(depsRoot, shortname);
+    const checkoutDboDir = join(checkoutDir, '.dbo');
+
+    try {
+      // 1. Create checkout dir + minimal config
+      await mkdir(checkoutDboDir, { recursive: true });
+      const minConfigPath = join(checkoutDboDir, 'config.json');
+      let configExists = false;
+      try { await access(minConfigPath); configExists = true; } catch {}
+      if (!configExists) {
+        const { domain } = await loadConfig();
+        const effectiveDomain = options.domain || domain;
+        await writeFile(minConfigPath, JSON.stringify({ domain: effectiveDomain }, null, 2) + '\n');
+      }
+
+      // 2. Symlink credentials
+      await symlinkCredentials(parentDboDir, checkoutDboDir);
+
+      // 3. Staleness check (unless --force or --schema)
+      if (!forceAll) {
+        let isStale = true;
+        try {
+          isStale = await checkDependencyStaleness(shortname, options);
+        } catch {
+          // Network unavailable — assume stale to attempt clone
+        }
+        if (!isStale) {
+          skipped.push(shortname);
+          continue;
+        }
+      }
+
+      // 4. Run the clone (quiet — suppress child process output)
+      if (shortname === '_system' && options.systemSchemaPath) {
+        const relPath = relative(checkoutDir, options.systemSchemaPath);
+        await execFn(checkoutDir, ['clone', relPath, '--force', '--yes', '--no-deps'], { quiet: true });
+      } else {
+        await execFn(checkoutDir, ['clone', '--app', shortname, '--force', '--yes', '--no-deps'], { quiet: true });
+      }
+
+      // 5. Read _LastUpdated from checkout's app.json and persist
+      try {
+        const appJsonPath = join(checkoutDir, 'app.json');
+        const appJson = JSON.parse(await readFile(appJsonPath, 'utf8'));
+        const ts = appJson._LastUpdated || appJson.LastUpdated || null;
+        if (ts) await setDependencyLastUpdated(shortname, ts);
+      } catch { /* can't read _LastUpdated — that's OK */ }
+
+      synced.push(shortname);
+    } catch (err) {
+      failed.push(shortname);
+      if (options.verbose) log.warn(`  Dependency "${shortname}" failed: ${err.message}`);
+    }
+  }
+
+  // Stop spinner and print summary
+  const parts = [];
+  if (synced.length > 0) parts.push(`synced [${synced.join(', ')}]`);
+  if (skipped.length > 0) parts.push(`up to date [${skipped.join(', ')}]`);
+  if (failed.length > 0) parts.push(`failed [${failed.join(', ')}]`);
+
+  if (failed.length > 0 && synced.length === 0 && skipped.length === 0) {
+    spinner.stop(null);
+    log.warn(`Dependencies ${parts.join(', ')}`);
+  } else {
+    const summary = `Dependencies: ${parts.join(', ')}`;
+    spinner.stop(null);
+    if (failed.length > 0) {
+      log.warn(summary);
+    } else {
+      log.success(summary);
+    }
+  }
+}

package/src/lib/diff.js

@@ -208,15 +208,13 @@ export async function hasLocalModifications(metaPath, config = {}) {
     if (!syncDate) return false;
     const syncTime = syncDate.getTime();
 
-    // Check if metadata.json itself was edited since last sync
-    const metaStat = await stat(metaPath);
-    if (metaStat.mtime.getTime() > syncTime + 2000) {
-      return true;
-    }
+    // Skip metadata self-check: metadata files are managed by the CLI and
+    // their mtimes get bumped by migrations, interrupted clones, etc.
+    // Only check companion content/media files for actual user edits.
 
     // Check content files
     const metaDir = dirname(metaPath);
-    const contentCols = meta._contentColumns || [];
+    const contentCols = meta._companionReferenceColumns || meta._contentColumns || [];
 
     // Load baseline for content comparison fallback (build tools can
     // rewrite files with identical content, bumping mtime without any
@@ -497,7 +495,7 @@ export async function compareRecord(metaPath, config, serverRecordsMap) {
 
   const metaDir = dirname(metaPath);
   const metaBase = parseMetaFilename(basename(metaPath))?.naturalBase ?? basename(metaPath, '.metadata.json');
-  const contentCols = localMeta._contentColumns || [];
+  const contentCols = localMeta._companionReferenceColumns || localMeta._contentColumns || [];
   const fieldDiffs = [];
 
   // Compare content file columns
@@ -530,7 +528,7 @@ export async function compareRecord(metaPath, config, serverRecordsMap) {
   }
 
   // Compare metadata fields (non-content, non-system)
-  const skipFields = new Set(['_entity', '_contentColumns', '_mediaFile', 'children']);
+  const skipFields = new Set(['_entity', '_contentColumns', '_companionReferenceColumns', '_mediaFile', 'children']);
   for (const [key, serverVal] of Object.entries(serverRecord)) {
     if (skipFields.has(key)) continue;
     if (contentCols.includes(key)) continue; // Already handled above
@@ -607,7 +605,7 @@ export async function compareRecord(metaPath, config, serverRecordsMap) {
 export async function applyServerChanges(diffResult, acceptedFields, config) {
   const { metaPath, serverRecord, localMeta, fieldDiffs } = diffResult;
   const metaDir = dirname(metaPath);
-  const contentCols = new Set(localMeta._contentColumns || []);
+  const contentCols = new Set(localMeta._companionReferenceColumns || localMeta._contentColumns || []);
   let updatedMeta = { ...localMeta };
   const filesToTimestamp = [metaPath];
 
@@ -801,7 +799,7 @@ export async function inlineDiffAndMerge(serverRow, metaPath, config, options =
 
   const metaDir = dirname(metaPath);
   const metaBase = parseMetaFilename(basename(metaPath))?.naturalBase ?? basename(metaPath, '.metadata.json');
-  const contentCols = localMeta._contentColumns || [];
+  const contentCols = localMeta._companionReferenceColumns || localMeta._contentColumns || [];
   const fieldDiffs = [];
 
   // Compare content columns
@@ -837,7 +835,7 @@ export async function inlineDiffAndMerge(serverRow, metaPath, config, options =
   }
 
   // Compare metadata fields
-  const skipFields = new Set(['_entity', '_contentColumns', '_mediaFile', 'children']);
+  const skipFields = new Set(['_entity', '_contentColumns', '_companionReferenceColumns', '_mediaFile', 'children']);
   for (const [key, serverVal] of Object.entries(serverRow)) {
     if (skipFields.has(key)) continue;
     if (contentCols.includes(key)) continue;