@dboio/cli 0.4.1

package/src/lib/save-to-disk.js

@@ -0,0 +1,383 @@
+import { writeFile, mkdir, access, readFile } from 'fs/promises';
+import { join, dirname, basename, extname } from 'path';
+import { log } from './logger.js';
+
+/**
+ * Resolve a column value for file writing.
+ * Detects base64-encoded objects from the server and decodes them.
+ * Server returns these 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 String(value);
+}
+
+/**
+ * Save-to-disk engine with @filename round-trip support.
+ *
+ * When multiple content columns are selected, each gets its own file with
+ * a column-based suffix: main-Content.css, main-Description.md
+ *
+ * Metadata files store @filename references for push compatibility.
+ * If a metadata.json already exists, its @filename mappings are reused.
+ *
+ * Options:
+ *   entity: entity name stored as _entity in metadata
+ *   saveFilename: column for the base filename
+ *   savePath: column containing the directory path
+ *   saveContent: column name(s) to save as files
+ *   saveExtension: column name for extension, or literal extension
+ *   nonInteractive: skip all prompts
+ *   contentFileMap: object mapping column → { suffix, extension } per column
+ */
+export async function saveToDisk(rows, columns, options = {}) {
+  if (!rows || rows.length === 0) {
+    log.warn('No records to save.');
+    return;
+  }
+
+  let filenameCol, pathCol, contentCols, extensionSource, contentFileMap, customPath = null;
+
+  if (options.saveFilename || options.nonInteractive) {
+    filenameCol = options.saveFilename || findDefault(columns, ['UID', 'Name', 'name', 'uid']);
+    pathCol = options.savePath || null;
+    contentCols = options.saveContent ? (Array.isArray(options.saveContent) ? options.saveContent : [options.saveContent]) : [];
+    extensionSource = options.saveExtension || null;
+    contentFileMap = options.contentFileMap || null;
+  } else {
+    const inquirer = (await import('inquirer')).default;
+
+    // 1. Filename column
+    const defaultFilename = findDefault(columns, ['Name', 'name', 'UID', 'uid']);
+    const { filename } = await inquirer.prompt([{
+      type: 'list', name: 'filename',
+      message: 'Which column should be used as the base filename?',
+      choices: columns, default: defaultFilename,
+    }]);
+    filenameCol = filename;
+
+    // 2. Path column or custom path
+    const pathChoices = [
+      '(None — save to current directory)',
+      '(Custom path — type a directory)',
+      ...columns,
+    ];
+    const defaultPath = columns.includes('Path') ? 'Path' : columns.includes('path') ? 'path' : pathChoices[0];
+    const { pathChoice } = await inquirer.prompt([{
+      type: 'list', name: 'pathChoice',
+      message: 'Where should files be saved?',
+      choices: pathChoices, default: defaultPath,
+    }]);
+
+    if (pathChoice.startsWith('(Custom')) {
+      const { dir } = await inquirer.prompt([{
+        type: 'input', name: 'dir',
+        message: 'Directory path (created if it does not exist):',
+        default: '.',
+      }]);
+      customPath = dir;
+      pathCol = null;
+    } else if (pathChoice.startsWith('(None')) {
+      pathCol = null;
+    } else {
+      pathCol = pathChoice;
+    }
+
+    // 3. Content columns — pick one at a time, configure extension immediately
+    const contentDefaults = findContentDefaults(columns);
+    const extCol = findColumn(columns, ['Extension', 'extension', 'ext']);
+    let useExtCol = false;
+
+    // Ask once about Extension column if it exists
+    if (extCol) {
+      const { useIt } = await inquirer.prompt([{
+        type: 'confirm', name: 'useIt',
+        message: `Use the "${extCol}" column value as file extension for content files?`,
+        default: true,
+      }]);
+      useExtCol = useIt;
+    }
+
+    contentCols = [];
+    contentFileMap = {};
+    let availableColumns = [...columns];
+
+    // Loop: pick column → configure extension → ask for another
+    let keepAdding = true;
+    while (keepAdding) {
+      const choices = ['(Done — no more files)', ...availableColumns];
+      const defaultChoice = contentCols.length === 0
+        ? (contentDefaults[0] || choices[0])
+        : choices[0];
+
+      const { col } = await inquirer.prompt([{
+        type: 'list', name: 'col',
+        message: contentCols.length === 0
+          ? 'Save a column as file content?'
+          : 'Save another column as a file?',
+        choices,
+        default: defaultChoice,
+      }]);
+
+      if (col.startsWith('(Done')) {
+        keepAdding = false;
+        break;
+      }
+
+      // Configure this column's extension immediately
+      if (useExtCol) {
+        contentFileMap[col] = { suffix: contentCols.length > 0 ? col.toLowerCase() : '', extensionSource: extCol };
+      } else {
+        const ext = await promptExtension(inquirer, col);
+        contentFileMap[col] = { suffix: contentCols.length > 0 ? col.toLowerCase() : '', extension: ext };
+      }
+
+      contentCols.push(col);
+      availableColumns = availableColumns.filter(c => c !== col);
+
+      // If only 1 column so far, no suffix needed
+      // If we add a second, retroactively add suffix to the first
+      if (contentCols.length === 2) {
+        const firstCol = contentCols[0];
+        if (!contentFileMap[firstCol].suffix) {
+          contentFileMap[firstCol].suffix = firstCol.toLowerCase();
+        }
+      }
+
+      if (availableColumns.length === 0) break;
+    }
+
+    // Single column: clear suffix (not needed)
+    if (contentCols.length === 1) {
+      contentFileMap[contentCols[0]].suffix = '';
+    }
+
+    extensionSource = useExtCol ? extCol : null;
+  }
+
+  let savedCount = 0;
+  const usedNames = new Map(); // track dir+name to avoid collisions
+
+  for (const row of rows) {
+    const name = sanitizeFilename(String(row[filenameCol] ?? 'untitled'));
+    let dir = customPath || '.';
+    let finalName = name;
+
+    if (pathCol && row[pathCol]) {
+      const pathValue = String(row[pathCol]);
+      const pathHasFile = extname(pathValue) !== '';
+
+      if (pathHasFile) {
+        dir = dirname(pathValue);
+        const pathFilename = basename(pathValue, extname(pathValue));
+        if (options.nonInteractive) {
+          finalName = pathFilename;
+        } else {
+          const inquirer = (await import('inquirer')).default;
+          const { usePathName } = await inquirer.prompt([{
+            type: 'confirm', name: 'usePathName',
+            message: `Path "${pathValue}" contains filename "${basename(pathValue)}" — use this as the filename?`,
+            default: true,
+          }]);
+          if (usePathName) finalName = pathFilename;
+        }
+      } else {
+        dir = pathValue;
+      }
+    }
+
+    dir = dir.replace(/^\/+|\/+$/g, '');
+    if (!dir) dir = '.';
+    if (dir !== '.') await mkdir(dir, { recursive: true });
+
+    // Deduplicate filenames when multiple records share the same name
+    const nameKey = `${dir}/${finalName}`;
+    const count = usedNames.get(nameKey) || 0;
+    usedNames.set(nameKey, count + 1);
+    if (count > 0) {
+      finalName = `${finalName}-${count + 1}`;
+    }
+
+    // Check for existing metadata with @filename mappings to reuse
+    const metaPath = join(dir, `${finalName}.metadata.json`);
+    let existingMeta = null;
+    if (await fileExists(metaPath)) {
+      try {
+        existingMeta = JSON.parse(await readFile(metaPath, 'utf8'));
+      } catch { /* ignore parse errors */ }
+    }
+
+    // Build metadata with @filename placeholders
+    const meta = { ...row };
+    if (options.entity) meta._entity = options.entity;
+    const contentColumnsList = [];
+
+    for (const col of contentCols) {
+      const content = row[col];
+      if (content === null || content === undefined || content === '') {
+        log.warn(`Column "${col}" is empty for "${finalName}" — no file created`);
+        continue;
+      }
+
+      // Determine filename for this column's content
+      let fileName;
+
+      // First check: reuse existing @filename from previous pull
+      if (existingMeta && existingMeta[col] && String(existingMeta[col]).startsWith('@')) {
+        fileName = String(existingMeta[col]).substring(1);
+      } else {
+        // Build filename from config
+        fileName = buildContentFileName(finalName, col, row, contentCols, contentFileMap, extensionSource, columns);
+      }
+
+      const filePath = join(dir, fileName);
+
+      // Prompt before overwriting
+      if (await fileExists(filePath) && !options.nonInteractive) {
+        const inquirer = (await import('inquirer')).default;
+        const { overwrite } = await inquirer.prompt([{
+          type: 'confirm', name: 'overwrite',
+          message: `Overwrite existing file "${filePath}"?`,
+          default: true,
+        }]);
+        if (!overwrite) {
+          log.dim(`  → Skipped ${filePath}`);
+          meta[col] = `@${fileName}`;
+          contentColumnsList.push(col);
+          continue;
+        }
+      }
+
+      await writeFile(filePath, resolveContentValue(content));
+      log.success(`Saved ${filePath}`);
+      savedCount++;
+
+      meta[col] = `@${fileName}`;
+      contentColumnsList.push(col);
+    }
+
+    if (contentColumnsList.length > 0) {
+      meta._contentColumns = contentColumnsList;
+    }
+
+    // Save metadata — prompt if exists
+    if (await fileExists(metaPath) && !options.nonInteractive) {
+      const inquirer = (await import('inquirer')).default;
+      const { overwrite } = await inquirer.prompt([{
+        type: 'confirm', name: 'overwrite',
+        message: `Overwrite existing metadata "${metaPath}"?`,
+        default: true,
+      }]);
+      if (!overwrite) {
+        log.dim(`  → Skipped ${metaPath}`);
+        continue;
+      }
+    }
+
+    await writeFile(metaPath, JSON.stringify(meta, null, 2) + '\n');
+    log.dim(`  → ${metaPath}`);
+    savedCount++;
+  }
+
+  log.info(`Saved ${savedCount} file(s) for ${rows.length} record(s)`);
+}
+
+function buildContentFileName(baseName, col, row, contentCols, contentFileMap, extensionSource, columns) {
+  let suffix = '';
+  let ext = 'txt';
+
+  if (contentFileMap && contentFileMap[col]) {
+    const cfg = contentFileMap[col];
+    suffix = cfg.suffix || '';
+    if (cfg.extensionSource && columns.includes(cfg.extensionSource)) {
+      ext = String(row[cfg.extensionSource] || 'txt').toLowerCase();
+    } else if (cfg.extension) {
+      ext = cfg.extension;
+    }
+  } else if (extensionSource && columns.includes(extensionSource)) {
+    ext = String(row[extensionSource] || 'txt').toLowerCase();
+  }
+
+  // Single column with no suffix: main.css
+  // Multiple columns or with suffix: main-suffix.css
+  if (suffix) {
+    return `${baseName}-${suffix}.${ext}`;
+  }
+  if (contentCols.length > 1) {
+    return `${baseName}-${col.toLowerCase()}.${ext}`;
+  }
+  return `${baseName}.${ext}`;
+}
+
+const EXTENSION_CHOICES = [
+  'html', 'css', 'js', 'mjs', 'json', 'md', 'txt',
+  'sql', 'xml', 'sh', 'curl', 'csv', 'yaml',
+  '(custom)',
+];
+
+async function promptExtension(inquirer, columnName) {
+  const guessed = guessExtension(columnName);
+  // Put the guessed extension first in the list
+  const choices = [guessed, ...EXTENSION_CHOICES.filter(c => c !== guessed)];
+
+  const { ext } = await inquirer.prompt([{
+    type: 'list', name: 'ext',
+    message: `File extension for "${columnName}":`,
+    choices,
+    default: guessed,
+  }]);
+
+  if (ext === '(custom)') {
+    const { custom } = await inquirer.prompt([{
+      type: 'input', name: 'custom',
+      message: 'Enter custom extension:',
+      default: 'txt',
+    }]);
+    return custom.replace(/^\./, '');
+  }
+
+  return ext;
+}
+
+function guessExtension(columnName) {
+  const lower = columnName.toLowerCase();
+  if (lower.includes('css')) return 'css';
+  if (lower.includes('js') || lower.includes('script')) return 'js';
+  if (lower.includes('html')) return 'html';
+  if (lower.includes('sql')) return 'sql';
+  if (lower.includes('xml')) return 'xml';
+  if (lower.includes('md') || lower.includes('markdown')) return 'md';
+  if (lower.includes('json')) return 'json';
+  return 'txt';
+}
+
+async function fileExists(path) {
+  try { await access(path); return true; } catch { return false; }
+}
+
+function findDefault(columns, candidates) {
+  for (const c of candidates) {
+    if (columns.includes(c)) return c;
+  }
+  return columns[0];
+}
+
+/** Like findDefault but returns null if no match (no fallback) */
+function findColumn(columns, candidates) {
+  for (const c of candidates) {
+    if (columns.includes(c)) return c;
+  }
+  return null;
+}
+
+function findContentDefaults(columns) {
+  const candidates = ['Content', 'content', 'Text', 'text', 'Body', 'body'];
+  return columns.filter(c => candidates.includes(c));
+}
+
+function sanitizeFilename(name) {
+  return name.replace(/[/\\?%*:|"<>]/g, '-').replace(/\s+/g, '-').substring(0, 200);
+}

package/src/lib/structure.js

@@ -0,0 +1,129 @@
+import { readFile, writeFile, mkdir } from 'fs/promises';
+import { join } from 'path';
+
+const STRUCTURE_FILE = '.dbo/structure.json';
+
+/** All bin-placed files go under this directory at project root */
+export const BINS_DIR = 'Bins';
+
+/** Default top-level directories created at project root during clone */
+export const DEFAULT_PROJECT_DIRS = [
+  BINS_DIR,
+  'App Versions',
+  'Documentation',
+  'Sites',
+  'Extensions',
+  'Data Sources',
+];
+
+/**
+ * Build a bin hierarchy from an array of bin objects.
+ * Filters by targetAppId and resolves full directory paths via ParentBinID traversal.
+ *
+ * The Path field may already contain the full path from root (e.g. "assets/css/vendor")
+ * or just a segment name. We use the Name field as the directory segment and build
+ * full paths by walking up the ParentBinID chain, since Path can be ambiguous.
+ *
+ * Returns a map: { [BinID]: { name, path, parentBinID, fullPath } }
+ */
+export function buildBinHierarchy(bins, targetAppId) {
+  if (!Array.isArray(bins) || bins.length === 0) return {};
+
+  // Filter by AppID
+  const filtered = targetAppId
+    ? bins.filter(b => b.AppID === targetAppId)
+    : bins;
+
+  // Build lookup by BinID
+  const byId = {};
+  for (const bin of filtered) {
+    // Use Path as the segment name, but only the last part if it contains slashes
+    // (Path often stores the full path, e.g. "assets/css/vendor" for a bin named "vendor")
+    const rawPath = bin.Path || bin.Name;
+    const segment = rawPath.includes('/') ? rawPath.split('/').pop() : rawPath;
+
+    byId[bin.BinID] = {
+      name: bin.Name,
+      path: bin.Path,
+      segment,
+      parentBinID: bin.ParentBinID || null,
+      binId: bin.BinID,
+      uid: bin.UID,
+      fullPath: null,
+    };
+  }
+
+  // Resolve full paths by walking up parent chain using segment names
+  function resolvePath(binId) {
+    const entry = byId[binId];
+    if (!entry) return null;
+    if (entry.fullPath !== null) return entry.fullPath;
+
+    if (entry.parentBinID && byId[entry.parentBinID]) {
+      const parentPath = resolvePath(entry.parentBinID);
+      entry.fullPath = parentPath ? `${parentPath}/${entry.segment}` : entry.segment;
+    } else {
+      entry.fullPath = entry.segment;
+    }
+    return entry.fullPath;
+  }
+
+  for (const binId of Object.keys(byId)) {
+    resolvePath(binId);
+  }
+
+  return byId;
+}
+
+/**
+ * Lookup the full directory path for a BinID in the structure map.
+ * Returns path prefixed with bins/ (e.g. "bins/app/assets/css").
+ */
+export function resolveBinPath(binId, structure) {
+  const entry = structure[binId];
+  return entry ? `${BINS_DIR}/${entry.fullPath}` : null;
+}
+
+/**
+ * Create all directories from the bin structure under bins/.
+ */
+export async function createDirectories(structure) {
+  const paths = Object.values(structure)
+    .map(e => `${BINS_DIR}/${e.fullPath}`)
+    .filter(Boolean)
+    .sort(); // sort so parents are created first
+
+  for (const p of paths) {
+    await mkdir(p, { recursive: true });
+  }
+
+  return paths;
+}
+
+/**
+ * Save the bin structure to .dbo/structure.json.
+ */
+export async function saveStructureFile(structure) {
+  await mkdir('.dbo', { recursive: true });
+  await writeFile(STRUCTURE_FILE, JSON.stringify(structure, null, 2) + '\n');
+}
+
+/**
+ * Load bin structure from .dbo/structure.json.
+ */
+export async function loadStructureFile() {
+  try {
+    const raw = await readFile(STRUCTURE_FILE, 'utf8');
+    return JSON.parse(raw);
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * Find the bin name for a given BinID from the structure.
+ */
+export function getBinName(binId, structure) {
+  const entry = structure[binId];
+  return entry ? entry.name : null;
+}

package/src/lib/timestamps.js

@@ -0,0 +1,67 @@
+import { utimes } from 'fs/promises';
+
+/**
+ * Parse a server date string as being in the server's timezone.
+ * Server dates come as ISO-like strings (e.g. "2025-01-10T09:36:19Z")
+ * but the actual time is in the server's local timezone, not UTC.
+ *
+ * If serverTz is null/undefined, treats the date as UTC (no conversion).
+ * Returns a proper Date object in UTC.
+ */
+export function parseServerDate(dateStr, serverTz) {
+  if (!dateStr) return null;
+
+  // Strip trailing Z — the date may not actually be UTC
+  const clean = String(dateStr).replace(/Z$/, '');
+  const asUtc = new Date(clean + 'Z');
+  if (isNaN(asUtc.getTime())) return null;
+
+  // If no server timezone specified, treat as UTC
+  if (!serverTz || serverTz === 'UTC') return asUtc;
+
+  // Find offset: format this UTC instant in the server timezone,
+  // then compute the difference to determine the actual UTC time
+  const parts = new Intl.DateTimeFormat('en-US', {
+    timeZone: serverTz,
+    year: 'numeric', month: '2-digit', day: '2-digit',
+    hour: '2-digit', minute: '2-digit', second: '2-digit',
+    hour12: false,
+  }).formatToParts(asUtc);
+
+  const p = {};
+  for (const { type, value } of parts) p[type] = value;
+  const tzLocal = new Date(`${p.year}-${p.month}-${p.day}T${p.hour}:${p.minute}:${p.second}Z`);
+  const offset = tzLocal - asUtc;
+
+  return new Date(asUtc.getTime() - offset);
+}
+
+/**
+ * Set a file's Created (birthtime) and Modified (mtime) timestamps
+ * based on server _CreatedOn and _LastUpdated values.
+ *
+ * On macOS: setting mtime to a time before the current birthtime
+ * causes the OS to update birthtime to match. So we:
+ * 1. First set mtime to _CreatedOn (the earlier date) → updates birthtime
+ * 2. Then set mtime to _LastUpdated (the later date) → birthtime stays
+ *
+ * Created ← _CreatedOn, Modified ← _LastUpdated
+ */
+export async function setFileTimestamps(filePath, createdOn, lastUpdated, serverTz) {
+  const created = parseServerDate(createdOn, serverTz);
+  const modified = parseServerDate(lastUpdated, serverTz);
+
+  if (!created && !modified) return;
+
+  // Step 1: Set mtime to the created date (earlier) to update birthtime
+  if (created) {
+    await utimes(filePath, created, created);
+  }
+
+  // Step 2: Set mtime to the modified date (later) — birthtime stays at created
+  if (modified && created) {
+    await utimes(filePath, created, modified);
+  } else if (modified) {
+    await utimes(filePath, modified, modified);
+  }
+}