@dboio/cli 0.4.1 → 0.5.1

package/src/commands/mv.js

@@ -0,0 +1,869 @@
+import { Command } from 'commander';
+import { readFile, writeFile, stat, rename, mkdir, utimes } from 'fs/promises';
+import { join, dirname, basename, extname, relative, isAbsolute } from 'path';
+import { log } from '../lib/logger.js';
+import { formatError } from '../lib/formatter.js';
+import { loadSynchronize, saveSynchronize } from '../lib/config.js';
+import {
+  loadStructureFile,
+  saveStructureFile,
+  findBinByPath,
+  findChildBins,
+  resolveBinPath,
+  BINS_DIR
+} from '../lib/structure.js';
+import { findMetadataFiles } from '../lib/diff.js';
+
+export const mvCommand = new Command('mv')
+  .description('Move files or bins to a new location and update metadata')
+  .argument('<source>', 'File or directory to move')
+  .argument('[destination]', 'Target directory path, BinID, or UID (omit for interactive prompt)')
+  .option('-f, --force', 'Skip confirmation prompts')
+  .option('-v, --verbose', 'Show detailed operations')
+  .option('--dry-run', 'Preview changes without executing')
+  .option('-C, --confirm <value>', 'Commit changes (true|false)', 'true')
+  .action(async (source, destination, options) => {
+    try {
+      // Only items inside Bins/ are moveable
+      const relSource = isAbsolute(source) ? relative(process.cwd(), source) : source;
+      const normalized = relSource.replace(/\/+$/, '');
+      if (!normalized.startsWith(`${BINS_DIR}/`) && normalized !== BINS_DIR) {
+        log.error(`Only files and directories inside "${BINS_DIR}/" can be moved.`);
+        log.dim('  Root project directories (App Versions, Documentation, Sites, etc.) are part of the DBO app structure and cannot be moved.');
+        process.exit(1);
+      }
+
+      const pathStat = await stat(source).catch(() => null);
+      if (!pathStat) {
+        log.error(`Source path not found: "${source}"`);
+        process.exit(1);
+      }
+
+      const structure = await loadStructureFile();
+
+      // Resolve destination BinID
+      let targetBinId;
+      if (destination) {
+        targetBinId = resolveBinId(destination, structure);
+        if (targetBinId === null) {
+          log.error(`Invalid destination: "${destination}"`);
+          log.dim('  Must be: path, BinID, or UID');
+          process.exit(1);
+        }
+      } else {
+        targetBinId = await promptForBin(structure);
+        if (targetBinId === null) {
+          log.dim('Cancelled.');
+          return;
+        }
+      }
+
+      // Validate target exists in structure
+      if (!structure[targetBinId]) {
+        log.error(`BinID ${targetBinId} not found in .dbo/structure.json`);
+        log.dim('  Run "dbo clone" to refresh project structure.');
+        process.exit(1);
+      }
+
+      if (pathStat.isDirectory()) {
+        await mvBin(source, targetBinId, structure, options);
+      } else {
+        await mvFile(source, targetBinId, structure, options);
+      }
+    } catch (err) {
+      formatError(err);
+      process.exit(1);
+    }
+  });
+
+// ── Resolution helpers ───────────────────────────────────────────────────
+
+/**
+ * Convert a destination (path, BinID, or UID) to a numeric BinID.
+ * Returns null if not found.
+ */
+function resolveBinId(destination, structure) {
+  // Normalize absolute paths to relative
+  const dest = isAbsolute(destination) ? relative(process.cwd(), destination) : destination;
+
+  // Path format: contains /
+  if (dest.includes('/')) {
+    const bin = findBinByPath(dest, structure);
+    return bin ? bin.binId : null;
+  }
+
+  // Numeric BinID
+  if (/^\d+$/.test(dest)) {
+    const id = Number(dest);
+    return structure[id] ? id : null;
+  }
+
+  // 32-char hex UID
+  if (/^[a-f0-9]{32}$/i.test(dest)) {
+    for (const [binId, entry] of Object.entries(structure)) {
+      if (entry.uid === dest) {
+        return Number(binId);
+      }
+    }
+    return null;
+  }
+
+  // Try as path without slashes (single segment name)
+  const bin = findBinByPath(dest, structure);
+  return bin ? bin.binId : null;
+}
+
+/**
+ * Interactive bin selection prompt.
+ */
+async function promptForBin(structure) {
+  const entries = Object.entries(structure)
+    .map(([id, e]) => ({ binId: Number(id), ...e }))
+    .sort((a, b) => (a.fullPath || '').localeCompare(b.fullPath || ''));
+
+  if (entries.length === 0) {
+    log.error('No bins found in .dbo/structure.json');
+    log.dim('  Run "dbo clone" to refresh project structure.');
+    process.exit(1);
+  }
+
+  const choices = entries.map(e => ({
+    name: `${e.name} (${e.binId}) - ${BINS_DIR}/${e.fullPath}`,
+    value: e.binId,
+  }));
+  choices.push({ name: '(Enter custom BinID or UID)', value: '_custom' });
+
+  const inquirer = (await import('inquirer')).default;
+  const { binChoice } = await inquirer.prompt([{
+    type: 'list',
+    name: 'binChoice',
+    message: 'Select destination bin:',
+    choices,
+  }]);
+
+  if (binChoice === '_custom') {
+    const { customValue } = await inquirer.prompt([{
+      type: 'input',
+      name: 'customValue',
+      message: 'Enter BinID or UID:',
+      validate: v => v.trim() ? true : 'BinID or UID is required',
+    }]);
+    return resolveBinId(customValue.trim(), structure);
+  }
+
+  return binChoice;
+}
+
+// ── Validation ───────────────────────────────────────────────────────────
+
+/**
+ * Validate a move operation before executing.
+ */
+function validateMove(source, targetBinId, structure, options) {
+  const errors = [];
+  const warnings = [];
+
+  if (!structure[targetBinId]) {
+    errors.push(`Target BinID ${targetBinId} not found in structure.json`);
+  }
+
+  return { valid: errors.length === 0, errors, warnings };
+}
+
+/**
+ * Prevent moving a bin into its own subtree.
+ * Walks up the parent chain from targetBinId; if sourceBinId is encountered, it's circular.
+ */
+function checkCircularReference(sourceBinId, targetBinId, structure) {
+  if (sourceBinId === targetBinId) return true;
+
+  let current = targetBinId;
+  const visited = new Set();
+  while (current !== null && current !== undefined) {
+    if (visited.has(current)) break; // safety: break infinite loop
+    visited.add(current);
+    if (current === sourceBinId) return true;
+    const entry = structure[current];
+    if (!entry) break;
+    current = entry.parentBinID;
+  }
+  return false;
+}
+
+// ── Metadata helpers ─────────────────────────────────────────────────────
+
+/**
+ * Resolve a file path to its metadata.json path.
+ */
+function resolveMetaPath(filePath) {
+  if (filePath.endsWith('.metadata.json')) {
+    return filePath;
+  }
+  const dir = dirname(filePath);
+  const ext = extname(filePath);
+  const base = basename(filePath, ext);
+  return join(dir, `${base}.metadata.json`);
+}
+
+/**
+ * Get the entity-specific row ID from metadata.
+ */
+function getRowId(meta) {
+  if (meta._id) return meta._id;
+  if (meta._entity) {
+    const entityIdKey = meta._entity.charAt(0).toUpperCase() + meta._entity.slice(1) + 'ID';
+    if (meta[entityIdKey]) return meta[entityIdKey];
+  }
+  return null;
+}
+
+/**
+ * Update fields in a metadata JSON file and touch its mtime.
+ */
+async function updateMetadata(metaPath, updates, options) {
+  if (options.dryRun) {
+    log.info(`[DRY RUN] Would update metadata: ${metaPath}`);
+    for (const [key, val] of Object.entries(updates)) {
+      log.dim(`  ${key} = ${val}`);
+    }
+    return;
+  }
+
+  const raw = await readFile(metaPath, 'utf8');
+  const meta = JSON.parse(raw);
+  Object.assign(meta, updates);
+  await writeFile(metaPath, JSON.stringify(meta, null, 2) + '\n');
+
+  // Touch mtime to mark as modified
+  const now = new Date();
+  await utimes(metaPath, now, now);
+
+  if (options.verbose) {
+    for (const [key, val] of Object.entries(updates)) {
+      log.verbose(`metadata ${key} = ${val}`);
+    }
+  }
+}
+
+// ── Synchronize staging ──────────────────────────────────────────────────
+
+/**
+ * Merge two edit expressions for the same UID.
+ * Combines column assignments from both expressions.
+ *
+ * existing: "RowUID:abc;column:content.Name=Test"
+ * incoming: "RowUID:abc;column:content.BinID=456"
+ * result:   "RowUID:abc;column:content.Name=Test;column:content.BinID=456"
+ */
+function mergeExpressions(existing, incoming) {
+  // Parse both into parts
+  const existingParts = existing.split(';');
+  const incomingParts = incoming.split(';');
+
+  // Separate RowUID/RowID prefix from column assignments
+  const prefix = existingParts.find(p => p.startsWith('RowUID:') || p.startsWith('RowID:'));
+  const existingColumns = existingParts.filter(p => p.startsWith('column:'));
+  const incomingColumns = incomingParts.filter(p => p.startsWith('column:'));
+
+  // Build a map of column assignments (key = entity.Field, value = full part)
+  const columnMap = new Map();
+  for (const col of existingColumns) {
+    const key = extractColumnKey(col);
+    columnMap.set(key, col);
+  }
+  for (const col of incomingColumns) {
+    const key = extractColumnKey(col);
+    columnMap.set(key, col); // incoming overwrites existing for same key
+  }
+
+  return [prefix, ...columnMap.values()].join(';');
+}
+
+/**
+ * Extract the column key (e.g. "content.BinID") from a column part like "column:content.BinID=456".
+ */
+function extractColumnKey(columnPart) {
+  // column:entity.Field=value or column:entity.Field@filepath
+  const afterColon = columnPart.substring('column:'.length);
+  const eqIdx = afterColon.indexOf('=');
+  const atIdx = afterColon.indexOf('@');
+  if (eqIdx !== -1 && (atIdx === -1 || eqIdx < atIdx)) {
+    return afterColon.substring(0, eqIdx);
+  }
+  if (atIdx !== -1) {
+    return afterColon.substring(0, atIdx);
+  }
+  return afterColon;
+}
+
+/**
+ * Add or merge an edit entry in synchronize.json.
+ * Handles conflicts with existing delete entries.
+ *
+ * When `entry.originalValue` is provided (e.g. the original BinID before any
+ * local moves), the staged edit tracks it. If a subsequent move sets the value
+ * back to `originalValue`, the edit is removed entirely — the move is a no-op
+ * relative to the server state.
+ */
+async function stageEdit(entry, options) {
+  if (options.dryRun) {
+    log.info(`[DRY RUN] Would stage edit: ${entry.expression}`);
+    return;
+  }
+
+  const data = await loadSynchronize();
+
+  // Check for existing delete entry with same UID
+  const deleteIdx = data.delete.findIndex(e => e.UID === entry.UID);
+  if (deleteIdx >= 0) {
+    if (!options.force) {
+      const inquirer = (await import('inquirer')).default;
+      const { proceed } = await inquirer.prompt([{
+        type: 'confirm',
+        name: 'proceed',
+        message: 'This item is staged for deletion. Move it anyway (will cancel deletion)?',
+        default: false,
+      }]);
+      if (!proceed) {
+        log.dim('  Skipped (staged for deletion)');
+        return;
+      }
+    }
+    // Remove from delete list
+    data.delete.splice(deleteIdx, 1);
+    if (options.verbose) log.verbose('Removed existing delete entry');
+  }
+
+  // Check for existing edit entry with same UID
+  if (!data.edit) data.edit = [];
+  const editIdx = data.edit.findIndex(e => e.UID === entry.UID);
+  if (editIdx >= 0) {
+    const existing = data.edit[editIdx];
+
+    // Preserve the original value from the first staged edit
+    const originalValue = existing.originalValue ?? entry.originalValue;
+
+    // If this move reverts back to the original value, remove the edit entirely
+    if (originalValue !== undefined && entry.targetValue === originalValue) {
+      data.edit.splice(editIdx, 1);
+      await saveSynchronize(data);
+      log.success(`  Reverted to original location — staged edit removed`);
+      return;
+    }
+
+    // Otherwise merge expressions and preserve originalValue
+    existing.expression = mergeExpressions(existing.expression, entry.expression);
+    existing.originalValue = originalValue;
+    if (options.verbose) log.verbose(`Merged with existing edit: ${existing.expression}`);
+  } else {
+    // New edit entry — store originalValue for future revert detection
+    if (entry.originalValue !== undefined) {
+      // originalValue is stored on the entry, it will persist in synchronize.json
+    }
+    data.edit.push(entry);
+  }
+
+  await saveSynchronize(data);
+}
+
+// ── App.json updates ─────────────────────────────────────────────────────
+
+/**
+ * Update a single @path reference in app.json.
+ */
+async function updateAppJsonPath(oldMetaPath, newMetaPath, options) {
+  if (options.dryRun) {
+    log.info(`[DRY RUN] Would update app.json: @${oldMetaPath} → @${newMetaPath}`);
+    return;
+  }
+
+  const appJsonPath = join(process.cwd(), 'app.json');
+  let appJson;
+  try {
+    appJson = JSON.parse(await readFile(appJsonPath, 'utf8'));
+  } catch {
+    return; // no app.json
+  }
+
+  if (!appJson.children) return;
+
+  const oldRef = `@${oldMetaPath}`;
+  const newRef = `@${newMetaPath}`;
+  let changed = false;
+
+  for (const [key, arr] of Object.entries(appJson.children)) {
+    if (!Array.isArray(arr)) continue;
+    for (let i = 0; i < arr.length; i++) {
+      if (arr[i] === oldRef) {
+        arr[i] = newRef;
+        changed = true;
+      }
+    }
+  }
+
+  if (changed) {
+    await writeFile(appJsonPath, JSON.stringify(appJson, null, 2) + '\n');
+    if (options.verbose) log.verbose(`app.json: ${oldRef} → ${newRef}`);
+  }
+}
+
+/**
+ * Update all @path references that start with a given directory prefix in app.json.
+ */
+async function updateAppJsonForDirectoryMove(oldDirPath, newDirPath, options) {
+  if (options.dryRun) {
+    log.info(`[DRY RUN] Would update app.json refs: @${oldDirPath}/... → @${newDirPath}/...`);
+    return;
+  }
+
+  const appJsonPath = join(process.cwd(), 'app.json');
+  let appJson;
+  try {
+    appJson = JSON.parse(await readFile(appJsonPath, 'utf8'));
+  } catch {
+    return;
+  }
+
+  if (!appJson.children) return;
+
+  const oldPrefix = `@${oldDirPath}/`;
+  const newPrefix = `@${newDirPath}/`;
+  let changed = false;
+
+  for (const [key, arr] of Object.entries(appJson.children)) {
+    if (!Array.isArray(arr)) continue;
+    for (let i = 0; i < arr.length; i++) {
+      if (arr[i].startsWith(oldPrefix)) {
+        arr[i] = newPrefix + arr[i].substring(oldPrefix.length);
+        changed = true;
+      }
+    }
+  }
+
+  if (changed) {
+    await writeFile(appJsonPath, JSON.stringify(appJson, null, 2) + '\n');
+    if (options.verbose) log.verbose(`app.json: updated directory refs ${oldDirPath} → ${newDirPath}`);
+  }
+}
+
+// ── Execute helper ───────────────────────────────────────────────────────
+
+async function executeOperation(operation, description, options) {
+  if (options.dryRun) {
+    log.info(`[DRY RUN] Would ${description}`);
+    return;
+  }
+
+  if (options.verbose) log.dim(`  ${description}...`);
+  await operation();
+  if (options.verbose) log.success(`  ${description}`);
+}
+
+// ── File move ────────────────────────────────────────────────────────────
+
+/**
+ * Check for file name conflict at destination and prompt for resolution.
+ * Returns { action: 'proceed' | 'rename' | 'cancel', newName? }
+ */
+async function checkNameConflict(fileName, targetDir, options) {
+  const targetPath = join(targetDir, fileName);
+  const exists = await stat(targetPath).catch(() => null);
+  if (!exists) return { action: 'proceed' };
+
+  if (options.force) return { action: 'proceed' }; // overwrite silently
+
+  const inquirer = (await import('inquirer')).default;
+  const { action } = await inquirer.prompt([{
+    type: 'list',
+    name: 'action',
+    message: `File "${fileName}" already exists at destination. What would you like to do?`,
+    choices: [
+      { name: 'Overwrite existing file', value: 'overwrite' },
+      { name: 'Rename to avoid conflict', value: 'rename' },
+      { name: 'Cancel operation', value: 'cancel' },
+    ],
+  }]);
+
+  if (action === 'cancel') return { action: 'cancel' };
+  if (action === 'overwrite') return { action: 'proceed' };
+
+  // Rename
+  const { newName } = await inquirer.prompt([{
+    type: 'input',
+    name: 'newName',
+    message: 'Enter new file name:',
+    default: fileName,
+    validate: v => v.trim() ? true : 'File name is required',
+  }]);
+
+  return { action: 'rename', newName: newName.trim() };
+}
+
+/**
+ * Move a single file to a new bin.
+ */
+async function mvFile(sourceFile, targetBinId, structure, options) {
+  // Resolve metadata
+  const 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 entity = meta._entity;
+  const uid = meta.UID;
+  const rowId = getRowId(meta);
+  const currentBinId = meta.BinID;
+
+  if (!entity || !rowId) {
+    log.error(`Missing _entity or row ID in "${metaPath}". Cannot move.`);
+    process.exit(1);
+  }
+
+  // No-op detection
+  if (currentBinId === targetBinId) {
+    log.warn(`File is already in bin ${targetBinId}. Nothing to do.`);
+    return;
+  }
+
+  // Calculate paths
+  const targetDir = resolveBinPath(targetBinId, structure);
+  const sourceDir = dirname(metaPath);
+  const contentFileName = sourceFile.endsWith('.metadata.json')
+    ? null
+    : basename(sourceFile);
+  const metaFileName = basename(metaPath);
+
+  // Determine display name
+  const displayName = basename(metaPath, '.metadata.json');
+  const targetBin = structure[targetBinId];
+  const targetBinName = targetBin ? targetBin.name : String(targetBinId);
+  const targetBinFullPath = targetBin ? `${BINS_DIR}/${targetBin.fullPath}` : targetDir;
+
+  // Check for name conflict
+  const conflictFile = contentFileName || metaFileName;
+  const conflict = await checkNameConflict(conflictFile, targetDir, options);
+  if (conflict.action === 'cancel') {
+    log.dim('Cancelled.');
+    return;
+  }
+
+  // Resolve final file name (may be renamed)
+  let finalContentName = contentFileName;
+  let finalMetaName = metaFileName;
+  if (conflict.action === 'rename' && conflict.newName) {
+    if (contentFileName) {
+      finalContentName = conflict.newName;
+      const ext = extname(finalContentName);
+      const base = basename(finalContentName, ext);
+      finalMetaName = `${base}.metadata.json`;
+    } else {
+      finalMetaName = conflict.newName;
+    }
+  }
+
+  // Confirmation
+  if (!options.force && !options.dryRun) {
+    const inquirer = (await import('inquirer')).default;
+    const { confirm } = await inquirer.prompt([{
+      type: 'confirm',
+      name: 'confirm',
+      message: `Move "${displayName}" to "${targetBinName}" (${targetBinFullPath})?`,
+      default: true,
+    }]);
+    if (!confirm) {
+      log.dim('Cancelled.');
+      return;
+    }
+  }
+
+  // Build new paths
+  const newMetaPath = join(targetDir, finalMetaName);
+  const newContentPath = finalContentName ? join(targetDir, finalContentName) : null;
+
+  // Calculate the new Path field for metadata (relative to Bins/)
+  const newRelativePath = targetBin
+    ? `${targetBin.fullPath}/${finalContentName || displayName}`
+    : null;
+
+  // 1. Update metadata
+  const metaUpdates = { BinID: targetBinId };
+  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 (meta[col] && String(meta[col]).startsWith('@')) {
+        metaUpdates[col] = `@${finalContentName}`;
+      }
+    }
+  }
+
+  await updateMetadata(metaPath, metaUpdates, options);
+
+  // 2. Stage edit in synchronize.json
+  const expression = `RowID:${rowId};column:${entity}.BinID=${targetBinId}`;
+
+  await stageEdit({
+    UID: uid,
+    RowID: rowId,
+    entity,
+    name: displayName,
+    expression,
+    originalValue: currentBinId,
+    targetValue: targetBinId,
+  }, options);
+
+  // 3. Update app.json reference
+  await updateAppJsonPath(metaPath, newMetaPath, options);
+
+  // 4. Physically move files
+  await executeOperation(
+    () => mkdir(targetDir, { recursive: true }),
+    `ensure target directory ${targetDir}`,
+    options
+  );
+
+  await executeOperation(
+    () => rename(metaPath, newMetaPath),
+    `move ${metaPath} → ${newMetaPath}`,
+    options
+  );
+
+  if (contentFileName) {
+    const oldContentPath = join(sourceDir, contentFileName);
+    const contentExists = await stat(oldContentPath).catch(() => null);
+    if (contentExists) {
+      await executeOperation(
+        () => rename(oldContentPath, newContentPath),
+        `move ${oldContentPath} → ${newContentPath}`,
+        options
+      );
+    }
+  }
+
+  // Also move any media file reference
+  if (meta._mediaFile && String(meta._mediaFile).startsWith('@')) {
+    const mediaFileName = String(meta._mediaFile).substring(1);
+    const oldMediaPath = join(sourceDir, mediaFileName);
+    const newMediaPath = join(targetDir, mediaFileName);
+    const mediaExists = await stat(oldMediaPath).catch(() => null);
+    if (mediaExists) {
+      await executeOperation(
+        () => rename(oldMediaPath, newMediaPath),
+        `move ${oldMediaPath} → ${newMediaPath}`,
+        options
+      );
+    }
+  }
+
+  if (options.dryRun) {
+    log.info(`[DRY RUN] Would move "${displayName}" to "${targetBinName}" (${targetBinFullPath})`);
+  } else {
+    log.success(`Moved "${displayName}" → ${targetBinFullPath}`);
+    log.dim(`  Staged: ${expression}`);
+    log.info('Run `dbo push` to apply the move on the server.');
+  }
+}
+
+// ── Bin move ─────────────────────────────────────────────────────────────
+
+/**
+ * Recalculate fullPath for a bin and all descendants after a move.
+ * Returns list of updated BinIDs.
+ */
+function recalculateBinPaths(structure, movedBinId) {
+  const updated = [];
+  const entry = structure[movedBinId];
+  if (!entry) return updated;
+
+  // Recalculate this bin's fullPath based on new parent
+  const parent = entry.parentBinID !== null ? structure[entry.parentBinID] : null;
+  const segment = entry.segment || entry.name;
+  entry.fullPath = parent ? `${parent.fullPath}/${segment}` : segment;
+  updated.push(movedBinId);
+
+  // Recursively update children
+  const children = findChildBins(movedBinId, structure);
+  for (const child of children) {
+    const childId = child.binId || Object.keys(structure).find(k => structure[k] === child);
+    if (childId !== undefined) {
+      updated.push(...recalculateBinPaths(structure, Number(childId)));
+    }
+  }
+
+  return updated;
+}
+
+/**
+ * Move a directory (bin) to a new parent bin.
+ */
+async function mvBin(sourcePath, targetBinId, structure, options) {
+  const sourceBin = findBinByPath(sourcePath, structure);
+  if (!sourceBin) {
+    log.error(`Directory "${sourcePath}" is not a known bin in structure.json.`);
+    process.exit(1);
+  }
+
+  const sourceBinId = sourceBin.binId;
+  const targetBin = structure[targetBinId];
+
+  // Root-level bins are structural and cannot be moved
+  if (sourceBin.parentBinID === null) {
+    log.error(`Cannot move root-level bin "${sourceBin.name}".`);
+    log.dim('  Root bins are part of the DBO app structure and cannot be moved.');
+    log.dim('  You can move files or sub-directories within this bin instead.');
+    process.exit(1);
+  }
+
+  // No-op detection
+  if (sourceBin.parentBinID === targetBinId) {
+    log.warn(`Bin "${sourceBin.name}" is already in bin ${targetBinId}. Nothing to do.`);
+    return;
+  }
+
+  // Circular reference check
+  if (checkCircularReference(sourceBinId, targetBinId, structure)) {
+    log.error('Cannot move bin into its own subtree');
+    log.dim(`  Source: ${sourceBin.name} (${sourceBinId})`);
+    log.dim(`  Target: ${targetBin.name} (${targetBinId})`);
+    process.exit(1);
+  }
+
+  const targetBinName = targetBin ? targetBin.name : String(targetBinId);
+  const targetBinFullPath = targetBin ? `${BINS_DIR}/${targetBin.fullPath}` : null;
+
+  // Confirmation
+  if (!options.force && !options.dryRun) {
+    const inquirer = (await import('inquirer')).default;
+    const { confirm } = await inquirer.prompt([{
+      type: 'confirm',
+      name: 'confirm',
+      message: `Move bin "${sourceBin.name}" (${sourceBinId}) to "${targetBinName}" (${targetBinFullPath})?`,
+      default: true,
+    }]);
+    if (!confirm) {
+      log.dim('Cancelled.');
+      return;
+    }
+  }
+
+  // Calculate old and new paths
+  const oldDirPath = `${BINS_DIR}/${sourceBin.fullPath}`;
+  const oldFullPath = sourceBin.fullPath;
+
+  // 1. Update bin's ParentBinID in structure
+  if (!options.dryRun) {
+    structure[sourceBinId].parentBinID = targetBinId;
+  }
+
+  // 2. Recalculate paths for moved bin and descendants
+  const oldPaths = {};
+  // Capture old paths before recalculation
+  const collectOldPaths = (binId) => {
+    const e = structure[binId];
+    if (e) oldPaths[binId] = e.fullPath;
+    const children = findChildBins(binId, structure);
+    for (const child of children) {
+      const cid = child.binId || Object.keys(structure).find(k => structure[k] === child);
+      if (cid !== undefined) collectOldPaths(Number(cid));
+    }
+  };
+  collectOldPaths(sourceBinId);
+
+  const updatedBinIds = options.dryRun ? [] : recalculateBinPaths(structure, sourceBinId);
+  const newDirPath = options.dryRun
+    ? `${BINS_DIR}/${targetBin.fullPath}/${sourceBin.segment || sourceBin.name}`
+    : `${BINS_DIR}/${structure[sourceBinId].fullPath}`;
+
+  // 3. Update metadata for the bin itself (ParentBinID)
+  // Look for a bin metadata file in the source directory
+  const binMetaPath = join(oldDirPath, `${sourceBin.name}.metadata.json`);
+  const binMetaExists = await stat(binMetaPath).catch(() => null);
+  if (binMetaExists) {
+    await updateMetadata(binMetaPath, { ParentBinID: targetBinId }, options);
+  }
+
+  // 4. Stage edit for bin ParentBinID
+  const currentParentBinId = sourceBin.parentBinID;
+  const expression = `RowID:${sourceBinId};column:bin.ParentBinID=${targetBinId}`;
+
+  await stageEdit({
+    UID: sourceBin.uid,
+    RowID: sourceBinId,
+    entity: 'bin',
+    name: sourceBin.name,
+    expression,
+    originalValue: currentParentBinId,
+    targetValue: targetBinId,
+  }, options);
+
+  // 5. Update app.json for all affected file paths
+  await updateAppJsonForDirectoryMove(oldDirPath, newDirPath, options);
+
+  // 6. Save updated structure.json
+  await executeOperation(
+    () => saveStructureFile(structure),
+    'save updated structure.json',
+    options
+  );
+
+  // 7. Physically move directory
+  await executeOperation(
+    async () => {
+      const parentDir = dirname(newDirPath);
+      await mkdir(parentDir, { recursive: true });
+      await rename(oldDirPath, newDirPath);
+    },
+    `move ${oldDirPath} → ${newDirPath}`,
+    options
+  );
+
+  if (options.dryRun) {
+    log.info(`[DRY RUN] Would move bin "${sourceBin.name}" to "${targetBinName}"`);
+    log.dim(`  ${oldDirPath} → ${newDirPath}`);
+    if (Object.keys(oldPaths).length > 1) {
+      log.dim(`  ${Object.keys(oldPaths).length} bins would have paths recalculated`);
+    }
+  } else {
+    log.success(`Moved bin "${sourceBin.name}" → ${targetBinFullPath}`);
+    log.dim(`  Staged: ${expression}`);
+    if (updatedBinIds.length > 1) {
+      log.dim(`  Updated paths for ${updatedBinIds.length} bins`);
+    }
+    log.info('Run `dbo push` to apply the move on the server.');
+  }
+}
+
+// ── Exports for testing ──────────────────────────────────────────────────
+
+/**
+ * Check if a source path is inside the Bins/ directory.
+ */
+function isInsideBins(sourcePath) {
+  const rel = isAbsolute(sourcePath) ? relative(process.cwd(), sourcePath) : sourcePath;
+  const normalized = rel.replace(/\/+$/, '');
+  return normalized.startsWith(`${BINS_DIR}/`);
+}
+
+/**
+ * Check if a bin is a root-level bin (cannot be moved).
+ */
+function isRootBin(binEntry) {
+  return !!binEntry && binEntry.parentBinID === null;
+}
+
+export {
+  resolveBinId,
+  checkCircularReference,
+  mergeExpressions,
+  resolveMetaPath,
+  recalculateBinPaths,
+  extractColumnKey,
+  isInsideBins,
+  isRootBin,
+};