@dboio/cli 0.17.0 → 0.19.1

package/src/commands/clone.js

@@ -13,10 +13,17 @@ import { loadIgnore } from '../lib/ignore.js';
 import { checkDomainChange } from '../lib/domain-guard.js';
 import { applyTrashIcon, ensureTrashIcon, tagProjectFiles } from '../lib/tagging.js';
 import { loadMetadataSchema, saveMetadataSchema, getTemplateCols, setTemplateCols, buildTemplateFromCloneRecord, generateMetadataFromSchema, parseReferenceExpression, mergeDescriptorSchemaFromDependencies } from '../lib/metadata-schema.js';
-import { fetchSchema, loadSchema, saveSchema, isSchemaStale, SCHEMA_FILE } from '../lib/schema.js';
+import { fetchSchema, loadSchema, saveSchema, isSchemaStale } from '../lib/schema.js';
+import { appMetadataPath } from '../lib/config.js';
 import { runPendingMigrations } from '../lib/migrations.js';
 import { upsertDeployEntry } from '../lib/deploy-config.js';
 import { syncDependencies, parseDependenciesColumn } from '../lib/dependencies.js';
+import { sep } from 'path';
+
+/** True when cwd is inside app_dependencies/ (dependency checkout clone). */
+function isDependencyCheckout() {
+  return process.cwd().includes(`${sep}app_dependencies${sep}`);
+}
 import { mergeDependencies } from '../lib/config.js';
 
 /**
@@ -34,6 +41,32 @@ export function resolveContentValue(value) {
   return value !== null && value !== undefined ? String(value) : null;
 }
 
+/**
+ * Embed a server children object into metadata, decoding any base64 field values.
+ * Used by processEntityDirEntries() and processExtensionEntries().
+ *
+ * @param {Object} childrenObj - Server-side children: { entity_column: [...], ... }
+ * @returns {Object} - Decoded children object safe to write to metadata
+ */
+export function embedEntityChildren(childrenObj) {
+  const result = {};
+  for (const [childEntityName, childArray] of Object.entries(childrenObj)) {
+    if (!Array.isArray(childArray)) continue;
+    result[childEntityName] = childArray.map(child => {
+      const embedded = {};
+      for (const [k, v] of Object.entries(child)) {
+        if (v && typeof v === 'object' && !Array.isArray(v) && v.encoding === 'base64') {
+          embedded[k] = resolveContentValue(v) ?? '';
+        } else {
+          embedded[k] = v;
+        }
+      }
+      return embedded;
+    });
+  }
+  return result;
+}
+
 export function sanitizeFilename(name) {
   return name.replace(/[/\\?%*:|"<>]/g, '-').replace(/\s+/g, '-').substring(0, 200);
 }
@@ -491,6 +524,49 @@ async function detectAndRenameLegacyCompanions(metaPath, meta) {
   return metaChanged;
 }
 
+/**
+ * Clean up double/triple-metadata files (e.g., "app.metadata.metadata~uid.json")
+ * caused by an older bug where buildMetaFilename received a base already containing ".metadata".
+ * Scans lib/ directories for files matching the pattern and removes them.
+ */
+async function cleanDoubleMetadataFiles() {
+  const libDir = join(process.cwd(), 'lib');
+  if (!await fileExists(libDir)) return;
+
+  const trashDir = join(process.cwd(), 'trash');
+  let cleaned = 0;
+
+  async function scan(dir) {
+    let entries;
+    try { entries = await readdir(dir, { withFileTypes: true }); } catch { return; }
+
+    for (const entry of entries) {
+      if (entry.name.startsWith('.')) continue;
+      const full = join(dir, entry.name);
+
+      if (entry.isDirectory()) {
+        if (['node_modules', 'trash', '.git', '.app', 'app_dependencies'].includes(entry.name)) continue;
+        await scan(full);
+        continue;
+      }
+
+      // Detect double+ .metadata pattern: "name.metadata.metadata~uid.json" or "name.metadata.metadata.metadata~uid.json"
+      if (/\.metadata\.metadata[.~]/.test(entry.name)) {
+        try {
+          await mkdir(trashDir, { recursive: true });
+          await rename(full, join(trashDir, entry.name));
+          cleaned++;
+        } catch { /* non-critical */ }
+      }
+    }
+  }
+
+  await scan(libDir);
+  if (cleaned > 0) {
+    log.dim(`  Cleaned ${cleaned} duplicate metadata file(s) → trash/`);
+  }
+}
+
 /**
  * Scan all directories under Bins/ for orphaned legacy ~UID companion files
  * that no metadata @reference points to, and move them to trash/.
@@ -793,7 +869,7 @@ async function stageCollisionDeletions(toDelete, appJson, options) {
   }
 
   if (staged > 0) {
-    log.success(`${staged} record(s) staged in .dbo/synchronize.json`);
+    log.success(`${staged} record(s) staged in .app/synchronize.json`);
     log.dim('  Run "dbo push" to delete from server');
   }
 }
@@ -935,7 +1011,7 @@ async function checkPendingSynchronize(options) {
   if (totalCount === 0) return;
 
   log.warn('');
-  log.warn(`  ⚠  There are ${totalCount} un-pushed staged item(s) in .dbo/synchronize.json:`);
+  log.warn(`  ⚠  There are ${totalCount} un-pushed staged item(s) in .app/synchronize.json:`);
   if (deleteCount > 0) log.warn(`     ${deleteCount} pending deletion(s)`);
   if (editCount > 0) log.warn(`     ${editCount} pending edit(s)`);
   if (addCount > 0) log.warn(`     ${addCount} pending add(s)`);
@@ -1019,34 +1095,8 @@ export async function performClone(source, options = {}) {
   const effectiveDomain = options.domain || config.domain;
   let appJson;
 
-  // Fetch schema if missing, explicitly requested, or server has a newer version
+  // Load local schema (server fetch deferred until after auth validation)
   let schema = await loadSchema();
-  let shouldFetch = !schema || options.schema;
-  if (!shouldFetch && schema) {
-    try {
-      shouldFetch = await isSchemaStale({ domain: effectiveDomain, verbose: options.verbose });
-      if (shouldFetch) log.dim(`  Server schema is newer — refreshing schema.json`);
-    } catch {
-      // Can't check — continue with local schema
-    }
-  }
-  if (shouldFetch) {
-    try {
-      schema = await fetchSchema({ domain: effectiveDomain, verbose: options.verbose });
-      await saveSchema(schema);
-      log.dim(`  Saved schema.json`);
-    } catch (err) {
-      if (!schema) log.warn(`  Could not fetch schema: ${err.message}`);
-      // Continue with stale schema or null
-    }
-  }
-
-  // Regenerate metadata_schema.json for any new entity types
-  if (schema) {
-    const existing = await loadMetadataSchema();
-    const updated = generateMetadataFromSchema(schema, existing ?? {});
-    await saveMetadataSchema(updated);
-  }
 
   // Step 1: Source mismatch detection (skip in pull mode)
   // Warn when the user provides an explicit source that differs from the stored one.
@@ -1072,7 +1122,9 @@ export async function performClone(source, options = {}) {
     }
   }
 
-  // Step 2: Load the app JSON — retry loop with fallback prompt on failure
+  // Step 2: Load the app JSON — retry loop with fallback prompt on failure.
+  // This runs BEFORE schema/dependency sync so that the login prompt fires
+  // here if the session is expired (not buried inside a silent dependency clone).
   let activeSource = source;
   while (true) {
     try {
@@ -1102,6 +1154,35 @@ export async function performClone(source, options = {}) {
     throw new Error('Invalid app JSON: missing UID or children');
   }
 
+  // Fetch schema if missing, explicitly requested, or server has a newer version.
+  // Runs AFTER app fetch so that login prompt fires first on expired session.
+  let shouldFetchSchema = !schema || options.schema;
+  if (!shouldFetchSchema && schema) {
+    try {
+      shouldFetchSchema = await isSchemaStale({ domain: effectiveDomain, verbose: options.verbose });
+      if (shouldFetchSchema) log.dim(`  Server schema is newer — refreshing _system dependency baseline`);
+    } catch {
+      // Can't check — continue with local schema
+    }
+  }
+  if (shouldFetchSchema) {
+    try {
+      schema = await fetchSchema({ domain: effectiveDomain, verbose: options.verbose });
+      await saveSchema(schema);
+      log.dim(`  Refreshed _system dependency baseline`);
+    } catch (err) {
+      if (!schema) log.warn(`  Could not fetch schema: ${err.message}`);
+      // Continue with stale schema or null
+    }
+  }
+
+  // Regenerate metadata_schema.json for any new entity types
+  if (schema) {
+    const existing = await loadMetadataSchema();
+    const updated = generateMetadataFromSchema(schema, existing ?? {});
+    await saveMetadataSchema(updated);
+  }
+
   // Domain change detection
   if (effectiveDomain) {
     const { changed, proceed } = await checkDomainChange(effectiveDomain, options);
@@ -1118,10 +1199,12 @@ export async function performClone(source, options = {}) {
     await checkPendingSynchronize(options);
   }
 
-  // Ensure sensitive files are gitignored
-  await ensureGitignore(['.dbo/credentials.json', '.dbo/cookies.txt', '.dbo/.app_baseline.json']);
+  // Ensure sensitive files are gitignored (skip for dependency checkouts — not user projects)
+  if (!isDependencyCheckout()) {
+    await ensureGitignore(['.app/credentials.json', '.app/cookies.txt', '.app/ticketing.local.json', '.app/scripts.local.json', '.app/errors.log', 'app_dependencies/']);
+  }
 
-  // Step 2: Update .dbo/config.json (skip in pull mode — config already set)
+  // Step 2: Update .app/config.json (skip in pull mode — config already set)
   if (!options.pullMode) {
     await updateConfigWithApp({
       AppID: appJson.AppID,
@@ -1130,9 +1213,9 @@ export async function performClone(source, options = {}) {
       AppShortName: appJson.ShortName,
     });
     await saveCloneSource(activeSource || 'default');
-    log.dim('  Updated .dbo/config.json with app metadata');
+    log.dim('  Updated .app/config.json with app metadata');
 
-    // Merge Dependencies from app.json into .dbo/config.json
+    // Merge Dependencies into .app/config.json
     // Always ensure at least ["_system"] is persisted
     const fromApp = parseDependenciesColumn(appJson.Dependencies);
     if (fromApp.length > 0) {
@@ -1164,8 +1247,8 @@ export async function performClone(source, options = {}) {
     }
   }
 
-  // Step 3: Update package.json (skip in pull mode)
-  if (!options.pullMode) {
+  // Step 3: Update package.json (skip in pull mode and dependency checkouts)
+  if (!options.pullMode && !isDependencyCheckout()) {
     await updatePackageJson(appJson, config);
   }
 
@@ -1183,7 +1266,7 @@ export async function performClone(source, options = {}) {
         force: explicitDeps ? true : options.force,
         schema: options.schema,
         verbose: options.verbose,
-        systemSchemaPath: join(process.cwd(), SCHEMA_FILE),
+        systemSchemaPath: join(process.cwd(), 'app_dependencies', '_system', '.app', '_system.json'),
         only: explicitDeps || undefined,
       });
     } catch (err) {
@@ -1209,19 +1292,28 @@ export async function performClone(source, options = {}) {
   const structure = buildBinHierarchy(bins, appJson.AppID);
 
   if (!options.pullMode) {
-    for (const dir of SCAFFOLD_DIRS) {
+    // Inside app_dependencies/: skip development-only scaffold dirs (src, test, trash)
+    const isDependencyCheckout = process.cwd().includes(`${sep}app_dependencies${sep}`);
+    const DEP_SKIP_DIRS = new Set(['src', 'test', 'trash']);
+    const dirsToScaffold = isDependencyCheckout
+      ? SCAFFOLD_DIRS.filter(d => !DEP_SKIP_DIRS.has(d))
+      : SCAFFOLD_DIRS;
+
+    for (const dir of dirsToScaffold) {
       await mkdir(dir, { recursive: true });
     }
 
     // Best-effort: apply trash icon
-    await applyTrashIcon(join(process.cwd(), 'trash'));
+    if (!isDependencyCheckout) {
+      await applyTrashIcon(join(process.cwd(), 'trash'));
+    }
 
     const createdDirs = await createDirectories(structure);
     await saveStructureFile(structure);
 
-    const totalDirs = SCAFFOLD_DIRS.length + createdDirs.length;
+    const totalDirs = dirsToScaffold.length + createdDirs.length;
     log.success(`Created ${totalDirs} director${totalDirs === 1 ? 'y' : 'ies'}`);
-    for (const d of SCAFFOLD_DIRS) log.dim(`  ${d}/`);
+    for (const d of dirsToScaffold) log.dim(`  ${d}/`);
     for (const d of createdDirs) log.dim(`  ${d}/`);
 
     // Warn about legacy root-level entity directories
@@ -1250,7 +1342,7 @@ export async function performClone(source, options = {}) {
   if (!serverTz || serverTz === 'UTC') {
     serverTz = 'America/Los_Angeles';
     await updateConfigWithApp({ ServerTimezone: serverTz });
-    log.dim(`  Set ServerTimezone to ${serverTz} in .dbo/config.json`);
+    log.dim(`  Set ServerTimezone to ${serverTz} in .app/config.json`);
   }
 
   // Resolve --entity filter: which entity types to process
@@ -1300,8 +1392,8 @@ export async function performClone(source, options = {}) {
     );
   }
 
-  // Step 5a: Write manifest.json to project root (from server content or resolved template)
-  if (!entityFilter || entityFilter.has('content')) {
+  // Step 5a: Write manifest.json to project root (skip for dependency checkouts)
+  if ((!entityFilter || entityFilter.has('content')) && !isDependencyCheckout()) {
     await writeManifestJson(appJson, contentRefs);
   }
 
@@ -1358,7 +1450,7 @@ export async function performClone(source, options = {}) {
   // Step 7: Save app.json with references
   await saveAppJson(appJson, contentRefs, otherRefs, effectiveDomain);
 
-  // Step 8: Create .dbo/.app_baseline.json baseline for delta tracking (skip in entity-filter mode to avoid overwriting)
+  // Step 8: Create .app/<shortName>.json baseline for delta tracking (skip in entity-filter mode to avoid overwriting)
   if (!entityFilter) {
     await saveBaselineFile(appJson);
     resetBaselineCache(); // invalidate so next operation reloads the fresh baseline
@@ -1374,13 +1466,17 @@ export async function performClone(source, options = {}) {
   // Step 9: Trash orphaned legacy ~UID companion files that no metadata references
   await trashOrphanedLegacyCompanions();
 
+  // Step 9b: Clean up double-metadata files (e.g., "app.metadata.metadata~uid.json")
+  // caused by an older bug where buildMetaFilename received a base already containing ".metadata"
+  await cleanDoubleMetadataFiles();
+
   // Step 10: Tag project files with sync status (best-effort, non-blocking)
   tagProjectFiles({ verbose: false }).catch(() => {});
 
   log.plain('');
   const verb = options.pullMode ? 'Pull' : 'Clone';
   log.success(entityFilter ? `${verb} complete! (filtered: ${options.entity})` : `${verb} complete!`);
-  log.dim('  app.json saved to project root');
+  log.dim('  App metadata saved to .app/');
   if (!options.pullMode) {
     log.dim('  Run "dbo login" to authenticate, then "dbo push" to deploy changes');
   }
@@ -1546,7 +1642,24 @@ async function fetchAppFromServer(appShortName, options, config) {
     throw new Error(`No app found with ShortName "${appShortName}"`);
   }
 
-  spinner.succeed(`Found app on server`);
+  // Heuristic: detect sparse responses — may indicate expired session or
+  // limited permissions on the target app. Warn but proceed: the server may
+  // intentionally scope /api/app/object responses by user security.
+  const children = appRecord.children || {};
+  const childKeys = Object.keys(children);
+  const hasContentOrMedia = children.content?.length > 0 || children.media?.length > 0 || children.bin?.length > 0;
+  if (childKeys.length > 0 && !hasContentOrMedia) {
+    const totalRecords = childKeys.reduce((sum, k) => sum + (Array.isArray(children[k]) ? children[k].length : 0), 0);
+    if (totalRecords <= 5) {
+      spinner.warn(`App "${appShortName}" returned sparse data (${totalRecords} record(s), no content/media/bins)`);
+      log.warn('  If data is missing, check permissions or run "dbo login" and re-clone.');
+    } else {
+      spinner.succeed(`Found app on server`);
+    }
+  } else {
+    spinner.succeed(`Found app on server`);
+  }
+
   return appRecord;
 }
 
@@ -1967,7 +2080,14 @@ async function processEntityDirEntries(entityName, entries, options, serverTz) {
     const extractedContentCols = [];
 
     for (const [key, value] of Object.entries(record)) {
-      if (key === 'children') continue;
+      if (key === 'children') {
+        // Embed children inline with base64 decoding (entity_column, security_column, etc.)
+        if (value && typeof value === 'object' && !Array.isArray(value)
+            && Object.keys(value).length > 0) {
+          meta.children = embedEntityChildren(value);
+        }
+        continue;
+      }
 
       // Check if this column should be extracted as a companion file
       const extractInfo = contentColsToExtract.find(c => c.col === key);
@@ -2105,7 +2225,7 @@ async function buildDescriptorPrePass(extensionEntries, structure, metadataSchem
   }
 
   await saveDescriptorMapping(structure, mapping);
-  log.dim(`  Saved descriptorMapping to .dbo/structure.json`);
+  log.dim(`  Saved descriptorMapping to .app/directories.json`);
 
   // Parse form-control-code from descriptor_definition records → populate metadata_schema.json
   const descriptorDefs = extensionEntries.filter(r =>
@@ -2545,7 +2665,14 @@ async function processExtensionEntries(entries, structure, options, serverTz) {
       const extractedCols = [];
 
       for (const [key, value] of Object.entries(record)) {
-        if (key === 'children') continue;
+        if (key === 'children') {
+          // Embed children inline with base64 decoding
+          if (value && typeof value === 'object' && !Array.isArray(value)
+              && Object.keys(value).length > 0) {
+            meta.children = embedEntityChildren(value);
+          }
+          continue;
+        }
 
         const companionRef = companionRefs.find(r => r.column.toLowerCase() === key.toLowerCase());
         if (companionRef) {
@@ -2878,7 +3005,7 @@ async function processMediaEntries(mediaRecords, structure, options, config, app
         log.dim(`  Error: ${err.message}`);
       }
 
-      // Append to .dbo/errors.log
+      // Append to .app/errors.log
       await appendErrorLog({
         timestamp: new Date().toISOString(),
         command: 'clone',
@@ -2957,7 +3084,7 @@ async function processMediaEntries(mediaRecords, structure, options, config, app
       });
       log.dim(`  Staged: ${stale.filename}`);
     }
-    log.success('Stale media records staged in .dbo/synchronize.json');
+    log.success('Stale media records staged in .app/synchronize.json');
     log.dim('  Run "dbo push" to delete from server');
   }
 
@@ -3024,7 +3151,9 @@ async function processRecord(entityName, record, structure, options, usedNames,
   }
 
   // If no extension determined and Content column has data, prompt user to choose one
-  if (!ext && !options.yes && record.Content) {
+  // Only prompt when --configure is set; otherwise skip silently (companion extraction
+  // should not surprise the user with interactive prompts during normal clone/pull)
+  if (!ext && options.configure && !options.yes && record.Content) {
     const cv = record.Content;
     const hasContentData = cv && (
       (typeof cv === 'object' && cv.value !== null && cv.value !== undefined) ||
@@ -3574,27 +3703,23 @@ async function extractCustomSqlIfNeeded(entityObj, companionStem, outputDir, ser
 
 /**
  * Recursively build a children object for a parent entity.
- * Mutates parentObj to set parentObj.children = { column: [], join: [], filter: [] }.
- * Returns companionFiles: string[] of written companion file basenames.
+ * Mutates parentObj to set parentObj.children keyed by physical entity names:
+ *   { output_value: [], output_value_filter: [], output_value_entity_column_rel: [] }
  *
  * Each child object retains _entity set to the physical entity name
- * (output_value, output_value_entity_column_rel, output_value_filter)
  * so that push can route submissions correctly.
  *
+ * Child CustomSQL values are decoded inline as strings — only the root output's
+ * CustomSQL is extracted as a companion .sql file (done by the caller).
+ *
  * @param {Object} parentObj - The entity object to populate (mutated in place)
  * @param {Object} node - Tree node from buildOutputHierarchyTree (has _children)
- * @param {string} rootStem - Root output file stem (e.g. "Sales~abc")
- * @param {string} outputDir - Directory where root output JSON lives
- * @param {string} serverTz - Server timezone
- * @param {string} [parentStem] - Ancestor stem for compound companion naming
- * @returns {Promise<string[]>} - Array of written companion file basenames
  */
-async function buildInlineOutputChildren(parentObj, node, rootStem, outputDir, serverTz, parentStem = rootStem) {
-  const companionFiles = [];
+export function buildInlineOutputChildren(parentObj, node) {
   const nodeChildren = node._children || {};
 
-  // Always create children object with all three doc keys
-  parentObj.children = { column: [], join: [], filter: [] };
+  // Use physical entity names as children keys (not doc aliases)
+  parentObj.children = { output_value: [], output_value_filter: [], output_value_entity_column_rel: [] };
 
   for (const docKey of INLINE_DOC_KEYS) {
     const entityArray = nodeChildren[docKey];
@@ -3602,44 +3727,32 @@ async function buildInlineOutputChildren(parentObj, node, rootStem, outputDir, s
 
     if (!Array.isArray(entityArray) || entityArray.length === 0) continue;
 
-    for (let childIdx = 0; childIdx < entityArray.length; childIdx++) {
-      const child = entityArray[childIdx];
+    for (const child of entityArray) {
       // Build a clean copy without tree-internal fields
       const childObj = { ...child };
       delete childObj._children;
 
-      // Decode any base64 values
+      // Decode all base64 fields inline (including CustomSQL — only root output extracts SQL files)
       for (const [key, value] of Object.entries(childObj)) {
-        if (key === 'CustomSQL') continue; // handled by extractCustomSqlIfNeeded
         if (value && typeof value === 'object' && !Array.isArray(value) && value.encoding === 'base64') {
-          childObj[key] = resolveContentValue(value);
+          childObj[key] = resolveContentValue(value) ?? '';
         }
       }
 
       // Ensure _entity is set to physical entity name (for push routing)
       childObj._entity = physicalKey;
 
-      // Compute companion stem for this child (index-based, not UID-based)
-      const childStem = getChildCompanionStem(rootStem, physicalKey, childIdx, parentStem);
-
-      // Extract CustomSQL if needed
-      const companionFile = await extractCustomSqlIfNeeded(childObj, childStem, outputDir, serverTz);
-      if (companionFile) companionFiles.push(companionFile);
-
       // Recurse into child's _children (e.g. join→column, column→filter)
       if (child._children && Object.keys(child._children).some(k => child._children[k]?.length > 0)) {
-        const gcFiles = await buildInlineOutputChildren(childObj, child, rootStem, outputDir, serverTz, childStem);
-        companionFiles.push(...gcFiles);
+        buildInlineOutputChildren(childObj, child);
       } else {
         // Leaf node: still set empty children
-        childObj.children = { column: [], join: [], filter: [] };
+        childObj.children = { output_value: [], output_value_filter: [], output_value_entity_column_rel: [] };
       }
 
-      parentObj.children[docKey].push(childObj);
+      parentObj.children[physicalKey].push(childObj);
     }
   }
-
-  return companionFiles;
 }
 
 /**
@@ -3661,8 +3774,8 @@ async function trashOrphanedChildFiles(outputDir, rootStem) {
   for (const f of files) {
     const matchesCurrent = f.startsWith(`${rootStem}.`);
     const matchesLegacy = f.startsWith(`${legacyStem}.`);
-    if ((matchesCurrent || matchesLegacy) && /\.(column|join|filter)~/.test(f)) {
-      // Old child file or legacy CustomSQL companion — trash it
+    if ((matchesCurrent || matchesLegacy) && /\.(column|join|filter)(~|-\d+\.|\.CustomSQL)/.test(f)) {
+      // Old child file, legacy child JSON, or old per-child CustomSQL companion — trash it
       if (!trashCreated) {
         await mkdir(trashDir, { recursive: true });
         trashCreated = true;
@@ -3814,6 +3927,26 @@ async function processOutputHierarchy(appJson, structure, options, serverTz) {
   // Resolve filename columns for each entity type
   const filenameCols = await resolveOutputFilenameColumns(appJson, options);
 
+  // Detect companion filename collisions: multiple outputs that produce the same
+  // rootBasename + binDir. When collisions exist, use UID-qualified companion stems
+  // so each output's .CustomSQL.sql doesn't overwrite the others.
+  const companionKey = (output) => {
+    let binDir = BINS_DIR;
+    if (output.BinID && structure[output.BinID]) {
+      binDir = resolveBinPath(output.BinID, structure);
+    }
+    const base = buildOutputFilename('output', output, filenameCols.output);
+    return `${binDir}/${base}`;
+  };
+  const companionKeyCounts = new Map();
+  for (const output of tree) {
+    const key = companionKey(output);
+    companionKeyCounts.set(key, (companionKeyCounts.get(key) || 0) + 1);
+  }
+  const collidingCompanionKeys = new Set(
+    [...companionKeyCounts.entries()].filter(([, count]) => count > 1).map(([key]) => key)
+  );
+
   const refs = [];
   const bulkAction = { value: null };
   const config = await loadConfig();
@@ -3924,11 +4057,16 @@ async function processOutputHierarchy(appJson, structure, options, serverTz) {
     // Copy raw CustomSQL for extraction helper
     rootMeta.CustomSQL = output.CustomSQL;
 
+    // When multiple outputs share the same name+bin, qualify the companion stem
+    // with the UID so each gets its own .CustomSQL.sql file.
+    const isCollision = collidingCompanionKeys.has(`${binDir}/${rootBasename}`);
+    const companionStem = isCollision ? `${rootBasename}~${rootUid}` : rootBasename;
+
     // Extract CustomSQL on root (rules 1/2/3)
-    await extractCustomSqlIfNeeded(rootMeta, rootBasename, binDir, serverTz);
+    await extractCustomSqlIfNeeded(rootMeta, companionStem, binDir, serverTz);
 
     // Embed all children under rootMeta.children = { column, join, filter }
-    await buildInlineOutputChildren(rootMeta, output, rootBasename, binDir, serverTz);
+    buildInlineOutputChildren(rootMeta, output);
     // rootMeta now has .children = { column: [...], join: [...], filter: [...] }
 
     await writeFile(rootMetaPath, JSON.stringify(rootMeta, null, 2) + '\n');
@@ -4030,11 +4168,11 @@ async function writeManifestJson(appJson, contentRefs) {
   };
 
   await writeFile('manifest.json', JSON.stringify(manifest, null, 2) + '\n');
-  log.dim('  manifest.json generated at project root (from app.json values)');
+  log.dim('  manifest.json generated at project root (from app metadata)');
 }
 
 /**
- * Save app.json to project root with @ references replacing processed entries.
+ * Save app metadata to project root with @ references replacing processed entries.
  */
 async function saveAppJson(appJson, contentRefs, otherRefs, domain) {
   const output = { ...appJson };
@@ -4072,11 +4210,12 @@ async function saveAppJson(appJson, contentRefs, otherRefs, domain) {
     delete output.children.output_value_entity_column_rel;
   }
 
-  await writeFile('app.json', JSON.stringify(output, null, 2) + '\n');
+  const metaPath = await appMetadataPath();
+  await writeFile(metaPath, JSON.stringify(output, null, 2) + '\n');
 }
 
 /**
- * Save .dbo/.app_baseline.json baseline file with decoded base64 values.
+ * Save .app/<shortName>.json baseline file with decoded base64 values.
  * This file tracks the server state for delta detection.
  */
 async function saveBaselineFile(appJson) {
@@ -4086,10 +4225,10 @@ async function saveBaselineFile(appJson) {
   // Recursively decode all base64 fields
   decodeBase64Fields(baseline);
 
-  // Save to .app.json
+  // Save baseline
   await saveAppJsonBaseline(baseline);
 
-  log.dim('  .dbo/.app_baseline.json baseline created (system-managed, do not edit)');
+  log.dim('  .app/ baseline created (system-managed, do not edit)');
 }
 
 /**
@@ -4125,10 +4264,10 @@ export function decodeBase64Fields(obj) {
 
 // ── Error log ─────────────────────────────────────────────────────────────
 
-const ERROR_LOG_PATH = join('.dbo', 'errors.log');
+const ERROR_LOG_PATH = join('.app', 'errors.log');
 
 /**
- * Append a structured error entry to .dbo/errors.log.
+ * Append a structured error entry to .app/errors.log.
  * Creates the file if absent. Each entry is one JSON line (JSONL format).
  */
 async function appendErrorLog(entry) {

package/src/commands/deploy.js

@@ -9,12 +9,12 @@ import { resolveTransactionKey } from '../lib/transaction-key.js';
 import { log } from '../lib/logger.js';
 import { runPendingMigrations } from '../lib/migrations.js';
 
-const MANIFEST_FILE = '.dbo/deploy_config.json';
+const MANIFEST_FILE = '.app/deploy_config.json';
 const LEGACY_MANIFEST_FILE = 'dbo.deploy.json';
 
 export const deployCommand = new Command('deploy')
   .description('Deploy files to DBO.io using a manifest or direct arguments')
-  .argument('[name]', 'Deployment name from .dbo/deploy_config.json (e.g., css:colors)')
+  .argument('[name]', 'Deployment name from .app/deploy_config.json (e.g., css:colors)')
   .option('--all', 'Deploy all entries in the manifest')
   .option('-C, --confirm <value>', 'Commit: true (default) or false', 'true')
   .option('--ticket <id>', 'Override ticket ID')
@@ -29,7 +29,7 @@ export const deployCommand = new Command('deploy')
       await runPendingMigrations(options);
       const client = new DboClient({ domain: options.domain, verbose: options.verbose });
 
-      // Load manifest — try .dbo/deploy_config.json first, fall back to legacy dbo.deploy.json
+      // Load manifest — try .app/deploy_config.json first, fall back to legacy dbo.deploy.json
       let manifest;
       let manifestSource;
       try {