@dboio/cli 0.6.14 → 0.7.2

package/src/commands/clone.js

@@ -2,8 +2,8 @@ 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, saveEntityDirPreference, loadEntityDirPreference, saveEntityContentExtractions, loadEntityContentExtractions, saveAppJsonBaseline, addDeleteEntry, loadCollisionResolutions, saveCollisionResolutions, loadSynchronize, saveAppModifyKey, loadTransactionKeyPreset, saveTransactionKeyPreset } from '../lib/config.js';
-import { buildBinHierarchy, resolveBinPath, createDirectories, saveStructureFile, getBinName, findBinByPath, BINS_DIR, DEFAULT_PROJECT_DIRS, ENTITY_DIR_MAP } from '../lib/structure.js';
+import { loadConfig, updateConfigWithApp, loadClonePlacement, saveClonePlacement, ensureGitignore, saveEntityDirPreference, loadEntityDirPreference, saveEntityContentExtractions, loadEntityContentExtractions, saveAppJsonBaseline, addDeleteEntry, loadCollisionResolutions, saveCollisionResolutions, loadSynchronize, saveAppModifyKey, loadTransactionKeyPreset, saveTransactionKeyPreset, loadOutputFilenamePreference, saveOutputFilenamePreference } from '../lib/config.js';
+import { buildBinHierarchy, resolveBinPath, createDirectories, saveStructureFile, getBinName, findBinByPath, BINS_DIR, DEFAULT_PROJECT_DIRS, ENTITY_DIR_MAP, OUTPUT_ENTITY_MAP, OUTPUT_HIERARCHY_ENTITIES } from '../lib/structure.js';
 import { log } from '../lib/logger.js';
 import { setFileTimestamps } from '../lib/timestamps.js';
 import { getLocalSyncTime, isServerNewer, hasLocalModifications, promptChangeDetection, inlineDiffAndMerge } from '../lib/diff.js';
@@ -421,6 +421,8 @@ 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('-e, --entity <type>', 'Only clone a specific entity type (e.g. output, content, media, extension)')
+  .option('--force', 'Force re-processing of all files, skip change detection')
   .option('--domain <host>', 'Override domain')
   .option('-y, --yes', 'Auto-accept all prompts')
   .option('-v, --verbose', 'Show HTTP request details')
@@ -573,38 +575,68 @@ export async function performClone(source, options = {}) {
     log.dim(`  Set ServerTimezone to ${serverTz} in .dbo/config.json`);
   }
 
-  // Step 4c: Detect and resolve file path collisions
-  log.info('Scanning for file path collisions...');
-  const fileRegistry = await buildFileRegistry(appJson, structure, placementPrefs);
-  const toDeleteUIDs = await resolveCollisions(fileRegistry, options);
+  // Resolve --entity filter: which entity types to process
+  // "output" expands to all OUTPUT_HIERARCHY_ENTITIES, others are matched directly
+  const entityFilter = resolveEntityFilter(options.entity);
+  if (entityFilter) {
+    log.info(`Entity filter: only processing ${options.entity}`);
+  }
+
+  // Step 4c: Detect and resolve file path collisions (skip in entity-filter mode)
+  let toDeleteUIDs = new Set();
+  if (!entityFilter) {
+    log.info('Scanning for file path collisions...');
+    const fileRegistry = await buildFileRegistry(appJson, structure, placementPrefs);
+    toDeleteUIDs = await resolveCollisions(fileRegistry, options);
 
-  if (toDeleteUIDs.size > 0) {
-    await stageCollisionDeletions(toDeleteUIDs, appJson, options);
+    if (toDeleteUIDs.size > 0) {
+      await stageCollisionDeletions(toDeleteUIDs, appJson, options);
+    }
   }
 
   // Step 5: Process content → files + metadata (skip rejected records)
-  const contentRefs = await processContentEntries(
-    appJson.children.content || [],
-    structure,
-    options,
-    placementPrefs.contentPlacement,
-    serverTz,
-    toDeleteUIDs,
-  );
+  let contentRefs = [];
+  if (!entityFilter || entityFilter.has('content')) {
+    contentRefs = await processContentEntries(
+      appJson.children.content || [],
+      structure,
+      options,
+      placementPrefs.contentPlacement,
+      serverTz,
+      toDeleteUIDs,
+    );
+  }
 
   // Step 5b: Process media → download binary files + metadata (skip rejected records)
   let mediaRefs = [];
-  const mediaEntries = appJson.children.media || [];
-  if (mediaEntries.length > 0) {
-    mediaRefs = await processMediaEntries(mediaEntries, structure, options, config, appJson.ShortName, placementPrefs.mediaPlacement, serverTz, toDeleteUIDs);
+  if (!entityFilter || entityFilter.has('media')) {
+    const mediaEntries = appJson.children.media || [];
+    if (mediaEntries.length > 0) {
+      mediaRefs = await processMediaEntries(mediaEntries, structure, options, config, appJson.ShortName, placementPrefs.mediaPlacement, serverTz, toDeleteUIDs);
+    }
   }
 
-  // Step 6: Process other entities (not output, not bin, not content, not media)
+  // Step 5c: Process output hierarchy
   const otherRefs = {};
+  if (!entityFilter || entityFilter.has('output')) {
+    const outputEntries = appJson.children.output || [];
+    if (outputEntries.length > 0) {
+      const outputRefs = await processOutputHierarchy(appJson, structure, options, serverTz);
+      if (outputRefs.length > 0) {
+        otherRefs.output = outputRefs;
+      }
+    }
+  }
+
+  // Step 6: Process other entities (not output hierarchy, not bin, not content, not media)
   for (const [entityName, entries] of Object.entries(appJson.children)) {
-    if (['bin', 'content', 'output', 'media'].includes(entityName)) continue;
+    if (['bin', 'content', 'output', 'output_value', 'output_value_filter',
+         'output_value_entity_column_rel', 'media'].includes(entityName)) continue;
     if (!Array.isArray(entries)) continue;
 
+    // Skip if entity filter is active and this entity doesn't match
+    if (entityFilter && !entityFilter.has(entityName)) continue;
+
     if (ENTITY_DIR_MAP[entityName]) {
       // Entity types with project directories — process into their directory
       const refs = await processEntityDirEntries(entityName, entries, options, serverTz);
@@ -628,18 +660,43 @@ export async function performClone(source, options = {}) {
   // Step 7: Save app.json with references
   await saveAppJson(appJson, contentRefs, otherRefs, effectiveDomain);
 
-  // Step 8: Create .app.json baseline for delta tracking
-  await saveBaselineFile(appJson);
+  // Step 8: Create .app.json baseline for delta tracking (skip in entity-filter mode to avoid overwriting)
+  if (!entityFilter) {
+    await saveBaselineFile(appJson);
+  }
 
   // Step 9: Ensure .app.json is in .gitignore
   await ensureGitignore(['.app.json']);
 
   log.plain('');
-  log.success('Clone complete!');
+  log.success(entityFilter ? `Clone complete! (filtered: ${options.entity})` : 'Clone complete!');
   log.dim('  app.json saved to project root');
   log.dim('  Run "dbo login" to authenticate, then "dbo push" to deploy changes');
 }
 
+/**
+ * Resolve --entity filter into a Set of entity keys to process.
+ * Returns null if no filter (process everything), or a Set of entity key strings.
+ *
+ * "output" expands to all OUTPUT_HIERARCHY_ENTITIES.
+ * Entity-dir names (e.g. "extension", "site") are matched directly.
+ * Documentation aliases are also accepted (e.g. "column" → "output_value").
+ */
+function resolveEntityFilter(entityArg) {
+  if (!entityArg) return null;
+
+  const input = entityArg.toLowerCase().trim();
+
+  // "output" or any output sub-entity → process all output hierarchy entities
+  const docToPhysical = { column: 'output_value', filter: 'output_value_filter', join: 'output_value_entity_column_rel' };
+  if (input === 'output' || OUTPUT_HIERARCHY_ENTITIES.includes(input) || docToPhysical[input]) {
+    return new Set(OUTPUT_HIERARCHY_ENTITIES.concat(['output']));
+  }
+
+  // Direct match on known entity types
+  return new Set([input]);
+}
+
 /**
  * Resolve placement preferences from config or prompt the user.
  * Returns { contentPlacement, mediaPlacement } where values are 'path'|'bin'|'ask'|null
@@ -1700,6 +1757,568 @@ export function guessExtensionForColumn(columnName) {
   return 'txt';
 }
 
+// ─── Output Hierarchy Processing ──────────────────────────────────────────
+
+/**
+ * Build a tree structure from flat output entity arrays.
+ * Groups columns, joins, and filters under their parent output records.
+ *
+ * @param {Object} appJson - The full app JSON with children arrays
+ * @returns {Array} - Array of output root nodes with nested _children
+ */
+export function buildOutputHierarchyTree(appJson) {
+  const outputs = appJson.children.output || [];
+  const columns = appJson.children.output_value || [];
+  const filters = appJson.children.output_value_filter || [];
+  const joins = appJson.children.output_value_entity_column_rel || [];
+
+  if (outputs.length === 0) return [];
+
+  // Index all entities by their numeric ID for O(1) lookups
+  const outputById = new Map();
+  const columnById = new Map();
+  const joinById = new Map();
+
+  for (const o of outputs) {
+    outputById.set(o.OutputID || o._id, { ...o, _children: { column: [], join: [], filter: [] } });
+  }
+  for (const c of columns) {
+    columnById.set(c.OutputValueID || c._id, { ...c, _children: { filter: [] } });
+  }
+  for (const j of joins) {
+    joinById.set(j.OutputValueEntityColumnRelID || j._id, { ...j, _children: { column: [] } });
+  }
+
+  // Attach filters: to column (via OutputValueID) or directly to output (via OutputID)
+  for (const f of filters) {
+    if (f.OutputValueID) {
+      const parent = columnById.get(f.OutputValueID);
+      if (parent) {
+        parent._children.filter.push({ ...f });
+        continue;
+      }
+    }
+    if (f.OutputID) {
+      const parent = outputById.get(f.OutputID);
+      if (parent) {
+        parent._children.filter.push({ ...f });
+      }
+    }
+  }
+
+  // Attach columns: to join (via OutputValueEntityColumnRelID) or directly to output (via OutputID)
+  for (const [, col] of columnById) {
+    if (col.OutputValueEntityColumnRelID) {
+      const parent = joinById.get(col.OutputValueEntityColumnRelID);
+      if (parent) {
+        parent._children.column.push(col);
+        continue;
+      }
+    }
+    if (col.OutputID) {
+      const parent = outputById.get(col.OutputID);
+      if (parent) {
+        parent._children.column.push(col);
+      }
+    }
+  }
+
+  // Attach joins to outputs (via OutputID)
+  for (const [, j] of joinById) {
+    if (j.OutputID) {
+      const parent = outputById.get(j.OutputID);
+      if (parent) {
+        parent._children.join.push(j);
+      }
+    }
+  }
+
+  // Sort children by OrderNumber (ties broken by array index stability)
+  const sortByOrder = (a, b) => (a.OrderNumber || 0) - (b.OrderNumber || 0);
+
+  for (const [, output] of outputById) {
+    output._children.column.sort(sortByOrder);
+    output._children.join.sort(sortByOrder);
+    output._children.filter.sort(sortByOrder);
+
+    for (const col of output._children.column) {
+      col._children.filter.sort(sortByOrder);
+    }
+    for (const j of output._children.join) {
+      j._children.column.sort(sortByOrder);
+      for (const col of j._children.column) {
+        col._children.filter.sort(sortByOrder);
+      }
+    }
+  }
+
+  return Array.from(outputById.values());
+}
+
+/**
+ * Resolve filename column preferences for each output entity type.
+ * Loads from config, prompts if needed, saves choices.
+ *
+ * @param {Object} appJson - The full app JSON
+ * @param {Object} options - CLI options
+ * @returns {Object} - { output: 'Name', output_value: 'Title', ... }
+ */
+async function resolveOutputFilenameColumns(appJson, options) {
+  const defaults = {
+    output: 'Name',
+    output_value: 'Title',
+    output_value_filter: 'ShortName',
+    output_value_entity_column_rel: 'UID',
+  };
+  const fallbacks = {
+    output: ['Name', 'Title', 'OrderNumber', 'UID'],
+    output_value: ['Title', 'Name', 'OrderNumber', 'UID'],
+    output_value_filter: ['ShortName', 'Name', 'UID'],
+    output_value_entity_column_rel: ['UID'],
+  };
+  const docNames = OUTPUT_ENTITY_MAP;
+  const result = {};
+
+  for (const entityKey of OUTPUT_HIERARCHY_ENTITIES) {
+    // Check saved preference
+    const saved = await loadOutputFilenamePreference(entityKey);
+    if (saved) {
+      result[entityKey] = saved;
+      continue;
+    }
+
+    // In -y mode use defaults
+    if (options.yes) {
+      result[entityKey] = defaults[entityKey];
+      await saveOutputFilenamePreference(entityKey, defaults[entityKey]);
+      continue;
+    }
+
+    // Find a sample record to get available columns
+    const records = appJson.children[entityKey] || [];
+    if (records.length === 0) {
+      result[entityKey] = defaults[entityKey];
+      continue;
+    }
+
+    const sampleRecord = records[0];
+    const columns = Object.keys(sampleRecord).filter(k => k !== 'children' && !k.startsWith('_'));
+
+    // Find best default from fallback chain
+    let defaultCol = defaults[entityKey];
+    for (const fb of fallbacks[entityKey]) {
+      if (columns.includes(fb)) { defaultCol = fb; break; }
+    }
+
+    const inquirer = (await import('inquirer')).default;
+    const { col } = await inquirer.prompt([{
+      type: 'list',
+      name: 'col',
+      message: `Which column should be used as the filename for ${docNames[entityKey]} (${entityKey}) records?`,
+      choices: columns,
+      default: defaultCol,
+    }]);
+
+    result[entityKey] = col;
+    await saveOutputFilenamePreference(entityKey, col);
+    log.dim(`  Saved filename column preference for ${entityKey}`);
+  }
+
+  return result;
+}
+
+/**
+ * Build a filename for an output hierarchy entity.
+ * Uses dot-separated hierarchical naming: _output~<name>~<uid>.column~<name>~<uid>.json
+ *
+ * @param {string} entityType - Documentation name: 'output', 'column', 'join', 'filter'
+ * @param {Object} node - The entity record
+ * @param {string} filenameCol - Column to use for the name portion
+ * @param {string[]} parentChain - Array of parent segments: ['_output~name~uid', 'join~name~uid', ...]
+ * @returns {string} - Base filename without extension
+ */
+export function buildOutputFilename(entityType, node, filenameCol, parentChain = []) {
+  const uid = node.UID || '';
+  const rawName = node[filenameCol];
+  const name = rawName ? sanitizeFilename(String(rawName)) : '';
+
+  // Build this entity's segment: <type>~<name>~<uid>
+  // If filenameCol IS the UID, don't double-append it
+  let segment;
+  if (!name || name === uid) {
+    segment = `${entityType}~${uid}`;
+  } else {
+    segment = `${entityType}~${name}~${uid}`;
+  }
+
+  // Root output gets _ prefix
+  if (entityType === 'output') {
+    segment = `_${segment}`;
+  }
+
+  const allSegments = [...parentChain, segment];
+  return allSegments.join('.');
+}
+
+/**
+ * Parse an output hierarchy filename back into entity relationships.
+ *
+ * @param {string} filename - e.g. "_output~name~uid.column~name~uid.filter~name~uid.json"
+ * @returns {Object} - { segments: [{entity, name, uid}], rootOutputUid, entityType, uid }
+ */
+export function parseOutputHierarchyFile(filename) {
+  // Strip .json extension
+  let base = filename;
+  if (base.endsWith('.json')) base = base.substring(0, base.length - 5);
+
+  // Split into segments by finding entity type boundaries
+  // Entity types are: _output~, output~, column~, join~, filter~
+  const parts = [];
+
+  // First, split by '.' but we need to be careful since names can contain '.'
+  // Strategy: find entity-type prefixed segments
+  // Split on '.' then re-join segments that don't start with an entity type
+  const dotParts = base.split('.');
+  let currentSegment = null;
+
+  for (const part of dotParts) {
+    // Check if this part starts with an entity type prefix
+    const stripped = part.replace(/^_/, '');
+    const match = stripped.match(/^(output|column|join|filter)~/);
+
+    if (match) {
+      if (currentSegment !== null) {
+        parts.push(currentSegment);
+      }
+      currentSegment = part;
+    } else if (currentSegment !== null) {
+      // This part belongs to the previous segment (name contained '.')
+      currentSegment += '.' + part;
+    } else {
+      currentSegment = part;
+    }
+  }
+  if (currentSegment !== null) {
+    parts.push(currentSegment);
+  }
+
+  // Parse each segment: <type>~<name>~<uid> or <type>~<uid>
+  const segments = [];
+  for (const part of parts) {
+    const stripped = part.replace(/^_/, '');
+    const firstTilde = stripped.indexOf('~');
+    if (firstTilde < 0) continue;
+
+    const entityType = stripped.substring(0, firstTilde);
+    const rest = stripped.substring(firstTilde + 1);
+
+    // The UID is the last ~-separated value (UIDs are alphanumeric, typically 8+ chars)
+    const lastTilde = rest.lastIndexOf('~');
+    let name, uid;
+    if (lastTilde >= 0) {
+      name = rest.substring(0, lastTilde);
+      uid = rest.substring(lastTilde + 1);
+    } else {
+      // No second tilde — the entire rest is the UID
+      name = null;
+      uid = rest;
+    }
+
+    segments.push({ entity: entityType, name, uid });
+  }
+
+  if (segments.length === 0) return null;
+
+  const last = segments[segments.length - 1];
+  const root = segments[0];
+
+  // Map documentation name back to physical table name
+  const docToPhysical = {
+    output: 'output',
+    column: 'output_value',
+    filter: 'output_value_filter',
+    join: 'output_value_entity_column_rel',
+  };
+
+  return {
+    segments,
+    rootOutputUid: root.uid,
+    entityType: last.entity,
+    physicalEntity: docToPhysical[last.entity] || last.entity,
+    uid: last.uid,
+    parentEntity: segments.length > 1 ? segments[segments.length - 2].entity : null,
+    parentUid: segments.length > 1 ? segments[segments.length - 2].uid : null,
+  };
+}
+
+/**
+ * Main orchestrator: process output hierarchy entities during clone.
+ * Builds tree, resolves filenames, writes hierarchy files.
+ *
+ * @param {Object} appJson - The full app JSON
+ * @param {Object} structure - Bin hierarchy structure
+ * @param {Object} options - CLI options
+ * @param {string} serverTz - Server timezone
+ * @returns {Array} - Array of { uid, metaPath } for app.json reference replacement
+ */
+async function processOutputHierarchy(appJson, structure, options, serverTz) {
+  const tree = buildOutputHierarchyTree(appJson);
+  if (tree.length === 0) return [];
+
+  log.info(`Processing ${tree.length} output record(s) with hierarchy...`);
+
+  // Resolve filename columns for each entity type
+  const filenameCols = await resolveOutputFilenameColumns(appJson, options);
+
+  const refs = [];
+  const bulkAction = { value: null };
+  const config = await loadConfig();
+  // When --force flag is set, skip change detection and re-process all files
+  const forceReprocess = !!options.force;
+
+  for (const output of tree) {
+    // Resolve bin directory for this output
+    let binDir = null;
+    let chosenBinId = null;
+    if (output.BinID && structure[output.BinID]) {
+      binDir = resolveBinPath(output.BinID, structure);
+    }
+
+    if (!binDir) {
+      // No BinID — prompt or default
+      if (!options.yes) {
+        const inquirer = (await import('inquirer')).default;
+        const binChoices = Object.entries(structure).map(([id, entry]) => ({
+          name: `${entry.name} (${entry.fullPath})`,
+          value: id,
+        }));
+
+        if (binChoices.length > 0) {
+          const { binId } = await inquirer.prompt([{
+            type: 'list',
+            name: 'binId',
+            message: `Output "${output.Name || output.UID}" has no BinID. Which bin should it go in?`,
+            choices: binChoices,
+          }]);
+          chosenBinId = Number(binId);
+          binDir = resolveBinPath(chosenBinId, structure);
+        } else {
+          binDir = BINS_DIR;
+        }
+      } else {
+        binDir = BINS_DIR;
+      }
+    }
+
+    await mkdir(binDir, { recursive: true });
+
+    // Build root output filename
+    const rootBasename = buildOutputFilename('output', output, filenameCols.output);
+    const rootMetaPath = join(binDir, `${rootBasename}.json`);
+
+    // Change detection for existing files (skip when --entity forces re-processing)
+    if (await fileExists(rootMetaPath) && !options.yes && !forceReprocess) {
+      if (bulkAction.value === 'skip_all') {
+        log.dim(`  Skipped ${rootBasename}`);
+        refs.push({ uid: output.UID, metaPath: rootMetaPath });
+        continue;
+      }
+      if (bulkAction.value !== 'overwrite_all') {
+        const localSyncTime = await getLocalSyncTime(rootMetaPath);
+        const serverNewer = isServerNewer(localSyncTime, output._LastUpdated, config);
+        if (serverNewer) {
+          const action = await promptChangeDetection(rootBasename, output, config);
+          if (action === 'skip') { refs.push({ uid: output.UID, metaPath: rootMetaPath }); continue; }
+          if (action === 'skip_all') { bulkAction.value = 'skip_all'; refs.push({ uid: output.UID, metaPath: rootMetaPath }); continue; }
+          if (action === 'overwrite_all') { bulkAction.value = 'overwrite_all'; }
+          if (action === 'compare') { await inlineDiffAndMerge(output, rootMetaPath, config); refs.push({ uid: output.UID, metaPath: rootMetaPath }); continue; }
+        } else {
+          const locallyModified = await hasLocalModifications(rootMetaPath, config);
+          if (locallyModified) {
+            const action = await promptChangeDetection(rootBasename, output, config, { localIsNewer: true });
+            if (action === 'skip') { refs.push({ uid: output.UID, metaPath: rootMetaPath }); continue; }
+            if (action === 'skip_all') { bulkAction.value = 'skip_all'; refs.push({ uid: output.UID, metaPath: rootMetaPath }); continue; }
+            if (action === 'overwrite_all') { bulkAction.value = 'overwrite_all'; }
+            if (action === 'compare') { await inlineDiffAndMerge(output, rootMetaPath, config, { localIsNewer: true }); refs.push({ uid: output.UID, metaPath: rootMetaPath }); continue; }
+          } else {
+            log.dim(`  Up to date: ${rootBasename}`);
+            refs.push({ uid: output.UID, metaPath: rootMetaPath });
+            continue;
+          }
+        }
+      }
+    }
+
+    // Collect child file references for root JSON
+    const childRefs = { column: [], join: [], filter: [] };
+
+    // Helper to build a child filename segment
+    const childSegment = (type, node, col) => {
+      const uid = node.UID || '';
+      const rawName = node[col];
+      const name = rawName ? sanitizeFilename(String(rawName)) : '';
+      return (!name || name === uid) ? `${type}~${uid}` : `${type}~${name}~${uid}`;
+    };
+
+    // Process all children depth-first
+    // Direct filters on output
+    for (const filter of output._children.filter) {
+      const filterName = `${rootBasename}.${childSegment('filter', filter, filenameCols.output_value_filter)}`;
+      const filterPath = join(binDir, `${filterName}.json`);
+      await writeOutputEntityFile(filter, 'output_value_filter', filterPath, serverTz);
+      childRefs.filter.push(`@${filterPath}`);
+    }
+
+    // Direct columns on output
+    for (const col of output._children.column) {
+      const colSeg = childSegment('column', col, filenameCols.output_value);
+      const colName = `${rootBasename}.${colSeg}`;
+      const colPath = join(binDir, `${colName}.json`);
+      await writeOutputEntityFile(col, 'output_value', colPath, serverTz);
+      childRefs.column.push(`@${colPath}`);
+
+      // Filters under this column
+      for (const filter of col._children.filter) {
+        const filterName = `${colName}.${childSegment('filter', filter, filenameCols.output_value_filter)}`;
+        const filterPath = join(binDir, `${filterName}.json`);
+        await writeOutputEntityFile(filter, 'output_value_filter', filterPath, serverTz);
+        childRefs.filter.push(`@${filterPath}`);
+      }
+    }
+
+    // Joins on output
+    for (const j of output._children.join) {
+      const joinSeg = childSegment('join', j, filenameCols.output_value_entity_column_rel);
+      const joinName = `${rootBasename}.${joinSeg}`;
+      const joinPath = join(binDir, `${joinName}.json`);
+      await writeOutputEntityFile(j, 'output_value_entity_column_rel', joinPath, serverTz);
+      childRefs.join.push(`@${joinPath}`);
+
+      // Columns under this join
+      for (const col of j._children.column) {
+        const joinColName = `${joinName}.${childSegment('column', col, filenameCols.output_value)}`;
+        const joinColPath = join(binDir, `${joinColName}.json`);
+        await writeOutputEntityFile(col, 'output_value', joinColPath, serverTz);
+        childRefs.column.push(`@${joinColPath}`);
+
+        // Filters under this join→column
+        for (const filter of col._children.filter) {
+          const filterName = `${joinColName}.${childSegment('filter', filter, filenameCols.output_value_filter)}`;
+          const filterPath = join(binDir, `${filterName}.json`);
+          await writeOutputEntityFile(filter, 'output_value_filter', filterPath, serverTz);
+          childRefs.filter.push(`@${filterPath}`);
+        }
+      }
+    }
+
+    // Write root output JSON with child references
+    const rootMeta = {};
+    const rootContentColumns = [];
+    for (const [key, value] of Object.entries(output)) {
+      if (key === '_children') continue;
+
+      // Always extract CustomSQL to companion .sql file
+      if (key === 'CustomSQL') {
+        const decoded = resolveContentValue(value);
+        const sqlContent = (decoded && decoded.trim()) ? decoded : '';
+        const sqlFilePath = rootMetaPath.replace(/\.json$/, '.CustomSQL.sql');
+        await writeFile(sqlFilePath, sqlContent);
+        rootMeta[key] = `@${basename(sqlFilePath)}`;
+        rootContentColumns.push('CustomSQL');
+        if (serverTz && (output._CreatedOn || output._LastUpdated)) {
+          try { await setFileTimestamps(sqlFilePath, output._CreatedOn, output._LastUpdated, serverTz); } catch { /* non-critical */ }
+        }
+        log.dim(`  → ${sqlFilePath}`);
+        continue;
+      }
+
+      if (value && typeof value === 'object' && !Array.isArray(value) && value.encoding === 'base64') {
+        rootMeta[key] = resolveContentValue(value);
+      } else {
+        rootMeta[key] = value;
+      }
+    }
+    rootMeta._entity = 'output';
+    if (rootContentColumns.length > 0) {
+      rootMeta._contentColumns = rootContentColumns;
+    }
+    rootMeta.children = childRefs;
+
+    // If user chose a bin for a BinID-less output, store it and mark as modified
+    if (chosenBinId) {
+      rootMeta.BinID = chosenBinId;
+      log.dim(`  Set BinID=${chosenBinId} on "${output.Name || output.UID}" (staged for next push)`);
+    }
+
+    await writeFile(rootMetaPath, JSON.stringify(rootMeta, null, 2) + '\n');
+    log.success(`Saved ${rootMetaPath}`);
+
+    // Set file timestamps to server's _LastUpdated so diff detection works.
+    // Skip when chosenBinId is set — keep mtime at "now" so push detects the local edit.
+    if (!chosenBinId && serverTz && (output._CreatedOn || output._LastUpdated)) {
+      try {
+        await setFileTimestamps(rootMetaPath, output._CreatedOn, output._LastUpdated, serverTz);
+      } catch { /* non-critical */ }
+    }
+
+    refs.push({ uid: output.UID, metaPath: rootMetaPath });
+  }
+
+  return refs;
+}
+
+/**
+ * Write a single output hierarchy entity file (column, join, or filter).
+ * Handles CustomSQL extraction to companion .sql files.
+ */
+async function writeOutputEntityFile(node, physicalEntity, filePath, serverTz) {
+  const meta = {};
+  const contentColumns = [];
+
+  for (const [key, value] of Object.entries(node)) {
+    if (key === '_children') continue;
+
+    // Always extract CustomSQL to companion .sql file
+    if (key === 'CustomSQL') {
+      const decoded = resolveContentValue(value);
+      const sqlContent = (decoded && decoded.trim()) ? decoded : '';
+      const sqlFilePath = filePath.replace(/\.json$/, '.CustomSQL.sql');
+      await writeFile(sqlFilePath, sqlContent);
+      meta[key] = `@${basename(sqlFilePath)}`;
+      contentColumns.push('CustomSQL');
+
+      if (serverTz && (node._CreatedOn || node._LastUpdated)) {
+        try {
+          await setFileTimestamps(sqlFilePath, node._CreatedOn, node._LastUpdated, serverTz);
+        } catch { /* non-critical */ }
+      }
+      log.dim(`  → ${sqlFilePath}`);
+      continue;
+    }
+
+    // Decode other base64 columns inline
+    if (value && typeof value === 'object' && !Array.isArray(value) && value.encoding === 'base64') {
+      meta[key] = resolveContentValue(value);
+    } else {
+      meta[key] = value;
+    }
+  }
+
+  meta._entity = physicalEntity;
+  if (contentColumns.length > 0) {
+    meta._contentColumns = contentColumns;
+  }
+
+  await writeFile(filePath, JSON.stringify(meta, null, 2) + '\n');
+  log.dim(`  → ${filePath}`);
+
+  if (serverTz && (node._CreatedOn || node._LastUpdated)) {
+    try {
+      await setFileTimestamps(filePath, node._CreatedOn, node._LastUpdated, serverTz);
+    } catch { /* non-critical */ }
+  }
+}
+
 /**
  * Save app.json to project root with @ references replacing processed entries.
  */
@@ -1731,7 +2350,13 @@ async function saveAppJson(appJson, contentRefs, otherRefs, domain) {
   }
 
   // Bins stay as-is (directory structure, no metadata files)
-  // Output stays as-is (ignored for now)
+
+  // Remove sub-entity arrays that are now embedded in output hierarchy files
+  if (otherRefs.output) {
+    delete output.children.output_value;
+    delete output.children.output_value_filter;
+    delete output.children.output_value_entity_column_rel;
+  }
 
   await writeFile('app.json', JSON.stringify(output, null, 2) + '\n');
 }