@dboio/cli 0.4.1

package/src/commands/clone.js

@@ -0,0 +1,742 @@
+import { Command } from 'commander';
+import { readFile, writeFile, mkdir, access } from 'fs/promises';
+import { join, basename, extname } from 'path';
+import { DboClient } from '../lib/client.js';
+import { loadConfig, updateConfigWithApp, loadClonePlacement, saveClonePlacement, ensureGitignore } from '../lib/config.js';
+import { buildBinHierarchy, resolveBinPath, createDirectories, saveStructureFile, getBinName, BINS_DIR, DEFAULT_PROJECT_DIRS } from '../lib/structure.js';
+import { log } from '../lib/logger.js';
+import { setFileTimestamps } from '../lib/timestamps.js';
+
+/**
+ * Resolve a column value that may be base64-encoded.
+ * Server returns large text as: { bytes: N, value: "base64string", encoding: "base64" }
+ */
+function resolveContentValue(value) {
+  if (value && typeof value === 'object' && !Array.isArray(value)
+      && value.encoding === 'base64' && typeof value.value === 'string') {
+    return Buffer.from(value.value, 'base64').toString('utf8');
+  }
+  return value !== null && value !== undefined ? String(value) : null;
+}
+
+function sanitizeFilename(name) {
+  return name.replace(/[/\\?%*:|"<>]/g, '-').replace(/\s+/g, '-').substring(0, 200);
+}
+
+async function fileExists(path) {
+  try { await access(path); return true; } catch { return false; }
+}
+
+export const cloneCommand = new Command('clone')
+  .description('Clone an app from DBO.io to a local project structure')
+  .argument('[source]', 'Local JSON file path (optional)')
+  .option('--app <shortName>', 'App short name to fetch from server')
+  .option('--domain <host>', 'Override domain')
+  .option('-y, --yes', 'Auto-accept all prompts')
+  .option('-v, --verbose', 'Show HTTP request details')
+  .action(async (source, options) => {
+    try {
+      await performClone(source, options);
+    } catch (err) {
+      log.error(err.message);
+      process.exit(1);
+    }
+  });
+
+/**
+ * Main clone workflow. Exported for use by init --clone.
+ */
+export async function performClone(source, options = {}) {
+  const config = await loadConfig();
+  let appJson;
+
+  // Step 1: Load the app JSON
+  if (source) {
+    // Local file
+    log.info(`Loading app JSON from ${source}...`);
+    const raw = await readFile(source, 'utf8');
+    appJson = JSON.parse(raw);
+  } else if (options.app) {
+    // Fetch from server by AppShortName
+    appJson = await fetchAppFromServer(options.app, options, config);
+  } else if (config.AppShortName) {
+    // Use config's AppShortName
+    appJson = await fetchAppFromServer(config.AppShortName, options, config);
+  } else {
+    // Prompt
+    const inquirer = (await import('inquirer')).default;
+    const { choice } = await inquirer.prompt([{
+      type: 'list',
+      name: 'choice',
+      message: 'How would you like to clone?',
+      choices: [
+        { name: 'From server (by app short name)', value: 'server' },
+        { name: 'From a local JSON file', value: 'local' },
+      ],
+    }]);
+
+    if (choice === 'server') {
+      const { appName } = await inquirer.prompt([{
+        type: 'input', name: 'appName',
+        message: 'App short name:',
+        validate: v => v.trim() ? true : 'App short name is required',
+      }]);
+      appJson = await fetchAppFromServer(appName, options, config);
+    } else {
+      const { filePath } = await inquirer.prompt([{
+        type: 'input', name: 'filePath',
+        message: 'Path to JSON file:',
+        validate: v => v.trim() ? true : 'File path is required',
+      }]);
+      const raw = await readFile(filePath, 'utf8');
+      appJson = JSON.parse(raw);
+    }
+  }
+
+  // Validate structure
+  if (!appJson || !appJson.UID || !appJson.children) {
+    throw new Error('Invalid app JSON: missing UID or children');
+  }
+
+  log.success(`Cloning "${appJson.Name}" (${appJson.ShortName})`);
+
+  // Ensure sensitive files are gitignored
+  await ensureGitignore(['.dbo/credentials.json', '.dbo/cookies.txt']);
+
+  // Step 2: Update .dbo/config.json
+  await updateConfigWithApp({
+    AppID: appJson.AppID,
+    AppUID: appJson.UID,
+    AppName: appJson.Name,
+    AppShortName: appJson.ShortName,
+  });
+  log.dim('  Updated .dbo/config.json with app metadata');
+
+  // Step 3: Update package.json
+  await updatePackageJson(appJson, config);
+
+  // Step 4: Create default project directories + bin structure
+  for (const dir of DEFAULT_PROJECT_DIRS) {
+    await mkdir(dir, { recursive: true });
+  }
+
+  const bins = appJson.children.bin || [];
+  const structure = buildBinHierarchy(bins, appJson.AppID);
+  const createdDirs = await createDirectories(structure);
+  await saveStructureFile(structure);
+
+  const totalDirs = DEFAULT_PROJECT_DIRS.length + createdDirs.length;
+  log.success(`Created ${totalDirs} director${totalDirs === 1 ? 'y' : 'ies'}`);
+  for (const d of DEFAULT_PROJECT_DIRS) log.dim(`  ${d}/`);
+  for (const d of createdDirs) log.dim(`  ${d}/`);
+
+  // Step 4b: Determine placement preferences (from config or prompt)
+  const placementPrefs = await resolvePlacementPreferences(appJson, options);
+
+  // Ensure ServerTimezone is set in config (default: America/Los_Angeles for DBO.io)
+  let serverTz = config.ServerTimezone;
+  if (!serverTz || serverTz === 'UTC') {
+    serverTz = 'America/Los_Angeles';
+    await updateConfigWithApp({ ServerTimezone: serverTz });
+    log.dim(`  Set ServerTimezone to ${serverTz} in .dbo/config.json`);
+  }
+
+  // Step 5: Process content → files + metadata
+  const contentRefs = await processContentEntries(
+    appJson.children.content || [],
+    structure,
+    options,
+    placementPrefs.contentPlacement,
+    serverTz,
+  );
+
+  // Step 5b: Process media → download binary files + metadata
+  let mediaRefs = [];
+  const mediaEntries = appJson.children.media || [];
+  if (mediaEntries.length > 0) {
+    mediaRefs = await processMediaEntries(mediaEntries, structure, options, config, appJson.ShortName, placementPrefs.mediaPlacement, serverTz);
+  }
+
+  // Step 6: Process other entities (not output, not bin, not content, not media)
+  const otherRefs = {};
+  for (const [entityName, entries] of Object.entries(appJson.children)) {
+    if (['bin', 'content', 'output', 'media'].includes(entityName)) continue;
+    if (!Array.isArray(entries)) continue;
+
+    const refs = await processGenericEntries(entityName, entries, structure, options, placementPrefs.contentPlacement, serverTz);
+    if (refs.length > 0) {
+      otherRefs[entityName] = refs;
+    }
+  }
+
+  // Include media refs in otherRefs for app.json replacement
+  if (mediaRefs.length > 0) {
+    otherRefs.media = mediaRefs;
+  }
+
+  // Step 7: Save app.json with references
+  await saveAppJson(appJson, contentRefs, otherRefs);
+
+  log.plain('');
+  log.success('Clone complete!');
+  log.dim('  app.json saved to project root');
+  log.dim('  Run "dbo login" to authenticate, then "dbo push" to deploy changes');
+}
+
+/**
+ * Resolve placement preferences from config or prompt the user.
+ * Returns { contentPlacement, mediaPlacement } where values are 'path'|'bin'|'ask'|null
+ */
+async function resolvePlacementPreferences(appJson, options) {
+  // Load saved preferences from config
+  const saved = await loadClonePlacement();
+  let contentPlacement = saved.contentPlacement;
+  let mediaPlacement = saved.mediaPlacement;
+
+  const hasContent = (appJson.children.content || []).length > 0;
+  const hasMedia = (appJson.children.media || []).length > 0;
+
+  // If -y flag, default to bin placement (no prompts)
+  if (options.yes) {
+    return {
+      contentPlacement: contentPlacement || 'bin',
+      mediaPlacement: mediaPlacement || 'bin',
+    };
+  }
+
+  // If both are already set in config, use them
+  if (contentPlacement && mediaPlacement) {
+    return { contentPlacement, mediaPlacement };
+  }
+
+  const inquirer = (await import('inquirer')).default;
+  const prompts = [];
+
+  if (!contentPlacement && hasContent) {
+    prompts.push({
+      type: 'list',
+      name: 'contentPlacement',
+      message: 'How should content files be placed?',
+      choices: [
+        { name: 'Save all in BinID directory', value: 'bin' },
+        { name: 'Save all in their specified Path directory', value: 'path' },
+        { name: 'Ask for every file that has both', value: 'ask' },
+      ],
+    });
+  }
+
+  if (!mediaPlacement && hasMedia) {
+    prompts.push({
+      type: 'list',
+      name: 'mediaPlacement',
+      message: 'How should media files be placed?',
+      choices: [
+        { name: 'Save all in BinID directory', value: 'bin' },
+        { name: 'Save all in their specified FullPath directory', value: 'fullpath' },
+        { name: 'Ask for every file that has both', value: 'ask' },
+      ],
+    });
+  }
+
+  if (prompts.length > 0) {
+    const answers = await inquirer.prompt(prompts);
+    contentPlacement = contentPlacement || answers.contentPlacement || 'bin';
+    mediaPlacement = mediaPlacement || answers.mediaPlacement || 'bin';
+
+    // Save to config for future clones
+    await saveClonePlacement({ mediaPlacement, contentPlacement });
+    log.dim('  Saved placement preferences to .dbo/config.json');
+  }
+
+  return {
+    contentPlacement: contentPlacement || 'bin',
+    mediaPlacement: mediaPlacement || 'bin',
+  };
+}
+
+/**
+ * Fetch app JSON from the server by AppShortName.
+ */
+async function fetchAppFromServer(appShortName, options, config) {
+  const client = new DboClient({ domain: options.domain, verbose: options.verbose });
+  log.info(`Fetching app "${appShortName}" from server...`);
+
+  const result = await client.get('/api/o/object_lookup_app__CALL', {
+    '_filter:AppShortName': appShortName,
+    '_format': 'json_raw',
+  });
+
+  const data = result.payload || result.data;
+  const rows = Array.isArray(data) ? data : (data?.Rows || data?.rows || []);
+
+  if (rows.length === 0) {
+    throw new Error(`No app found with ShortName "${appShortName}"`);
+  }
+
+  log.success(`Found app on server`);
+  return rows[0];
+}
+
+/**
+ * Create or update package.json with app metadata.
+ * Only populates fields that are not already set.
+ */
+async function updatePackageJson(appJson, config) {
+  const pkgPath = join(process.cwd(), 'package.json');
+  let pkg = {};
+
+  try {
+    pkg = JSON.parse(await readFile(pkgPath, 'utf8'));
+  } catch {
+    // No package.json yet — start fresh
+    pkg = { private: true };
+  }
+
+  let changed = false;
+
+  if (!pkg.name && appJson.ShortName) {
+    pkg.name = appJson.ShortName;
+    changed = true;
+  }
+  if (!pkg.productName && appJson.Name) {
+    pkg.productName = appJson.Name;
+    changed = true;
+  }
+  if (!pkg.description && appJson.Description) {
+    pkg.description = appJson.Description;
+    changed = true;
+  }
+  if (!pkg.homepage && config.domain) {
+    pkg.homepage = `https://${config.domain}`;
+    changed = true;
+  }
+
+  // Add deploy script if not already set
+  if (!pkg.scripts) pkg.scripts = {};
+  if (!pkg.scripts.deploy) {
+    pkg.scripts.deploy = "dbo push '.'";
+    changed = true;
+  }
+
+  if (changed) {
+    await writeFile(pkgPath, JSON.stringify(pkg, null, 2) + '\n');
+    log.dim('  Updated package.json with app metadata');
+  }
+}
+
+/**
+ * Process content entries: write files + metadata, return reference map.
+ * Returns array of { uid, metaPath } for app.json reference replacement.
+ */
+async function processContentEntries(contents, structure, options, contentPlacement, serverTz) {
+  if (!contents || contents.length === 0) return [];
+
+  const refs = [];
+  const usedNames = new Map();
+  // Pre-set from config: 'path' or 'bin' skips prompts, 'ask' or null prompts per-file
+  const placementPreference = {
+    value: (contentPlacement === 'path' || contentPlacement === 'bin') ? contentPlacement : null,
+  };
+
+  log.info(`Processing ${contents.length} content record(s)...`);
+
+  for (const record of contents) {
+    const ref = await processRecord('content', record, structure, options, usedNames, placementPreference, serverTz);
+    if (ref) refs.push(ref);
+  }
+
+  return refs;
+}
+
+/**
+ * Process non-content, non-output entities.
+ * Only handles entries with a BinID.
+ */
+async function processGenericEntries(entityName, entries, structure, options, contentPlacement, serverTz) {
+  if (!entries || entries.length === 0) return [];
+
+  const refs = [];
+  const usedNames = new Map();
+  const placementPreference = {
+    value: (contentPlacement === 'path' || contentPlacement === 'bin') ? contentPlacement : null,
+  };
+  let processed = 0;
+
+  for (const record of entries) {
+    if (!record.BinID) continue; // Skip entries without BinID
+
+    const ref = await processRecord(entityName, record, structure, options, usedNames, placementPreference, serverTz);
+    if (ref) {
+      refs.push(ref);
+      processed++;
+    }
+  }
+
+  if (processed > 0) {
+    log.info(`Processed ${processed} ${entityName} record(s)`);
+  }
+
+  return refs;
+}
+
+/**
+ * Process media entries: download binary files from server + create metadata.
+ * Media uses Filename (not Name) and files are fetched via /api/media/{uid}.
+ */
+async function processMediaEntries(mediaRecords, structure, options, config, appShortName, mediaPlacement, serverTz) {
+  if (!mediaRecords || mediaRecords.length === 0) return [];
+
+  // Determine if we can download (need a server connection)
+  let canDownload = false;
+  let client = null;
+
+  if (!options.yes) {
+    const inquirer = (await import('inquirer')).default;
+    const { download } = await inquirer.prompt([{
+      type: 'confirm',
+      name: 'download',
+      message: `${mediaRecords.length} media file(s) need to be downloaded from the server. Attempt download now?`,
+      default: true,
+    }]);
+    canDownload = download;
+  } else {
+    canDownload = true;
+  }
+
+  if (canDownload) {
+    try {
+      client = new DboClient({ domain: options.domain, verbose: options.verbose });
+      await client.getDomain(); // Verify domain is configured
+    } catch {
+      log.warn('No domain configured — skipping media downloads');
+      canDownload = false;
+    }
+  }
+
+  if (!canDownload) {
+    log.warn(`Skipping ${mediaRecords.length} media file(s) — download not attempted`);
+    return [];
+  }
+
+  const refs = [];
+  const usedNames = new Map();
+  // Map config values: 'fullpath' → 'path' (used internally), 'bin' → 'bin', 'ask' → null
+  const placementPreference = {
+    value: mediaPlacement === 'fullpath' ? 'path' : mediaPlacement === 'bin' ? 'bin' : null,
+  };
+  let downloaded = 0;
+  let failed = 0;
+
+  log.info(`Downloading ${mediaRecords.length} media file(s)...`);
+
+  for (const record of mediaRecords) {
+    const filename = record.Filename || `${record.Name || record.UID}.${(record.Extension || 'bin').toLowerCase()}`;
+    const name = sanitizeFilename(filename.replace(/\.[^.]+$/, '')); // base name without extension
+    const ext = (record.Extension || 'bin').toLowerCase();
+
+    // Determine target directory (default: bins/ for items without explicit placement)
+    let dir = BINS_DIR;
+    const hasBinID = record.BinID && structure[record.BinID];
+    const hasFullPath = record.FullPath && typeof record.FullPath === 'string';
+
+    // Parse directory from FullPath: strip leading / and remove filename
+    // FullPath like /media/operator/app/assets/gfx/logo.png → media/operator/app/assets/gfx/
+    // These are valid project-relative paths (media/, dir/ are real directories)
+    let fullPathDir = null;
+    if (hasFullPath) {
+      const stripped = record.FullPath.replace(/^\/+/, '');
+      const lastSlash = stripped.lastIndexOf('/');
+      fullPathDir = lastSlash >= 0 ? stripped.substring(0, lastSlash) : BINS_DIR;
+    }
+
+    if (hasBinID && fullPathDir && fullPathDir !== '.' && !options.yes) {
+      if (placementPreference.value) {
+        dir = placementPreference.value === 'path'
+          ? fullPathDir
+          : resolveBinPath(record.BinID, structure);
+      } else {
+        const binPath = resolveBinPath(record.BinID, structure);
+        const binName = getBinName(record.BinID, structure);
+        const inquirer = (await import('inquirer')).default;
+
+        const { placement } = await inquirer.prompt([{
+          type: 'list',
+          name: 'placement',
+          message: `Where do you want me to place ${filename}?`,
+          choices: [
+            { name: `Into the FullPath of ${fullPathDir}`, value: 'path' },
+            { name: `Into the BinID of ${record.BinID} (${binName} → ${binPath})`, value: 'bin' },
+            { name: `Place this and all further files by FullPath`, value: 'all_path' },
+            { name: `Place this and all further files by BinID`, value: 'all_bin' },
+          ],
+        }]);
+
+        if (placement === 'all_path') {
+          placementPreference.value = 'path';
+          dir = fullPathDir;
+        } else if (placement === 'all_bin') {
+          placementPreference.value = 'bin';
+          dir = binPath;
+        } else {
+          dir = placement === 'path' ? fullPathDir : binPath;
+        }
+      }
+    } else if (hasBinID) {
+      dir = resolveBinPath(record.BinID, structure);
+    } else if (fullPathDir && fullPathDir !== BINS_DIR) {
+      dir = fullPathDir;
+    }
+
+    dir = dir.replace(/^\/+|\/+$/g, '');
+    if (!dir) dir = BINS_DIR;
+    await mkdir(dir, { recursive: true });
+
+    // Deduplicate using full filename (name.ext) so different formats don't collide
+    // e.g. KaTeX_SansSerif-Italic.woff and KaTeX_SansSerif-Italic.woff2 are separate files
+    const fileKey = `${dir}/${name}.${ext}`;
+    const fileCount = usedNames.get(fileKey) || 0;
+    usedNames.set(fileKey, fileCount + 1);
+    const dedupName = fileCount > 0 ? `${name}-${fileCount + 1}` : name;
+    const finalFilename = `${dedupName}.${ext}`;
+    // Metadata: use name.ext as base to avoid collisions between formats
+    // e.g. KaTeX_SansSerif-Italic.woff.metadata.json vs KaTeX_SansSerif-Italic.woff2.metadata.json
+    const filePath = join(dir, finalFilename);
+    const metaPath = join(dir, `${finalFilename}.metadata.json`);
+
+    // Download the file
+    try {
+      const buffer = await client.getBuffer(`/api/media/${record.UID}`);
+      await writeFile(filePath, buffer);
+      const sizeKB = (buffer.length / 1024).toFixed(1);
+      log.success(`Downloaded ${filePath} (${sizeKB} KB)`);
+      downloaded++;
+    } catch (err) {
+      log.warn(`Failed to download ${filename}`);
+      log.dim(`  UID: ${record.UID}`);
+      log.dim(`  URL: /api/media/${record.UID}`);
+      if (record.FullPath) log.dim(`  FullPath: ${record.FullPath}`);
+      log.dim(`  Error: ${err.message}`);
+      failed++;
+      continue; // Skip metadata if download failed
+    }
+
+    // Build metadata
+    const meta = {};
+    for (const [key, value] of Object.entries(record)) {
+      if (key === 'children') continue;
+      meta[key] = value;
+    }
+    meta._entity = 'media';
+    meta._mediaFile = `@${finalFilename}`;
+
+    await writeFile(metaPath, JSON.stringify(meta, null, 2) + '\n');
+    log.dim(`  → ${metaPath}`);
+
+    // Set file timestamps from server dates
+    if (serverTz && (record._CreatedOn || record._LastUpdated)) {
+      try {
+        await setFileTimestamps(filePath, record._CreatedOn, record._LastUpdated, serverTz);
+        await setFileTimestamps(metaPath, record._CreatedOn, record._LastUpdated, serverTz);
+      } catch { /* non-critical */ }
+    }
+
+    refs.push({ uid: record.UID, metaPath });
+  }
+
+  log.info(`Media: ${downloaded} downloaded, ${failed} failed`);
+  return refs;
+}
+
+/**
+ * Process a single record: determine directory, write content file + metadata.
+ * Returns { uid, metaPath } or null.
+ */
+async function processRecord(entityName, record, structure, options, usedNames, placementPreference, serverTz) {
+  let name = sanitizeFilename(String(record.Name || record.UID || 'untitled'));
+  const ext = (record.Extension || 'txt').toLowerCase();
+
+  // Avoid double extension: if name already ends with .ext, strip it
+  const extWithDot = `.${ext}`;
+  if (name.toLowerCase().endsWith(extWithDot)) {
+    name = name.substring(0, name.length - extWithDot.length);
+  }
+
+  // Determine target directory (default: bins/ for items without explicit placement)
+  let dir = BINS_DIR;
+  const hasBinID = record.BinID && structure[record.BinID];
+  const hasPath = record.Path && typeof record.Path === 'string' && record.Path.trim();
+
+  if (hasBinID && hasPath && !options.yes) {
+    // Check for a saved "all" preference
+    if (placementPreference.value) {
+      dir = placementPreference.value === 'path'
+        ? record.Path
+        : resolveBinPath(record.BinID, structure);
+    } else {
+      // Both BinID and Path — prompt user
+      const binPath = resolveBinPath(record.BinID, structure);
+      const binName = getBinName(record.BinID, structure);
+      const inquirer = (await import('inquirer')).default;
+
+      const { placement } = await inquirer.prompt([{
+        type: 'list',
+        name: 'placement',
+        message: `Where do you want me to place ${name}.${ext}?`,
+        choices: [
+          { name: `Into the Path of ${record.Path}`, value: 'path' },
+          { name: `Into the BinID of ${record.BinID} (${binName} → ${binPath})`, value: 'bin' },
+          { name: `Place this and all further files by Path`, value: 'all_path' },
+          { name: `Place this and all further files by BinID`, value: 'all_bin' },
+        ],
+      }]);
+
+      if (placement === 'all_path') {
+        placementPreference.value = 'path';
+        dir = record.Path;
+      } else if (placement === 'all_bin') {
+        placementPreference.value = 'bin';
+        dir = binPath;
+      } else {
+        dir = placement === 'path' ? record.Path : binPath;
+      }
+    }
+  } else if (hasBinID) {
+    dir = resolveBinPath(record.BinID, structure);
+  } else if (hasPath) {
+    dir = record.Path;
+  }
+
+  // Clean up directory path
+  dir = dir.replace(/^\/+|\/+$/g, '');
+  if (!dir) dir = BINS_DIR;
+
+  // Handle path that contains a filename
+  const pathExt = extname(dir);
+  if (pathExt) {
+    // Path includes a filename — use the directory part
+    dir = dir.substring(0, dir.lastIndexOf('/')) || BINS_DIR;
+  }
+
+  await mkdir(dir, { recursive: true });
+
+  // Deduplicate filenames
+  const nameKey = `${dir}/${name}`;
+  const count = usedNames.get(nameKey) || 0;
+  usedNames.set(nameKey, count + 1);
+  const finalName = count > 0 ? `${name}-${count + 1}` : name;
+
+  // Write content file if Content column has data
+  const contentValue = record.Content;
+  const hasContent = contentValue && (
+    (typeof contentValue === 'object' && contentValue.value) ||
+    (typeof contentValue === 'string' && contentValue.length > 0)
+  );
+
+  const fileName = `${finalName}.${ext}`;
+  const filePath = join(dir, fileName);
+  const metaPath = join(dir, `${finalName}.metadata.json`);
+
+  if (hasContent) {
+    const decoded = resolveContentValue(contentValue);
+    if (decoded) {
+      await writeFile(filePath, decoded);
+      log.success(`Saved ${filePath}`);
+    }
+  }
+
+  // Build metadata
+  const meta = {};
+  for (const [key, value] of Object.entries(record)) {
+    if (key === 'children') continue; // Don't store nested children in metadata
+
+    if (key === 'Content' && hasContent) {
+      // Replace with @filename reference
+      meta[key] = `@${fileName}`;
+    } else if (value && typeof value === 'object' && value.encoding === 'base64') {
+      // Other base64 columns — decode and store inline or as reference
+      const decoded = resolveContentValue(value);
+      if (decoded && decoded.length > 200) {
+        // Large value: save as separate file
+        const colExt = guessExtensionForColumn(key);
+        const colFileName = `${finalName}-${key.toLowerCase()}.${colExt}`;
+        const colFilePath = join(dir, colFileName);
+        await writeFile(colFilePath, decoded);
+        meta[key] = `@${colFileName}`;
+        if (!meta._contentColumns) meta._contentColumns = [];
+        meta._contentColumns.push(key);
+      } else {
+        meta[key] = decoded;
+      }
+    } else {
+      meta[key] = value;
+    }
+  }
+
+  meta._entity = entityName;
+  if (hasContent && !meta._contentColumns) {
+    meta._contentColumns = ['Content'];
+  }
+
+  await writeFile(metaPath, JSON.stringify(meta, null, 2) + '\n');
+  log.dim(`  → ${metaPath}`);
+
+  // Set file timestamps from server dates
+  if (serverTz && (record._CreatedOn || record._LastUpdated)) {
+    try {
+      if (hasContent) await setFileTimestamps(filePath, record._CreatedOn, record._LastUpdated, serverTz);
+      await setFileTimestamps(metaPath, record._CreatedOn, record._LastUpdated, serverTz);
+    } catch { /* non-critical */ }
+  }
+
+  return { uid: record.UID, metaPath };
+}
+
+/**
+ * Guess file extension for a column name.
+ */
+function guessExtensionForColumn(columnName) {
+  const lower = columnName.toLowerCase();
+  if (lower.includes('css')) return 'css';
+  if (lower.includes('js') || lower.includes('script')) return 'js';
+  if (lower.includes('html') || lower.includes('template')) return 'html';
+  if (lower.includes('sql') || lower === 'customsql') return 'sql';
+  if (lower.includes('xml')) return 'xml';
+  if (lower.includes('json')) return 'json';
+  if (lower.includes('md') || lower.includes('markdown')) return 'md';
+  return 'txt';
+}
+
+/**
+ * Save app.json to project root with @ references replacing processed entries.
+ */
+async function saveAppJson(appJson, contentRefs, otherRefs) {
+  const output = { ...appJson };
+  output.children = { ...appJson.children };
+
+  // Replace content array with references
+  if (contentRefs.length > 0) {
+    output.children.content = contentRefs.map(r => `@${r.metaPath}`);
+  }
+
+  // Replace other entity arrays with references
+  for (const [entityName, refs] of Object.entries(otherRefs)) {
+    if (refs.length > 0) {
+      // Mix: referenced entries become strings, unreferenced stay as objects
+      const original = appJson.children[entityName] || [];
+      const refUids = new Set(refs.map(r => r.uid));
+      const refMap = Object.fromEntries(refs.map(r => [r.uid, r.metaPath]));
+
+      output.children[entityName] = original.map(entry => {
+        if (refUids.has(entry.UID)) {
+          return `@${refMap[entry.UID]}`;
+        }
+        return entry; // Keep unreferenced entries as-is
+      });
+    }
+  }
+
+  // Bins stay as-is (directory structure, no metadata files)
+  // Output stays as-is (ignored for now)
+
+  await writeFile('app.json', JSON.stringify(output, null, 2) + '\n');
+}