@dboio/cli 0.15.2 → 0.16.2

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;

package/src/lib/filenames.js

@@ -213,7 +213,7 @@ export async function findMetadataForCompanion(companionPath) {
     const metaPath = join(dir, entry);
     try {
       const meta = JSON.parse(await readFile(metaPath, 'utf8'));
-      const cols = [...(meta._contentColumns || [])];
+      const cols = [...(meta._companionReferenceColumns || meta._contentColumns || [])];
       if (meta._mediaFile) cols.push('_mediaFile');
       for (const col of cols) {
         const ref = meta[col];
@@ -280,7 +280,7 @@ export async function renameToUidConvention(meta, metaPath, uid, lastUpdated, se
   if (serverTz && lastUpdated) {
     const { setFileTimestamps } = await import('./timestamps.js');
     try { await setFileTimestamps(newMetaPath, lastUpdated, lastUpdated, serverTz); } catch {}
-    const contentCols = [...(meta._contentColumns || [])];
+    const contentCols = [...(meta._companionReferenceColumns || meta._contentColumns || [])];
     if (meta._mediaFile) contentCols.push('_mediaFile');
     for (const col of contentCols) {
       const ref = updatedMeta[col];

package/src/lib/ignore.js

@@ -16,6 +16,7 @@ const DEFAULT_FILE_CONTENT = `# DBO CLI ignore patterns
 .dboignore
 *.dboio.json
 app.json
+.dbo/dependencies/
 
 # Editor / IDE / OS
 .DS_Store

package/src/lib/logger.js

@@ -1,5 +1,7 @@
 import chalk from 'chalk';
 
+const SPINNER_FRAMES = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+
 export const log = {
   info(msg) { console.log(chalk.blue('ℹ'), msg); },
   success(msg) { console.log(chalk.green('✓'), msg); },
@@ -9,4 +11,37 @@ export const log = {
   plain(msg) { console.log(msg); },
   verbose(msg) { console.log(chalk.dim('  →'), chalk.dim(msg)); },
   label(label, value) { console.log(chalk.dim(`  ${label}:`), value); },
+
+  /**
+   * Start a spinner with a message. Returns { stop(finalMsg) }.
+   * The spinner writes to stderr so it doesn't pollute piped output.
+   */
+  spinner(msg) {
+    let i = 0;
+    const stream = process.stderr;
+    const isTTY = stream.isTTY;
+    if (!isTTY) {
+      // Non-TTY: just print the message once, return a no-op stop
+      console.log(chalk.dim(msg));
+      return { update() {}, stop(final) { if (final) console.log(final); } };
+    }
+    const render = () => {
+      const frame = chalk.cyan(SPINNER_FRAMES[i % SPINNER_FRAMES.length]);
+      stream.clearLine(0);
+      stream.cursorTo(0);
+      stream.write(`${frame} ${chalk.dim(msg)}`);
+      i++;
+    };
+    render();
+    const timer = setInterval(render, 80);
+    return {
+      update(newMsg) { msg = newMsg; },
+      stop(final) {
+        clearInterval(timer);
+        stream.clearLine(0);
+        stream.cursorTo(0);
+        if (final) console.log(final);
+      },
+    };
+  },
 };