@dboio/cli 0.16.2 → 0.17.0

package/src/commands/adopt.js

@@ -0,0 +1,534 @@
+import { Command } from 'commander';
+import { readFile, writeFile, stat, mkdir } from 'fs/promises';
+import { join, dirname, basename, extname, relative } from 'path';
+import { log } from '../lib/logger.js';
+import { loadIgnore } from '../lib/ignore.js';
+import { loadAppConfig, loadAppJsonBaseline, loadExtensionDocumentationMDPlacement, loadDescriptorFilenamePreference } from '../lib/config.js';
+import {
+  resolveDirective, resolveTemplateCols, assembleMetadata,
+  promptReferenceColumn, getTemplateCols, setTemplateCols,
+  loadMetadataSchema, saveMetadataSchema,
+} from '../lib/metadata-schema.js';
+import { loadStructureFile, findBinByPath, BINS_DIR } from '../lib/structure.js';
+import { isMetadataFile } from '../lib/filenames.js';
+import { findUnaddedFiles, MIME_TYPES, seedMetadataTemplate, detectDocumentationFile, detectManifestFile } from '../lib/insert.js';
+import { runPendingMigrations } from '../lib/migrations.js';
+
+export const adoptCommand = new Command('adopt')
+  .description('Create metadata companion for a file or directory (local only — use dbo push to insert)')
+  .argument('<path>', 'File path, directory path, or "." for current directory')
+  .option('-e, --entity <spec>', 'Entity and optional column: e.g. content, media, extension.widget, extension.String5')
+  .option('--into <metaPath>', 'Attach file to an existing metadata record as an additional companion column (single-file only)')
+  .option('-y, --yes', 'Skip all confirmation prompts and use defaults')
+  .option('-v, --verbose', 'Show verbose output')
+  .option('--domain <host>', 'Override domain')
+  .option('--no-migrate', 'Skip pending migrations for this invocation')
+  .action(async (targetPath, options) => {
+    try {
+      await runPendingMigrations(options);
+
+      // --into is single-file only
+      if (options.into) {
+        if (targetPath === '.' || (await stat(targetPath)).isDirectory()) {
+          log.error('--into is not supported in directory mode');
+          process.exit(1);
+        }
+        await adoptIntoRecord(targetPath, options.into, options.entity, options);
+        return;
+      }
+
+      const pathStat = await stat(targetPath).catch(() => null);
+      if (!pathStat) {
+        log.error(`Path not found: ${targetPath}`);
+        process.exit(1);
+      }
+
+      if (pathStat.isDirectory()) {
+        await adoptDirectory(targetPath, options.entity, options);
+      } else {
+        await adoptSingleFile(targetPath, options.entity, options);
+      }
+    } catch (err) {
+      log.error(err.message);
+      process.exit(1);
+    }
+  });
+
+/**
+ * Disambiguate extension.widget (descriptor) from extension.String5 (column).
+ */
+function parseEntitySpec(spec, metadataSchema) {
+  if (!spec) return null;
+  const dotIdx = spec.indexOf('.');
+  if (dotIdx === -1) return { entity: spec, descriptor: null, column: null };
+
+  const entity = spec.slice(0, dotIdx);
+  const sub = spec.slice(dotIdx + 1);
+
+  if (entity === 'extension') {
+    // Check if `sub` is a known descriptor in metadata_schema.json
+    const extSchema = metadataSchema?.extension;
+    if (extSchema && typeof extSchema === 'object' && !Array.isArray(extSchema) && extSchema[sub] !== undefined) {
+      return { entity: 'extension', descriptor: sub, column: null };
+    }
+    // Otherwise treat as column name
+    return { entity: 'extension', descriptor: null, column: sub };
+  }
+
+  // e.g. "content.Content" — treat sub as explicit column
+  return { entity, descriptor: null, column: sub };
+}
+
+/**
+ * Build entity-specific metadata for a file in or outside lib/bins/.
+ */
+async function buildBinMetadata(filePath, entity, appConfig, structure) {
+  const rel = relative(process.cwd(), filePath).replace(/\\/g, '/');
+  const ext = extname(filePath).replace('.', '').toLowerCase();
+  const fileName = basename(filePath);
+  const base = basename(filePath, extname(filePath));
+  const fileDir = dirname(rel);
+  const bin = findBinByPath(fileDir, structure);
+  const binPath = bin?.path || '';
+
+  const metaPath = join(dirname(filePath), `${base}.metadata.json`);
+
+  if (entity === 'content') {
+    const contentPath = binPath
+      ? `${binPath}/${base}.${ext}`
+      : `${base}.${ext}`;
+    const meta = {
+      _entity: 'content',
+      _companionReferenceColumns: ['Content'],
+      Name: base,
+      Content: `@${fileName}`,
+      Extension: ext.toUpperCase(),
+      Path: contentPath,
+      Active: 1,
+      Public: 0,
+    };
+    if (bin) meta.BinID = bin.binId;
+    if (appConfig.AppID) meta.AppID = appConfig.AppID;
+    return { meta, metaPath };
+  }
+
+  if (entity === 'media') {
+    const meta = {
+      _entity: 'media',
+      _mediaFile: `@${fileName}`,
+      Name: base,
+      Filename: fileName,
+      Extension: ext,
+      Ownership: 'App',
+    };
+    if (bin) meta.BinID = bin.binId;
+    if (appConfig.AppID) meta.AppID = appConfig.AppID;
+    if (binPath) meta.Path = binPath;
+    const mimeType = MIME_TYPES[ext];
+    if (mimeType) meta.MimeType = mimeType;
+    if (appConfig.AppShortName) {
+      const parts = ['', 'media', appConfig.AppShortName, 'app'];
+      if (binPath) parts.push(binPath);
+      parts.push(fileName);
+      meta.FullPath = parts.join('/');
+    }
+    return { meta, metaPath };
+  }
+
+  return null; // unsupported entity for bin metadata
+}
+
+/**
+ * Adopt a single file — create a *.metadata.json companion (local only, no server call).
+ */
+async function adoptSingleFile(filePath, entityArg, options) {
+  const ig = await loadIgnore();
+  const relPath = relative(process.cwd(), filePath).replace(/\\/g, '/');
+  if (ig.ignores(relPath)) {
+    log.dim(`Skipped (dboignored): ${relPath}`);
+    return;
+  }
+
+  const dir = dirname(filePath);
+  const ext = extname(filePath);
+  const base = basename(filePath, ext);
+  const fileName = basename(filePath);
+
+  // Check for existing metadata
+  const metaPath = join(dir, `${base}.metadata.json`);
+  let existingMeta = null;
+  try {
+    existingMeta = JSON.parse(await readFile(metaPath, 'utf8'));
+  } catch { /* no file — that's fine */ }
+
+  if (existingMeta) {
+    if (existingMeta.UID || existingMeta._CreatedOn) {
+      log.warn(`"${fileName}" is already on the server (has UID/_CreatedOn) — skipping.`);
+      return;
+    }
+    // Metadata exists but no server record
+    if (!options.yes) {
+      const inquirer = (await import('inquirer')).default;
+      const { overwrite } = await inquirer.prompt([{
+        type: 'confirm',
+        name: 'overwrite',
+        message: `Metadata already exists for "${fileName}" (no UID). Overwrite?`,
+        default: false,
+      }]);
+      if (!overwrite) return;
+    }
+  }
+
+  const metadataSchema = await loadMetadataSchema() ?? {};
+
+  // --- Resolve entity from -e flag or directory inference ---
+  let entity, descriptor, column;
+  if (entityArg) {
+    const parsed = parseEntitySpec(entityArg, metadataSchema);
+    entity = parsed.entity;
+    descriptor = parsed.descriptor;
+    column = parsed.column;
+  } else {
+    // No -e: infer via resolveDirective
+    const directive = resolveDirective(filePath);
+    if (directive) {
+      entity = directive.entity;
+      descriptor = directive.descriptor;
+    } else {
+      // Fall back to interactive wizard
+      log.warn(`Cannot infer entity for "${fileName}". Use -e <entity> to specify.`);
+      await runInteractiveWizard(filePath, options);
+      return;
+    }
+  }
+
+  const appConfig = await loadAppConfig();
+
+  // --- Special case: manifest.json ---
+  const rel = relative(process.cwd(), filePath).replace(/\\/g, '/');
+  if (rel.toLowerCase() === 'manifest.json') {
+    const manifestResult = await detectManifestFile(filePath);
+    if (manifestResult) {
+      log.success(`Created manifest metadata at ${manifestResult.metaPath}`);
+      return;
+    }
+  }
+
+  // --- content or media entities: build entity-specific metadata ---
+  if ((entity === 'content' || entity === 'media') && !column) {
+    const structure = await loadStructureFile();
+    const result = await buildBinMetadata(filePath, entity, appConfig, structure);
+    if (result) {
+      await writeFile(result.metaPath, JSON.stringify(result.meta, null, 2) + '\n');
+      log.success(`Created ${entity} metadata: ${basename(result.metaPath)}`);
+      await seedMetadataTemplate();
+      return;
+    }
+  }
+
+  // --- docs/ files with documentation directive ---
+  if (entity === 'extension' && descriptor === 'documentation') {
+    const docBase = base;
+    const companionDir = join(process.cwd(), 'lib', 'extension', 'documentation');
+    await mkdir(companionDir, { recursive: true });
+    const docMetaPath = join(companionDir, `${docBase}.metadata.json`);
+
+    const docMeta = {
+      _entity: 'extension',
+      Descriptor: 'documentation',
+      Name: docBase,
+    };
+    const contentCol = 'String10';
+    docMeta[contentCol] = `@/${relPath}`;
+    docMeta._companionReferenceColumns = [contentCol];
+
+    await writeFile(docMetaPath, JSON.stringify(docMeta, null, 2) + '\n');
+    log.success(`Created documentation metadata: ${basename(docMetaPath)}`);
+    return;
+  }
+
+  // --- General path: use resolveTemplateCols + assembleMetadata ---
+  const appJson = await (async () => { try { return await loadAppJsonBaseline(); } catch { return null; } })();
+  const resolved = await resolveTemplateCols(entity, descriptor, appConfig, appJson);
+
+  if (resolved === null) {
+    // Malformed metadata_schema.json — fall through to wizard
+    await runInteractiveWizard(filePath, options);
+    return;
+  }
+
+  let { cols, templates } = resolved;
+
+  // If an explicit column was provided, inject it as @reference
+  if (column) {
+    const hasCol = cols.some(c => c.startsWith(column + '=') || c === column);
+    if (hasCol) {
+      cols = cols.map(c => (c === column || c.startsWith(column + '=')) ? `${column}=@reference` : c);
+    } else {
+      cols.push(`${column}=@reference`);
+    }
+  } else {
+    // Ensure @reference marker exists
+    const hasRefMarker = cols.some(c => c.includes('=@reference'));
+    if (!hasRefMarker) {
+      if (options.yes) {
+        log.warn(`No @reference column in template for ${entity}${descriptor ? '.' + descriptor : ''} — skipping content column.`);
+      } else {
+        const chosen = await promptReferenceColumn(cols, entity, descriptor);
+        if (chosen) {
+          cols = cols.map(c => c === chosen ? `${chosen}=@reference` : c);
+          templates = templates ?? metadataSchema;
+          setTemplateCols(templates, entity, descriptor, cols);
+          await saveMetadataSchema(templates);
+        }
+      }
+    }
+  }
+
+  const { meta } = assembleMetadata(cols, filePath, entity, descriptor, appConfig);
+  const finalMetaPath = join(dirname(filePath), `${base}.metadata.json`);
+
+  await writeFile(finalMetaPath, JSON.stringify(meta, null, 2) + '\n');
+  log.success(`Created metadata: ${basename(finalMetaPath)}`);
+  log.dim(`  Run "dbo push" to insert this record on the server.`);
+}
+
+/**
+ * Interactive wizard fallback — creates metadata by prompting the user.
+ * Does NOT submit to server (local-only).
+ */
+async function runInteractiveWizard(filePath, options) {
+  const inquirer = (await import('inquirer')).default;
+  const fileName = basename(filePath);
+  const base = basename(filePath, extname(filePath));
+  const metaPath = join(dirname(filePath), `${base}.metadata.json`);
+
+  log.plain('');
+  log.warn(`I cannot adopt "${fileName}" because I don't have enough metadata.`);
+  log.plain(`I have a few things that I need, and I can set that up for you,`);
+  log.plain(`or you can manually create "${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;
+    }
+  }
+
+  const appConfig = await loadAppConfig();
+
+  const answers = await inquirer.prompt([
+    {
+      type: 'input',
+      name: 'entity',
+      message: 'Entity name (e.g. content, template, style):',
+      default: '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: 'Content',
+      validate: v => v.trim() ? true : 'Column name is required',
+    },
+    {
+      type: 'input',
+      name: 'BinID',
+      message: 'BinID (optional, press Enter to skip):',
+      default: '',
+    },
+    {
+      type: 'input',
+      name: 'SiteID',
+      message: 'SiteID (optional, press Enter to skip):',
+      default: '',
+    },
+    {
+      type: 'input',
+      name: 'Path',
+      message: 'Path (optional, press Enter for auto-generated):',
+      default: relative(process.cwd(), filePath).replace(/\\/g, '/'),
+    },
+  ]);
+
+  // AppID: smart prompt when config has app info
+  if (appConfig.AppID) {
+    const { appIdChoice } = await inquirer.prompt([{
+      type: 'list',
+      name: 'appIdChoice',
+      message: `You're creating metadata without an AppID, but your config has information about the current App. Do you want me to add that Column information?`,
+      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
+  const 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._companionReferenceColumns = [answers.contentColumn.trim()];
+
+  // Write metadata file — NO server submission
+  await writeFile(metaPath, JSON.stringify(meta, null, 2) + '\n');
+  log.success(`Created ${basename(metaPath)}`);
+  log.dim(`  Run "dbo push" to insert this record on the server.`);
+}
+
+/**
+ * Attach a file to an existing metadata record as an additional companion column.
+ */
+async function adoptIntoRecord(filePath, intoPath, columnArg, options) {
+  if (!columnArg) {
+    log.error('-e <column> is required when using --into');
+    process.exit(1);
+  }
+
+  // Load target metadata
+  let targetMeta;
+  try {
+    targetMeta = JSON.parse(await readFile(intoPath, 'utf8'));
+  } catch {
+    log.error(`Target metadata not found: ${intoPath}`);
+    process.exit(1);
+  }
+
+  const targetEntity = targetMeta._entity;
+  if (!targetEntity) {
+    log.error(`Target metadata has no _entity field: ${intoPath}`);
+    process.exit(1);
+  }
+
+  // Parse column from -e (strip entity prefix if provided, validate if it doesn't match)
+  let column = columnArg;
+  const dotIdx = columnArg.indexOf('.');
+  if (dotIdx !== -1) {
+    const entityPrefix = columnArg.slice(0, dotIdx);
+    column = columnArg.slice(dotIdx + 1);
+    if (entityPrefix !== targetEntity) {
+      log.error(`Entity mismatch: -e specifies "${entityPrefix}" but target metadata has _entity "${targetEntity}"`);
+      process.exit(1);
+    }
+  }
+
+  // Validate column in metadata_schema.json
+  const metadataSchema = await loadMetadataSchema() ?? {};
+  const cols = getTemplateCols(metadataSchema, targetEntity, targetMeta.Descriptor ?? null);
+  if (cols && !cols.some(c => c === column || c.startsWith(column + '='))) {
+    log.warn(`Column "${column}" is not in the metadata schema for "${targetEntity}" — proceeding anyway.`);
+  }
+
+  // Check if column already set
+  if (targetMeta[column] !== undefined) {
+    if (!options.yes) {
+      const inquirer = (await import('inquirer')).default;
+      const { overwrite } = await inquirer.prompt([{
+        type: 'confirm',
+        name: 'overwrite',
+        message: `Column "${column}" already has value "${targetMeta[column]}" in ${basename(intoPath)}. Overwrite?`,
+        default: false,
+      }]);
+      if (!overwrite) return;
+    }
+  }
+
+  // Add column and update _companionReferenceColumns
+  const fileName = basename(filePath);
+  targetMeta[column] = `@${fileName}`;
+  const refs = targetMeta._companionReferenceColumns ?? [];
+  if (!refs.includes(column)) refs.push(column);
+  targetMeta._companionReferenceColumns = refs;
+
+  await writeFile(intoPath, JSON.stringify(targetMeta, null, 2) + '\n');
+  log.success(`Added ${column}: "@${fileName}" to ${basename(intoPath)}`);
+  log.dim(`  _companionReferenceColumns: ${JSON.stringify(targetMeta._companionReferenceColumns)}`);
+  log.dim(`  Run "dbo push" to insert/update the record on the server.`);
+}
+
+/**
+ * Adopt all un-tracked files in a directory.
+ */
+async function adoptDirectory(dirPath, entityArg, options) {
+  if (!entityArg) {
+    log.error('The -e flag is required when adopting a directory.');
+    process.exit(1);
+  }
+
+  // Find files without metadata using the existing findUnaddedFiles logic
+  const ig = await loadIgnore();
+  const unadopted = await findUnaddedFiles(dirPath, ig);
+
+  if (unadopted.length === 0) {
+    log.info('Nothing to adopt — all files already have metadata.');
+    return;
+  }
+
+  const metadataSchema = await loadMetadataSchema() ?? {};
+  const parsed = parseEntitySpec(entityArg, metadataSchema);
+
+  log.info(`Found ${unadopted.length} file(s) to adopt as "${entityArg}":`);
+  for (const f of unadopted) {
+    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: `Create metadata for ${unadopted.length} file(s) as "${entityArg}"?`,
+      default: true,
+    }]);
+    if (!proceed) return;
+  }
+
+  let succeeded = 0;
+  let skipped = 0;
+
+  for (const filePath of unadopted) {
+    try {
+      await adoptSingleFile(filePath, entityArg, { ...options, yes: true }); // suppress per-file prompts
+      succeeded++;
+    } catch (err) {
+      log.error(`Failed: ${relative(process.cwd(), filePath)} — ${err.message}`);
+      skipped++;
+    }
+  }
+
+  log.info(`Adopt complete: ${succeeded} created, ${skipped} failed/skipped.`);
+}

package/src/commands/clone.js

@@ -1884,7 +1884,7 @@ async function processEntityDirEntries(entityName, entries, options, serverTz) {
         const configWithTz = { ...config, ServerTimezone: serverTz };
         const localSyncTime = await getLocalSyncTime(metaPath);
 
-        // If local metadata has no _LastUpdated (e.g. from dbo add), treat as server-newer
+        // If local metadata has no _LastUpdated (e.g. from dbo adopt), treat as server-newer
         let localMissingLastUpdated = false;
         try {
           const localMeta = JSON.parse(await readFile(metaPath, 'utf8'));
@@ -1895,7 +1895,7 @@ async function processEntityDirEntries(entityName, entries, options, serverTz) {
         const serverDate = parseServerDate(record._LastUpdated, serverTz);
 
         if (serverNewer) {
-          // Incomplete metadata (no _LastUpdated) from dbo add — auto-accept without prompting
+          // Incomplete metadata (no _LastUpdated) from dbo adopt — auto-accept without prompting
           if (localMissingLastUpdated) {
             log.dim(`  Completing metadata: ${name}`);
             // Fall through to write
@@ -3133,7 +3133,7 @@ async function processRecord(entityName, record, structure, options, usedNames,
       const configWithTz = { ...config, ServerTimezone: serverTz };
       const localSyncTime = await getLocalSyncTime(metaPath);
 
-      // If local metadata has no _LastUpdated (e.g. from dbo add with incomplete fields),
+      // If local metadata has no _LastUpdated (e.g. from dbo adopt with incomplete fields),
       // always treat as server-newer so pull populates missing columns.
       let localMissingLastUpdated = false;
       try {
@@ -3145,7 +3145,7 @@ async function processRecord(entityName, record, structure, options, usedNames,
       const serverDate = parseServerDate(record._LastUpdated, serverTz);
 
       if (serverNewer) {
-        // Incomplete metadata (no _LastUpdated) from dbo add — auto-accept without prompting
+        // Incomplete metadata (no _LastUpdated) from dbo adopt — auto-accept without prompting
         if (localMissingLastUpdated) {
           log.dim(`  Completing metadata: ${fileName}`);
           // Fall through to write

package/src/commands/push.js

@@ -20,7 +20,7 @@ import { BINS_DIR, ENTITY_DIR_NAMES, loadStructureFile, findBinByPath } from '..
 import { ensureTrashIcon, setFileTag } from '../lib/tagging.js';
 import { checkToeStepping } from '../lib/toe-stepping.js';
 import { runPendingMigrations } from '../lib/migrations.js';
-// AUTO-ADD DISABLED: import { findUnaddedFiles, detectBinFile, submitAdd } from './add.js';
+// AUTO-ADD DISABLED: import { findUnaddedFiles, detectBinFile, submitAdd } from '../lib/insert.js';
 
 /**
  * Resolve an @reference file path to an absolute filesystem path.

package/src/lib/filenames.js

@@ -251,7 +251,7 @@ export async function renameToUidConvention(meta, metaPath, uid, lastUpdated, se
   }
 
   // Determine naturalBase from the temp/old metadata filename
-  // Temp format from add.js: "colors.metadata.json" → naturalBase = "colors"
+  // Temp format from adopt.js: "colors.metadata.json" → naturalBase = "colors"
   // Old tilde format: "colors~uid.metadata.json" → naturalBase = "colors"
   let naturalBase;
   const legacyParsed = detectLegacyTildeMetadata(metaFilename);