@dboio/cli 0.15.3 → 0.17.0

package/src/{commands/add.js → lib/insert.js}

@@ -1,46 +1,22 @@
-import { Command } from 'commander';
-import { readFile, readdir, stat, writeFile, mkdir, unlink } from 'fs/promises';
+import { readFile, readdir, writeFile, mkdir, unlink } from 'fs/promises';
 import { join, dirname, basename, extname, relative } from 'path';
-import { DboClient } from '../lib/client.js';
-import { buildInputBody, checkSubmitErrors } from '../lib/input-parser.js';
-import { formatResponse, formatError } from '../lib/formatter.js';
-import { log } from '../lib/logger.js';
-import { shouldSkipColumn } from '../lib/columns.js';
-import { loadAppConfig, loadAppJsonBaseline, saveAppJsonBaseline, loadExtensionDocumentationMDPlacement, loadDescriptorFilenamePreference, loadConfig } from '../lib/config.js';
-import { resolveDirective, resolveTemplateCols, assembleMetadata, promptReferenceColumn, setTemplateCols, saveMetadataTemplates, loadMetadataTemplates } from '../lib/metadata-templates.js';
-import { hasUidInFilename, buildMetaFilename, isMetadataFile } from '../lib/filenames.js';
-import { setFileTimestamps } from '../lib/timestamps.js';
-import { checkStoredTicket, clearGlobalTicket } from '../lib/ticketing.js';
-import { checkModifyKey, isModifyKeyError, handleModifyKeyError } from '../lib/modify-key.js';
-import { loadIgnore } from '../lib/ignore.js';
-import { loadStructureFile, findBinByPath, BINS_DIR } from '../lib/structure.js';
-import { runPendingMigrations } from '../lib/migrations.js';
-import { upsertDeployEntry } from '../lib/deploy-config.js';
-
-// ─── File type classification for auto-detection in bin directories ────────
-
-/** Extensions treated as content entities (text-based, stored in content.Content) */
-const CONTENT_EXTENSIONS = new Set([
-  'sh', 'js', 'json', 'html', 'txt', 'xml', 'css', 'md',
-  'htm', 'svg', 'sql', 'csv', 'yaml', 'yml', 'ts', 'jsx', 'tsx',
-]);
-
-/** Extensions treated as media entities (binary files: images, audio, video) */
-const MEDIA_EXTENSIONS = new Set([
-  // Images
-  'png', 'jpg', 'jpeg', 'gif', 'webp', 'ico', 'bmp', 'tiff', 'tif', 'avif',
-  // Audio
-  'mp3', 'wav', 'ogg', 'aac', 'flac', 'm4a', 'wma',
-  // Video
-  'mp4', 'webm', 'mov', 'avi', 'mkv', 'wmv', 'flv',
-  // Fonts
-  'woff', 'woff2', 'ttf', 'otf', 'eot',
-  // Documents / archives (binary)
-  'pdf', 'zip', 'gz', 'tar',
-]);
+import { DboClient } from './client.js';
+import { buildInputBody, checkSubmitErrors } from './input-parser.js';
+import { formatResponse } from './formatter.js';
+import { log } from './logger.js';
+import { shouldSkipColumn } from './columns.js';
+import { loadAppConfig, loadAppJsonBaseline, saveAppJsonBaseline, loadExtensionDocumentationMDPlacement, loadDescriptorFilenamePreference, loadConfig } from './config.js';
+import { loadMetadataSchema, saveMetadataSchema } from './metadata-schema.js';
+import { hasUidInFilename, buildMetaFilename, isMetadataFile } from './filenames.js';
+import { setFileTimestamps } from './timestamps.js';
+import { checkStoredTicket, clearGlobalTicket } from './ticketing.js';
+import { checkModifyKey, isModifyKeyError, handleModifyKeyError } from './modify-key.js';
+import { loadIgnore } from './ignore.js';
+import { loadStructureFile, findBinByPath, BINS_DIR } from './structure.js';
+import { upsertDeployEntry } from './deploy-config.js';
 
 /** Simple MIME type lookup for common media extensions */
-const MIME_TYPES = {
+export const MIME_TYPES = {
   png: 'image/png', jpg: 'image/jpeg', jpeg: 'image/jpeg', gif: 'image/gif',
   webp: 'image/webp', ico: 'image/x-icon', bmp: 'image/bmp', svg: 'image/svg+xml',
   tiff: 'image/tiff', tif: 'image/tiff', avif: 'image/avif',
@@ -55,52 +31,66 @@ const MIME_TYPES = {
   tar: 'application/x-tar',
 };
 
-export const addCommand = new Command('add')
-  .description('Add a new file to DBO.io (creates record on server)')
-  .argument('<path>', 'File or "." to scan current directory')
-  .option('-C, --confirm <value>', 'Commit: true (default) or false', 'true')
-  .option('--ticket <id>', 'Override ticket ID')
-  .option('--modify-key <key>', 'Provide ModifyKey directly (skips interactive prompt)')
-  .option('--row-key <type>', 'Row key type (RowUID or RowID) — add uses RowID:add1 for new records regardless')
-  .option('-y, --yes', 'Auto-accept all prompts')
-  .option('--json', 'Output raw JSON')
-  .option('--jq <expr>', 'Filter JSON response')
-  .option('-v, --verbose', 'Show HTTP request details')
-  .option('--domain <host>', 'Override domain')
-  .option('--no-migrate', 'Skip pending migrations for this invocation')
-  .action(async (targetPath, options) => {
-    try {
-      await runPendingMigrations(options);
-      const client = new DboClient({ domain: options.domain, verbose: options.verbose });
-
-      // ModifyKey guard
-      const modifyKeyResult = await checkModifyKey(options);
-      if (modifyKeyResult.cancel) {
-        log.info('Submission cancelled');
-        return;
-      }
-      if (modifyKeyResult.modifyKey) options._resolvedModifyKey = modifyKeyResult.modifyKey;
-
-      if (targetPath === '.') {
-        await addDirectory(process.cwd(), client, options);
-      } else {
-        const pathStat = await stat(targetPath);
-        if (pathStat.isDirectory()) {
-          await addDirectory(targetPath, client, options);
-        } else {
-          await addSingleFile(targetPath, client, options);
-        }
-      }
-    } catch (err) {
-      formatError(err);
-      process.exit(1);
-    }
-  });
+/** Default template cols for core entity types */
+const TEMPLATE_DEFAULTS = {
+  content: [
+    'AppID', 'BinID', 'Name', 'Path', 'Content=@reference', 'Extension',
+    'Type', 'Title', 'Active', 'Public=0', 'SiteID', 'Description',
+    'Keywords', 'Parameters', 'CacheControl', 'RequireSSL', 'EntityID',
+  ],
+  media: [
+    'AppID', 'BinID', 'Name', 'Path', 'Filename', 'Extension',
+    'MimeType', 'FileSize', 'Ownership', 'Public', 'Description',
+    'Duration', 'ParentMediaID',
+  ],
+  output: [
+    'AppID', 'BinID', 'Name', 'Type', 'CustomSQL=@reference',
+    'Active', 'Public', 'Title', 'Description', 'Parameters',
+    'Cache', 'Limit', 'MaxRows', 'RowsPerPage', 'ApplyLocks',
+    'AdhocFilters', 'BaseEntityID', 'DataSourceID',
+    'DefaultMediaID', 'TemplateContentID', 'children',
+  ],
+  output_value: [
+    'OutputID', 'Title', 'ShortName', 'OutputType', 'OrderNumber',
+    'CustomSQL', 'Format', 'Aggregate', 'DatePart', 'Distinct',
+    'Hide', 'Shared', 'Summary', 'SortType', 'SortOrder',
+    'EnforceSecurity', 'ReferencedEntityColumnID',
+    'OutputValueEntityColumnRelID', 'children',
+  ],
+  output_value_filter: [
+    'OutputID', 'OutputValueID', 'ShortName', 'FilterType', 'Operator',
+    'OrderNumber', 'CustomSQL', 'Prompted', 'Required', 'Inclusive',
+    'PrimaryValue', 'SecondaryValue', 'FilterPreset',
+    'ApplyToAggregate', 'ValuesByOutputID', 'children',
+  ],
+  output_value_entity_column_rel: [
+    'OutputID', 'OutputValueID', 'JoinType', 'OrderNumber', 'CustomSQL',
+    'Alias', 'SourceJoinID', 'SourceEntityColumnID',
+    'ReferencedEntityColumnID', 'children',
+  ],
+};
 
 /**
- * Add a single file to DBO.io.
- * Returns the defaults used (entity, contentColumn) for batch reuse.
+ * Seed .dbo/metadata_schema.json with default fields for the given entity
+ * (and any other missing core entities) if an entry doesn't already exist.
  */
+export async function seedMetadataTemplate() {
+  const templates = await loadMetadataSchema() ?? {};
+
+  // Seed all missing core entities in one pass
+  const seeded = [];
+  for (const [name, cols] of Object.entries(TEMPLATE_DEFAULTS)) {
+    if (templates[name]) continue;
+    templates[name] = cols;
+    seeded.push(name);
+  }
+
+  if (seeded.length === 0) return;
+
+  await saveMetadataSchema(templates);
+  log.dim(`  Seeded metadata_schema.json with ${seeded.join(', ')} fields`);
+}
+
 /**
  * Detect whether a file lives in the project-root Documentation/ directory
  * AND the ExtensionDocumentationMDPlacement preference is 'root'.
@@ -108,7 +98,7 @@ export const addCommand = new Command('add')
  *
  * @param {string} filePath - Path to the file being added
  */
-async function detectDocumentationFile(filePath) {
+export async function detectDocumentationFile(filePath) {
   const placement = await loadExtensionDocumentationMDPlacement();
   if (placement !== 'root') return null;
 
@@ -124,7 +114,7 @@ async function detectDocumentationFile(filePath) {
  *
  * Creates companion metadata in bins/app/ with pre-filled fields.
  */
-async function detectManifestFile(filePath) {
+export async function detectManifestFile(filePath) {
   const rel = relative(process.cwd(), filePath).replace(/\\/g, '/');
   if (rel.toLowerCase() !== 'manifest.json') return null;
 
@@ -137,7 +127,7 @@ async function detectManifestFile(filePath) {
 
   const meta = {
     _entity: 'content',
-    _contentColumns: ['Content'],
+    _companionReferenceColumns: ['Content'],
     Content: '@/manifest.json',
     Path: 'manifest.json',
     Name: 'manifest.json',
@@ -174,6 +164,26 @@ export async function detectBinFile(filePath) {
   const ext = extname(filePath).replace('.', '').toLowerCase();
   if (!ext) return null;
 
+  // Extensions treated as content entities (text-based, stored in content.Content)
+  const CONTENT_EXTENSIONS = new Set([
+    'sh', 'js', 'json', 'html', 'txt', 'xml', 'css', 'md',
+    'htm', 'svg', 'sql', 'csv', 'yaml', 'yml', 'ts', 'jsx', 'tsx',
+  ]);
+
+  // Extensions treated as media entities (binary files: images, audio, video)
+  const MEDIA_EXTENSIONS = new Set([
+    // Images
+    'png', 'jpg', 'jpeg', 'gif', 'webp', 'ico', 'bmp', 'tiff', 'tif', 'avif',
+    // Audio
+    'mp3', 'wav', 'ogg', 'aac', 'flac', 'm4a', 'wma',
+    // Video
+    'mp4', 'webm', 'mov', 'avi', 'mkv', 'wmv', 'flv',
+    // Fonts
+    'woff', 'woff2', 'ttf', 'otf', 'eot',
+    // Documents / archives (binary)
+    'pdf', 'zip', 'gz', 'tar',
+  ]);
+
   const isContent = CONTENT_EXTENSIONS.has(ext);
   const isMedia = MEDIA_EXTENSIONS.has(ext);
   if (!isContent && !isMedia) return null;
@@ -202,7 +212,7 @@ export async function detectBinFile(filePath) {
 
     const meta = {
       _entity: 'content',
-      _contentColumns: ['Content'],
+      _companionReferenceColumns: ['Content'],
       Name: base,
       Content: `@${fileName}`,
       Extension: ext.toUpperCase(),
@@ -216,7 +226,7 @@ export async function detectBinFile(filePath) {
     await writeFile(metaPath, JSON.stringify(meta, null, 2) + '\n');
     log.success(`Auto-created content metadata for "${fileName}"`);
 
-    // Seed metadata_templates.json with content fields if missing
+    // Seed metadata_schema.json with content fields if missing
     await seedMetadataTemplate();
 
     return { meta, metaPath };
@@ -250,326 +260,18 @@ export async function detectBinFile(filePath) {
   await writeFile(metaPath, JSON.stringify(meta, null, 2) + '\n');
   log.success(`Auto-created media metadata for "${fileName}"`);
 
-  // Seed metadata_templates.json with media fields if missing
+  // Seed metadata_schema.json with media fields if missing
   await seedMetadataTemplate();
 
   return { meta, metaPath };
 }
 
-/** Default template cols for core entity types */
-const TEMPLATE_DEFAULTS = {
-  content: [
-    'AppID', 'BinID', 'Name', 'Path', 'Content=@reference', 'Extension',
-    'Type', 'Title', 'Active', 'Public=0', 'SiteID', 'Description',
-    'Keywords', 'Parameters', 'CacheControl', 'RequireSSL', 'EntityID',
-  ],
-  media: [
-    'AppID', 'BinID', 'Name', 'Path', 'Filename', 'Extension',
-    'MimeType', 'FileSize', 'Ownership', 'Public', 'Description',
-    'Duration', 'ParentMediaID',
-  ],
-  output: [
-    'AppID', 'BinID', 'Name', 'Type', 'CustomSQL=@reference',
-    'Active', 'Public', 'Title', 'Description', 'Parameters',
-    'Cache', 'Limit', 'MaxRows', 'RowsPerPage', 'ApplyLocks',
-    'AdhocFilters', 'BaseEntityID', 'DataSourceID',
-    'DefaultMediaID', 'TemplateContentID', 'children',
-  ],
-  output_value: [
-    'OutputID', 'Title', 'ShortName', 'OutputType', 'OrderNumber',
-    'CustomSQL', 'Format', 'Aggregate', 'DatePart', 'Distinct',
-    'Hide', 'Shared', 'Summary', 'SortType', 'SortOrder',
-    'EnforceSecurity', 'ReferencedEntityColumnID',
-    'OutputValueEntityColumnRelID', 'children',
-  ],
-  output_value_filter: [
-    'OutputID', 'OutputValueID', 'ShortName', 'FilterType', 'Operator',
-    'OrderNumber', 'CustomSQL', 'Prompted', 'Required', 'Inclusive',
-    'PrimaryValue', 'SecondaryValue', 'FilterPreset',
-    'ApplyToAggregate', 'ValuesByOutputID', 'children',
-  ],
-  output_value_entity_column_rel: [
-    'OutputID', 'OutputValueID', 'JoinType', 'OrderNumber', 'CustomSQL',
-    'Alias', 'SourceJoinID', 'SourceEntityColumnID',
-    'ReferencedEntityColumnID', 'children',
-  ],
-};
-
-/**
- * Seed .dbo/metadata_templates.json with default fields for the given entity
- * (and any other missing core entities) if an entry doesn't already exist.
- */
-async function seedMetadataTemplate() {
-  const templates = await loadMetadataTemplates() ?? {};
-
-  // Seed all missing core entities in one pass
-  const seeded = [];
-  for (const [name, cols] of Object.entries(TEMPLATE_DEFAULTS)) {
-    if (templates[name]) continue;
-    templates[name] = cols;
-    seeded.push(name);
-  }
-
-  if (seeded.length === 0) return;
-
-  await saveMetadataTemplates(templates);
-  log.dim(`  Seeded metadata_templates.json with ${seeded.join(', ')} fields`);
-}
-
-async function addSingleFile(filePath, client, options, batchDefaults) {
-  // Check .dboignore before doing any processing
-  const ig = await loadIgnore();
-  const relPath = relative(process.cwd(), filePath).replace(/\\/g, '/');
-  if (ig.ignores(relPath)) {
-    log.dim(`Skipped (dboignored): ${relPath}`);
-    return null;
-  }
-
-  const dir = dirname(filePath);
-  const ext = extname(filePath);
-  const base = basename(filePath, ext);
-  const fileName = basename(filePath);
-  const metaPath = join(dir, `${base}.metadata.json`);
-
-  // Step 1: Check for existing metadata
-  let meta = null;
-  try {
-    const raw = await readFile(metaPath, 'utf8');
-    if (raw.trim()) {
-      meta = JSON.parse(raw);
-    }
-  } catch {
-    // No metadata file — that's fine, we'll create one
-  }
-
-  // Step 2: If metadata exists with _CreatedOn, already on server
-  if (meta && meta._CreatedOn) {
-    log.warn(`"${fileName}" is already on the server (has _CreatedOn). Use "dbo push" to update.`);
-    return null;
-  }
-
-  // Step 3: If metadata exists without _CreatedOn, use it for insert
-  if (meta && meta._entity) {
-    log.info(`Found metadata for "${fileName}" — proceeding with insert`);
-    return await submitAdd(meta, metaPath, filePath, client, options);
-  }
-
-  // Step 3b: Directive / template path
-  const directive = resolveDirective(filePath);
-  if (directive) {
-    const { entity, descriptor } = directive;
-    const appConfig = await loadAppConfig();
-    const appJson = await loadAppJsonBaseline().catch(() => null);
-    const resolved = await resolveTemplateCols(entity, descriptor, appConfig, appJson);
-
-    if (resolved !== null) {
-      let { cols, templates } = resolved;
-
-      // Check if @reference col is known
-      const hasRefMarker = cols.some(c => c.includes('=@reference'));
-      if (!hasRefMarker) {
-        if (options.yes) {
-          console.warn(`Warning: No @reference column in template for ${entity}${descriptor ? '.' + descriptor : ''} — skipping content column. Update .dbo/metadata_templates.json to add Key=@reference.`);
-        } else {
-          const chosen = await promptReferenceColumn(cols, entity, descriptor);
-          if (chosen) {
-            cols = cols.map(c => c === chosen ? `${chosen}=@reference` : c);
-            templates = templates ?? await loadMetadataTemplates() ?? {};
-            setTemplateCols(templates, entity, descriptor, cols);
-            await saveMetadataTemplates(templates);
-          }
-        }
-      }
-
-      const { meta } = assembleMetadata(cols, filePath, entity, descriptor, appConfig);
-
-      // Determine metadata path
-      let templateMetaPath;
-      const rel = relative(process.cwd(), filePath).replace(/\\/g, '/');
-      if (rel.startsWith('docs/')) {
-        // docs/ files: companion metadata goes to extension/documentation/
-        const docDir = join(process.cwd(), 'extension', 'documentation');
-        await mkdir(docDir, { recursive: true });
-        templateMetaPath = join(docDir, `${basename(filePath, extname(filePath))}.metadata.json`);
-      } else {
-        templateMetaPath = join(dirname(filePath), `${basename(filePath, extname(filePath))}.metadata.json`);
-      }
-
-      await writeFile(templateMetaPath, JSON.stringify(meta, null, 2) + '\n');
-      return await submitAdd(meta, templateMetaPath, filePath, client, options);
-    }
-  }
-
-  // Step 3c: Auto-infer entity/descriptor for Documentation/ files when root placement is configured
-  const docInfo = await detectDocumentationFile(filePath);
-  if (docInfo) {
-    const filenameCol = await loadDescriptorFilenamePreference('documentation') || 'Name';
-    const docBase = basename(filePath, extname(filePath));
-    const companionDir = join(process.cwd(), 'extension', 'documentation');
-    await mkdir(companionDir, { recursive: true });
-
-    const docMeta = {
-      _entity: 'extension',
-      Descriptor: 'documentation',
-      [filenameCol]: docBase,
-      Name: docBase,
-    };
-
-    // Find the content column name from saved preferences
-    const contentCol = filenameCol === 'Name' ? 'String10' : 'String10';
-    const relPath = relative(process.cwd(), filePath).replace(/\\/g, '/');
-    docMeta[contentCol] = `@/${relPath}`;
-    docMeta._contentColumns = [contentCol];
-
-    const docMetaFile = join(companionDir, `${docBase}.metadata.json`);
-    await writeFile(docMetaFile, JSON.stringify(docMeta, null, 2) + '\n');
-    log.success(`Created companion metadata at ${docMetaFile}`);
-    return await submitAdd(docMeta, docMetaFile, filePath, client, options);
-  }
-
-  // Step 3d: Auto-detect manifest.json at project root
-  const manifestMeta = await detectManifestFile(filePath);
-  if (manifestMeta) {
-    return await submitAdd(manifestMeta.meta, manifestMeta.metaPath, filePath, client, options);
-  }
-
-  // Step 3e: Auto-detect content/media files in bin directories (lib/bins/)
-  const binMeta = await detectBinFile(filePath);
-  if (binMeta) {
-    return await submitAdd(binMeta.meta, binMeta.metaPath, filePath, client, options);
-  }
-
-  // Step 4: No usable metadata — interactive wizard
-  const inquirer = (await import('inquirer')).default;
-
-  log.plain('');
-  log.warn(`I cannot add "${fileName}" to the server, because I don't have any metadata.`);
-  log.plain(`I have a few things that I need, and I can set that up for you,`);
-  log.plain(`or you manually add "${base}.metadata.json" next to the file.`);
-  log.plain('');
-
-  if (!options.yes) {
-    const { proceed } = await inquirer.prompt([{
-      type: 'confirm',
-      name: 'proceed',
-      message: 'Want me to set that up for you?',
-      default: true,
-    }]);
-
-    if (!proceed) {
-      log.dim(`Skipping "${fileName}". Create "${base}.metadata.json" manually and try again.`);
-      return null;
-    }
-  }
-
-  // Prompt for required fields (reuse batch defaults if available)
-  // Check if config has AppID for smart default
-  const appConfig = await loadAppConfig();
-
-  const answers = await inquirer.prompt([
-    {
-      type: 'input',
-      name: 'entity',
-      message: 'Entity name (e.g. content, template, style):',
-      default: batchDefaults?.entity || 'content',
-      validate: v => v.trim() ? true : 'Entity is required',
-    },
-    {
-      type: 'input',
-      name: 'contentColumn',
-      message: 'Column name for the file content (e.g. Content, Body, Template):',
-      default: batchDefaults?.contentColumn || 'Content',
-      validate: v => v.trim() ? true : 'Column name is required',
-    },
-    {
-      type: 'input',
-      name: 'BinID',
-      message: 'BinID (optional, press Enter to skip):',
-      default: batchDefaults?.BinID || '',
-    },
-    {
-      type: 'input',
-      name: 'SiteID',
-      message: 'SiteID (optional, press Enter to skip):',
-      default: batchDefaults?.SiteID || '',
-    },
-    {
-      type: 'input',
-      name: 'Path',
-      message: 'Path (optional, press Enter for auto-generated):',
-      default: batchDefaults?.Path || relative(process.cwd(), filePath).replace(/\\/g, '/'),
-    },
-  ]);
-
-  // AppID: smart prompt when config has app info
-  if (batchDefaults?.AppID) {
-    answers.AppID = batchDefaults.AppID;
-  } else if (appConfig.AppID) {
-    const { appIdChoice } = await inquirer.prompt([{
-      type: 'list',
-      name: 'appIdChoice',
-      message: `You're submitting data without an AppID, but your config has information about the current App. Do you want me to add that Column information along with your submission?`,
-      choices: [
-        { name: `Yes, use AppID ${appConfig.AppID}`, value: 'use_config' },
-        { name: 'No', value: 'none' },
-        { name: 'Enter custom AppID', value: 'custom' },
-      ],
-    }]);
-    if (appIdChoice === 'use_config') {
-      answers.AppID = String(appConfig.AppID);
-    } else if (appIdChoice === 'custom') {
-      const { customAppId } = await inquirer.prompt([{
-        type: 'input', name: 'customAppId',
-        message: 'Custom AppID:',
-      }]);
-      answers.AppID = customAppId;
-    } else {
-      answers.AppID = '';
-    }
-  } else {
-    const { appId } = await inquirer.prompt([{
-      type: 'input', name: 'appId',
-      message: 'AppID (optional, press Enter to skip):',
-      default: '',
-    }]);
-    answers.AppID = appId;
-  }
-
-  // Build metadata object
-  meta = {};
-  if (answers.AppID.trim()) meta.AppID = isFinite(answers.AppID) ? Number(answers.AppID) : answers.AppID;
-  if (answers.BinID.trim()) meta.BinID = isFinite(answers.BinID) ? Number(answers.BinID) : answers.BinID;
-  if (answers.SiteID.trim()) meta.SiteID = isFinite(answers.SiteID) ? Number(answers.SiteID) : answers.SiteID;
-  meta.Name = base;
-  if (answers.Path.trim()) meta.Path = answers.Path.trim();
-  meta[answers.contentColumn.trim()] = `@${fileName}`;
-  meta._entity = answers.entity.trim();
-  meta._contentColumns = [answers.contentColumn.trim()];
-
-  // Write metadata file
-  await writeFile(metaPath, JSON.stringify(meta, null, 2) + '\n');
-  log.success(`Created ${basename(metaPath)}`);
-
-  // Submit the insert
-  const defaults = {
-    entity: answers.entity.trim(),
-    contentColumn: answers.contentColumn.trim(),
-    AppID: answers.AppID,
-    BinID: answers.BinID,
-    SiteID: answers.SiteID,
-    Path: answers.Path,
-  };
-
-  await submitAdd(meta, metaPath, filePath, client, options);
-  return defaults;
-}
-
 /**
  * Submit an insert to the server from a metadata object.
  */
 export async function submitAdd(meta, metaPath, filePath, client, options) {
   const entity = meta._entity;
-  const contentCols = new Set(meta._contentColumns || []);
+  const contentCols = new Set(meta._companionReferenceColumns || meta._contentColumns || []);
   const metaDir = dirname(metaPath);
 
   if (!entity) {
@@ -691,7 +393,7 @@ export async function submitAdd(meta, metaPath, filePath, client, options) {
         if (serverTz && returnedLastUpdated) {
           try {
             await setFileTimestamps(newMetaPath, returnedLastUpdated, returnedLastUpdated, serverTz);
-            for (const col of (meta._contentColumns || [])) {
+            for (const col of (meta._companionReferenceColumns || meta._contentColumns || [])) {
               const ref = meta[col];
               if (ref && String(ref).startsWith('@')) {
                 const fp = join(metaDir, String(ref).substring(1));
@@ -716,7 +418,7 @@ export async function submitAdd(meta, metaPath, filePath, client, options) {
   return { entity: meta._entity };
 }
 
-async function updateBaselineWithNewRecord(meta, uid, lastUpdated) {
+export async function updateBaselineWithNewRecord(meta, uid, lastUpdated) {
   try {
     const baseline = await loadAppJsonBaseline();
     if (!baseline) return;
@@ -741,68 +443,30 @@ async function updateBaselineWithNewRecord(meta, uid, lastUpdated) {
 }
 
 /**
- * Scan a directory for un-added files and add them.
+ * Collect all @ companion file references from a metadata object,
+ * including references nested inside children (inline output hierarchy).
  */
-async function addDirectory(dirPath, client, options) {
-  const unadded = await findUnaddedFiles(dirPath);
-
-  if (unadded.length === 0) {
-    log.info('No un-added files found.');
-    return;
-  }
-
-  log.info(`Found ${unadded.length} file(s) to add:`);
-  for (const f of unadded) {
-    log.plain(`  ${relative(process.cwd(), f)}`);
-  }
-  log.plain('');
-
-  if (!options.yes) {
-    const inquirer = (await import('inquirer')).default;
-    const { proceed } = await inquirer.prompt([{
-      type: 'confirm',
-      name: 'proceed',
-      message: `Add ${unadded.length} file(s)?`,
-      default: true,
-    }]);
-    if (!proceed) return;
-  }
-
-  // Pre-flight ticket validation
-  if (!options.ticket) {
-    const ticketCheck = await checkStoredTicket(options);
-    if (ticketCheck.cancel) {
-      log.info('Submission cancelled');
-      return;
-    }
-    if (ticketCheck.clearTicket) {
-      await clearGlobalTicket();
-      log.dim('  Cleared stored ticket');
+function collectCompanionRefs(meta, refs) {
+  for (const col of (meta._companionReferenceColumns || meta._contentColumns || [])) {
+    const val = meta[col];
+    if (typeof val === 'string' && val.startsWith('@') && !val.startsWith('@/')) {
+      refs.add(val.substring(1));
     }
   }
-
-  let succeeded = 0;
-  let failed = 0;
-  let batchDefaults = null;
-
-  for (const filePath of unadded) {
-    try {
-      const result = await addSingleFile(filePath, client, options, batchDefaults);
-      if (result) {
-        batchDefaults = result;
-        succeeded++;
-      }
-    } catch (err) {
-      if (err.message === 'SKIP_ALL') {
-        log.info('Skipping remaining records');
-        break;
+  if (meta._mediaFile && typeof meta._mediaFile === 'string' && meta._mediaFile.startsWith('@')) {
+    refs.add(meta._mediaFile.substring(1));
+  }
+  // Recurse into inline output children (column, join, filter arrays)
+  if (meta.children && typeof meta.children === 'object' && !Array.isArray(meta.children)) {
+    for (const arr of Object.values(meta.children)) {
+      if (!Array.isArray(arr)) continue;
+      for (const child of arr) {
+        if (child && typeof child === 'object') {
+          collectCompanionRefs(child, refs);
+        }
       }
-      log.error(`Failed: ${relative(process.cwd(), filePath)} — ${err.message}`);
-      failed++;
     }
   }
-
-  log.info(`Add complete: ${succeeded} succeeded, ${failed} failed`);
 }
 
 /**
@@ -835,15 +499,7 @@ export async function findUnaddedFiles(dir, ig, referencedFiles) {
       const meta = JSON.parse(raw);
       // Only count records that are on the server (have UID or _CreatedOn)
       if (!meta.UID && !meta._CreatedOn) continue;
-      for (const col of (meta._contentColumns || [])) {
-        const val = meta[col];
-        if (typeof val === 'string' && val.startsWith('@') && !val.startsWith('@/')) {
-          localRefs.add(val.substring(1));
-        }
-      }
-      if (meta._mediaFile && typeof meta._mediaFile === 'string' && meta._mediaFile.startsWith('@')) {
-        localRefs.add(meta._mediaFile.substring(1));
-      }
+      collectCompanionRefs(meta, localRefs);
     } catch { /* skip unreadable */ }
   }
 
@@ -912,19 +568,18 @@ async function _scanMetadataRefs(dir, referenced) {
       const meta = JSON.parse(raw);
       if (!meta._CreatedOn && !meta.UID) continue; // only count server-confirmed records
 
-      for (const col of (meta._contentColumns || [])) {
-        const val = meta[col];
-        if (typeof val === 'string' && val.startsWith('@')) {
-          const ref = val.substring(1);
-          if (ref.startsWith('/')) {
-            // @/path — absolute from project root
-            referenced.add(ref.substring(1));
-          } else {
-            // @filename — relative to metadata file's directory
-            const metaDir = relative(process.cwd(), dir).replace(/\\/g, '/');
-            const resolved = metaDir ? `${metaDir}/${ref}` : ref;
-            referenced.add(resolved);
-          }
+      // Collect all @ references (including from inline output children)
+      const allRefs = new Set();
+      collectCompanionRefs(meta, allRefs);
+      for (const refName of allRefs) {
+        if (refName.startsWith('/')) {
+          // @/path — absolute from project root
+          referenced.add(refName.substring(1));
+        } else {
+          // @filename — relative to metadata file's directory
+          const metaDir = relative(process.cwd(), dir).replace(/\\/g, '/');
+          const resolved = metaDir ? `${metaDir}/${refName}` : refName;
+          referenced.add(resolved);
         }
       }