@dboio/cli 0.13.2 → 0.15.1

package/src/commands/login.js

@@ -1,5 +1,5 @@
 import { Command } from 'commander';
-import { loadConfig, saveUserInfo, saveUserProfile, ensureGitignore } from '../lib/config.js';
+import { loadConfig, initConfig, saveUserInfo, saveUserProfile, ensureGitignore } from '../lib/config.js';
 import { DboClient } from '../lib/client.js';
 import { log } from '../lib/logger.js';
 
@@ -13,13 +13,24 @@ import { log } from '../lib/logger.js';
  */
 export async function performLogin(domain, knownUsername) {
   const config = await loadConfig();
+  const inquirer = (await import('inquirer')).default;
+
+  // Prompt for domain if not provided and not configured
+  if (!domain && !config.domain) {
+    const { domain: inputDomain } = await inquirer.prompt([
+      { type: 'input', name: 'domain', message: 'Domain (e.g. myapp.dbo.io):' },
+    ]);
+    if (!inputDomain) throw new Error('Domain is required.');
+    domain = inputDomain.trim();
+    await initConfig(domain);
+  }
+
   const client = new DboClient({ domain });
 
   let username = knownUsername || config.username;
   let password;
 
   // Interactive prompt for missing credentials
-  const inquirer = (await import('inquirer')).default;
   const answers = await inquirer.prompt([
     { type: 'input', name: 'username', message: 'Username (email):', default: username || undefined, when: !username },
     { type: 'password', name: 'password', message: 'Password:', mask: '*' },
@@ -83,7 +94,23 @@ export const loginCommand = new Command('login')
   .action(async (options) => {
     try {
       const config = await loadConfig();
-      const client = new DboClient({ domain: options.domain });
+      const inquirer = (await import('inquirer')).default;
+      let domain = options.domain;
+
+      // Prompt for domain if not provided and not configured
+      if (!domain && !config.domain) {
+        const { domain: inputDomain } = await inquirer.prompt([
+          { type: 'input', name: 'domain', message: 'Domain (e.g. myapp.dbo.io):' },
+        ]);
+        if (!inputDomain) {
+          log.error('Domain is required.');
+          process.exit(1);
+        }
+        domain = inputDomain.trim();
+        await initConfig(domain);
+      }
+
+      const client = new DboClient({ domain });
 
       let username = options.username || options.email || options.phone;
       let password = options.password || options.passkey;
@@ -93,7 +120,6 @@ export const loginCommand = new Command('login')
 
       // Interactive prompt if still missing
       if (!username || !password) {
-        const inquirer = (await import('inquirer')).default;
         const answers = await inquirer.prompt([
           { type: 'input', name: 'username', message: 'Username (email):', default: config.username, when: !username },
           { type: 'password', name: 'password', message: 'Password:', mask: '*', when: !password },

package/src/commands/mv.js

@@ -13,8 +13,9 @@ import {
   BINS_DIR
 } from '../lib/structure.js';
 import { findMetadataFiles } from '../lib/diff.js';
-import { findMetadataForCompanion } from '../lib/filenames.js';
+import { isMetadataFile, parseMetaFilename, findMetadataForCompanion } from '../lib/filenames.js';
 import { runPendingMigrations } from '../lib/migrations.js';
+import { removeDeployEntry, upsertDeployEntry } from '../lib/deploy-config.js';
 
 export const mvCommand = new Command('mv')
   .description('Move files or bins to a new location and update metadata')
@@ -200,7 +201,7 @@ function checkCircularReference(sourceBinId, targetBinId, structure) {
  * Resolve a file path to its metadata.json path.
  */
 function resolveMetaPath(filePath) {
-  if (filePath.endsWith('.metadata.json')) {
+  if (isMetadataFile(basename(filePath)) || filePath.endsWith('.metadata.json')) {
     return filePath;
   }
   const dir = dirname(filePath);
@@ -544,13 +545,13 @@ async function mvFile(sourceFile, targetBinId, structure, options) {
   // Calculate paths
   const targetDir = resolveBinPath(targetBinId, structure);
   const sourceDir = dirname(metaPath);
-  const contentFileName = sourceFile.endsWith('.metadata.json')
+  const contentFileName = (isMetadataFile(basename(sourceFile)) || sourceFile.endsWith('.metadata.json'))
     ? null
     : basename(sourceFile);
   const metaFileName = basename(metaPath);
 
   // Determine display name
-  const displayName = basename(metaPath, '.metadata.json');
+  const displayName = parseMetaFilename(basename(metaPath))?.naturalBase ?? basename(metaPath, '.metadata.json');
   const targetBin = structure[targetBinId];
   const targetBinName = targetBin ? targetBin.name : String(targetBinId);
   const targetBinFullPath = targetBin ? `${BINS_DIR}/${targetBin.fullPath}` : targetDir;
@@ -672,6 +673,18 @@ async function mvFile(sourceFile, targetBinId, structure, options) {
     }
   }
 
+  if (!options.dryRun) {
+    // Update deploy config: remove old entry (by UID), re-insert with new path + correct key
+    await removeDeployEntry(uid);
+    if (newContentPath) {
+      const col = (meta._contentColumns || [])[0] || 'Content';
+      await upsertDeployEntry(newContentPath, uid, entity, col);
+    } else if (meta._mediaFile && String(meta._mediaFile).startsWith('@')) {
+      const movedMediaPath = join(targetDir, String(meta._mediaFile).substring(1));
+      await upsertDeployEntry(movedMediaPath, uid, entity, 'File');
+    }
+  }
+
   if (options.dryRun) {
     log.info(`[DRY RUN] Would move "${displayName}" to "${targetBinName}" (${targetBinFullPath})`);
   } else {

package/src/commands/push.js

@@ -12,15 +12,25 @@ import { checkStoredTicket, applyStoredTicketToSubmission, clearRecordTicket, cl
 import { checkModifyKey, isModifyKeyError, handleModifyKeyError } from '../lib/modify-key.js';
 import { resolveTransactionKey } from '../lib/transaction-key.js';
 import { setFileTimestamps } from '../lib/timestamps.js';
-import { stripUidFromFilename, renameToUidConvention, hasUidInFilename, findMetadataForCompanion } from '../lib/filenames.js';
+import { stripUidFromFilename, renameToUidConvention, hasUidInFilename, isMetadataFile, parseMetaFilename, findMetadataForCompanion } from '../lib/filenames.js';
 import { findMetadataFiles, findFileInProject, findByUID } from '../lib/diff.js';
 import { loadIgnore } from '../lib/ignore.js';
 import { detectChangedColumns, findBaselineEntry, detectOutputChanges, getAllUserColumns, isReference, resolveReferencePath, detectBinChanges, synthesizeBinMetadata } from '../lib/delta.js';
 import { BINS_DIR, ENTITY_DIR_NAMES, loadStructureFile, findBinByPath } from '../lib/structure.js';
-import { ensureTrashIcon } from '../lib/folder-icon.js';
+import { ensureTrashIcon, setFileTag } from '../lib/tagging.js';
 import { checkToeStepping } from '../lib/toe-stepping.js';
 import { runPendingMigrations } from '../lib/migrations.js';
-import { findUnaddedFiles, detectBinFile, submitAdd } from './add.js';
+// AUTO-ADD DISABLED: import { findUnaddedFiles, detectBinFile, submitAdd } from './add.js';
+
+function _getMetaCompanionPaths(meta, metaPath) {
+  const dir = dirname(metaPath);
+  const paths = [];
+  for (const col of (meta._contentColumns || [])) {
+    const ref = meta[col];
+    if (ref && String(ref).startsWith('@')) paths.push(join(dir, String(ref).substring(1)));
+  }
+  return paths;
+}
 
 /**
  * Resolve an @reference file path to an absolute filesystem path.
@@ -86,7 +96,7 @@ export const pushCommand = new Command('push')
       const transactionKey = await resolveTransactionKey(options);
 
       // Process pending deletions from synchronize.json
-      await processPendingDeletes(client, options, modifyKey, transactionKey);
+      const deletedCount = await processPendingDeletes(client, options, modifyKey, transactionKey) || 0;
 
       // ── Resolution order ──────────────────────────────────────────
       // 1. Commas → UID list
@@ -125,7 +135,7 @@ export const pushCommand = new Command('push')
             log.dim(`  Found: ${relative(process.cwd(), resolved)}`);
             const resolvedStat = await stat(resolved);
             if (resolvedStat.isDirectory()) {
-              await pushDirectory(resolved, client, options, modifyKey, transactionKey);
+              await pushDirectory(resolved, client, options, modifyKey, transactionKey, deletedCount);
             } else {
               await pushSingleFile(resolved, client, options, modifyKey, transactionKey);
             }
@@ -146,7 +156,7 @@ export const pushCommand = new Command('push')
       }
 
       if (pathStat.isDirectory()) {
-        await pushDirectory(targetPath, client, options, modifyKey, transactionKey);
+        await pushDirectory(targetPath, client, options, modifyKey, transactionKey, deletedCount);
       } else {
         await pushSingleFile(targetPath, client, options, modifyKey, transactionKey);
       }
@@ -161,18 +171,27 @@ export const pushCommand = new Command('push')
  */
 async function processPendingDeletes(client, options, modifyKey = null, transactionKey = 'RowUID') {
   const sync = await loadSynchronize();
-  if (!sync.delete || sync.delete.length === 0) return;
+  if (!sync.delete || sync.delete.length === 0) return 0;
 
   log.info(`Processing ${sync.delete.length} pending deletion(s)...`);
 
   const remaining = [];
   const deletedUids = [];
 
+  // Load stored ticket once for all deletions (same as main push loop)
+  const { getGlobalTicket, getRecordTicket } = await import('../lib/ticketing.js');
+  const globalTicket = !options.ticket ? await getGlobalTicket() : null;
+
   for (const entry of sync.delete) {
     log.info(`Deleting "${entry.name}" (${entry.entity}:${entry.RowID})`);
 
     const extraParams = { '_confirm': options.confirm || 'true' };
-    if (options.ticket) extraParams['_OverrideTicketID'] = options.ticket;
+    if (options.ticket) {
+      extraParams['_OverrideTicketID'] = options.ticket;
+    } else {
+      const ticket = await getRecordTicket(entry.UID) || globalTicket;
+      if (ticket) extraParams['_OverrideTicketID'] = ticket;
+    }
     if (modifyKey) extraParams['_modify_key'] = modifyKey;
     const cachedUser2 = getSessionUserOverride();
     if (cachedUser2) extraParams['_OverrideUserID'] = cachedUser2;
@@ -234,6 +253,8 @@ async function processPendingDeletes(client, options, modifyKey = null, transact
   if (remaining.length > 0) {
     log.warn(`${remaining.length} deletion(s) failed and remain staged.`);
   }
+
+  return deletedUids.length;
 }
 
 /**
@@ -306,13 +327,20 @@ async function moveWillDeleteToTrash(entry) {
 async function pushSingleFile(filePath, client, options, modifyKey = null, transactionKey = 'RowUID') {
   // Find the metadata file
   let metaPath;
-  if (filePath.endsWith('.metadata.json')) {
+  if (isMetadataFile(basename(filePath)) || filePath.endsWith('.metadata.json')) {
     // User passed the metadata file directly — use it as-is
     metaPath = filePath;
   } else {
-    const dir = dirname(filePath);
-    const base = basename(filePath, extname(filePath));
-    metaPath = join(dir, `${base}.metadata.json`);
+    // Try findMetadataForCompanion first (handles both new and legacy formats)
+    const found = await findMetadataForCompanion(filePath);
+    if (found) {
+      metaPath = found;
+    } else {
+      // Fallback: old convention
+      const dir = dirname(filePath);
+      const base = basename(filePath, extname(filePath));
+      metaPath = join(dir, `${base}.metadata.json`);
+    }
   }
 
   let meta;
@@ -326,27 +354,12 @@ async function pushSingleFile(filePath, client, options, modifyKey = null, trans
       try { meta = JSON.parse(await readFile(metaPath, 'utf8')); } catch {}
     }
     if (!meta) {
-      // Try auto-detecting as a bin content/media file and add it first
-      const binMeta = await detectBinFile(filePath);
-      if (binMeta) {
-        log.info(`No metadata found — auto-adding "${basename(filePath)}" first`);
-        try {
-          await submitAdd(binMeta.meta, binMeta.metaPath, filePath, client, options);
-          // After successful add, re-read the metadata (now has UID)
-          metaPath = binMeta.metaPath;
-          // The metadata file may have been renamed with ~UID, so scan for it
-          const updatedMeta = await findMetadataForCompanion(filePath);
-          if (updatedMeta) metaPath = updatedMeta;
-          meta = JSON.parse(await readFile(metaPath, 'utf8'));
-          log.info(`Successfully added — now pushing updates`);
-        } catch (err) {
-          log.error(`Auto-add failed for "${basename(filePath)}": ${err.message}`);
-          process.exit(1);
-        }
-      } else {
-        log.error(`No metadata found for "${basename(filePath)}". Pull the record first with "dbo pull".`);
-        process.exit(1);
-      }
+      // AUTO-ADD DISABLED: local-file-first approach is being replaced by server-first workflow.
+      // New records should be created via the DBO REST API first, then `dbo pull` to populate locally.
+      // The auto-add code (detectBinFile + submitAdd) has been commented out intentionally.
+      // See: .claude/2_specs/auto-deploy-config-generation.md — "server-first approach"
+      log.error(`No metadata found for "${basename(filePath)}". Create the record on the server first, then run "dbo pull".`);
+      process.exit(1);
     }
   }
 
@@ -456,61 +469,16 @@ async function ensureManifestMetadata() {
 /**
  * Push all records found in a directory (recursive)
  */
-async function pushDirectory(dirPath, client, options, modifyKey = null, transactionKey = 'RowUID') {
+async function pushDirectory(dirPath, client, options, modifyKey = null, transactionKey = 'RowUID', deletedCount = 0) {
   // Auto-create manifest.metadata.json if manifest.json exists at root without companion metadata
   await ensureManifestMetadata();
 
-  // ── Auto-add: detect un-added files and create+submit them before push ──
-  const ig = await loadIgnore();
-  const justAddedUIDs = new Set(); // Track UIDs added in this invocation — skip from push loop
-
-  const unadded = await findUnaddedFiles(dirPath, ig);
-  if (unadded.length > 0) {
-    // Filter to files that detectBinFile can auto-classify (content/media in bins)
-    const autoAddable = [];
-    for (const filePath of unadded) {
-      const binMeta = await detectBinFile(filePath);
-      if (binMeta) autoAddable.push({ filePath, ...binMeta });
-    }
-
-    if (autoAddable.length > 0) {
-      log.info(`Found ${autoAddable.length} new file(s) to add before push:`);
-      for (const { filePath } of autoAddable) {
-        log.plain(`  ${relative(process.cwd(), filePath)}`);
-      }
-
-      const doAdd = async () => {
-        for (const { meta, metaPath, filePath } of autoAddable) {
-          try {
-            await submitAdd(meta, metaPath, filePath, client, options);
-            // After submitAdd, meta.UID is set if successful
-            if (meta.UID) justAddedUIDs.add(meta.UID);
-          } catch (err) {
-            log.error(`Failed to add ${relative(process.cwd(), filePath)}: ${err.message}`);
-          }
-        }
-      };
-
-      if (!options.yes) {
-        const inquirer = (await import('inquirer')).default;
-        const { proceed } = await inquirer.prompt([{
-          type: 'confirm',
-          name: 'proceed',
-          message: `Add ${autoAddable.length} file(s) to the server before pushing?`,
-          default: true,
-        }]);
-        if (!proceed) {
-          log.dim('Skipping auto-add — continuing with push');
-        } else {
-          await doAdd();
-        }
-      } else {
-        await doAdd();
-      }
-      if (justAddedUIDs.size > 0) log.plain('');
-    }
-  }
+  // AUTO-ADD DISABLED: local-file-first approach is being replaced by server-first workflow.
+  // New records should be created via the DBO REST API first, then `dbo pull` to populate locally.
+  // The auto-add code (findUnaddedFiles + detectBinFile + submitAdd) has been commented out.
+  // See: .claude/2_specs/auto-deploy-config-generation.md — "server-first approach"
 
+  const ig = await loadIgnore();
   const metaFiles = await findMetadataFiles(dirPath, ig);
 
   // ── Load scripts config early (before delta detection) ──────────────
@@ -597,16 +565,16 @@ async function pushDirectory(dirPath, client, options, modifyKey = null, transac
       continue;
     }
 
-    // Skip records that were just auto-added in this invocation — they're already on the server
-    if (meta.UID && justAddedUIDs.has(meta.UID)) {
-      log.dim(`  Skipped (just added): ${basename(metaPath)}`);
-      continue;
-    }
+    // AUTO-ADD DISABLED: justAddedUIDs skip removed (server-first workflow)
 
-    // Compound output files: handle root + all inline children together
-    // These have _entity='output' and inline children under .children
-    if (meta._entity === 'output' && meta.children) {
-      outputCompoundFiles.push({ meta, metaPath });
+    // Output hierarchy entities: only push compound output files (root with inline children).
+    // Flat output metadata without .children are skipped — they are pushed as part of
+    // their parent compound file, or via `dbo deploy`. Never as standalone records.
+    if (meta._entity === 'output' || meta._entity === 'output_value'
+        || meta._entity === 'output_value_filter' || meta._entity === 'output_value_entity_column_rel') {
+      if (meta._entity === 'output' && meta.children) {
+        outputCompoundFiles.push({ meta, metaPath });
+      }
       continue;
     }
 
@@ -702,23 +670,44 @@ async function pushDirectory(dirPath, client, options, modifyKey = null, transac
     }
   } catch { /* structure file missing or bin lookup failed — skip */ }
 
-  if (toPush.length === 0 && outputCompoundFiles.length === 0 && binPushItems.length === 0) {
-    if (metaFiles.length === 0) {
+  // Pre-filter compound output files: run delta detection early so unchanged outputs
+  // are excluded from the record count and ticket prompt (avoids false-positive prompts).
+  const outputsWithChanges = [];
+  for (const item of outputCompoundFiles) {
+    if (baseline) {
+      try {
+        const delta = await detectOutputChanges(item.metaPath, baseline);
+        const totalChanges = delta.root.length +
+          (delta.children ? Object.values(delta.children).reduce((s, c) => s + c.length, 0) : 999);
+        if (totalChanges === 0) {
+          log.dim(`  Skipping ${basename(item.metaPath)} — no changes detected`);
+          skipped++;
+          continue;
+        }
+      } catch { /* delta detection failed — include in push for safety */ }
+    }
+    outputsWithChanges.push(item);
+  }
+
+  if (toPush.length === 0 && outputsWithChanges.length === 0 && binPushItems.length === 0) {
+    if (metaFiles.length === 0 && deletedCount === 0) {
       log.warn(`No .metadata.json files found in "${dirPath}".`);
+    } else if (deletedCount > 0) {
+      log.info(`${deletedCount} deletion(s) processed. No other changes to push.`);
     } else {
       log.info('No changes to push');
     }
     return;
   }
 
-  log.info(`Found ${metaFiles.length} record(s) to push`);
+  log.info(`Found ${toPush.length + outputsWithChanges.length + binPushItems.length} record(s) to push`);
 
   // Pre-flight ticket validation (only if no --ticket flag)
-  const totalRecords = toPush.length + outputCompoundFiles.length + binPushItems.length;
+  const totalRecords = toPush.length + outputsWithChanges.length + binPushItems.length;
   if (!options.ticket && totalRecords > 0) {
     const recordSummary = [
-      ...toPush.map(r => basename(r.metaPath, '.metadata.json')),
-      ...outputCompoundFiles.map(r => basename(r.metaPath, '.json')),
+      ...toPush.map(r => { const p = parseMetaFilename(basename(r.metaPath)); return p ? p.naturalBase : basename(r.metaPath, '.metadata.json'); }),
+      ...outputsWithChanges.map(r => basename(r.metaPath, '.json')),
       ...binPushItems.map(r => `bin:${r.meta.Name}`),
     ].join(', ');
     const ticketCheck = await checkStoredTicket(options, `${totalRecords} record(s): ${recordSummary}`);
@@ -818,8 +807,8 @@ async function pushDirectory(dirPath, client, options, modifyKey = null, transac
     }
   }
 
-  // Process compound output files (root + inline children)
-  for (const { meta, metaPath } of outputCompoundFiles) {
+  // Process compound output files (root + inline children) — already pre-filtered for changes
+  for (const { meta, metaPath } of outputsWithChanges) {
     try {
       const result = await pushOutputCompound(meta, metaPath, client, options, baseline, modifyKey, transactionKey);
       if (result.pushed > 0) {
@@ -861,6 +850,13 @@ async function pushDirectory(dirPath, client, options, modifyKey = null, transac
     await updateBaselineAfterPush(baseline, successfulPushes);
   }
 
+  // Re-tag successfully pushed files as Synced (best-effort)
+  for (const { meta, metaPath } of successfulPushes) {
+    for (const filePath of _getMetaCompanionPaths(meta, metaPath)) {
+      setFileTag(filePath, 'synced').catch(() => {});
+    }
+  }
+
   log.info(`Push complete: ${succeeded} succeeded, ${failed} failed, ${skipped} skipped`);
 }
 
@@ -1221,7 +1217,8 @@ async function pushFromMetadata(meta, metaPath, client, options, changedColumns
   }
 
   const fieldLabel = changedColumns ? `${dataExprs.length} changed field(s)${isMediaUpload ? ' + media file' : ''}` : `${dataExprs.length} field(s)`;
-  log.info(`Pushing ${basename(metaPath, '.metadata.json')} (${entity}:${rowKeyValue}) — ${fieldLabel}`);
+  const pushDisplayName = parseMetaFilename(basename(metaPath))?.naturalBase ?? basename(metaPath, '.metadata.json');
+  log.info(`Pushing ${pushDisplayName} (${entity}:${rowKeyValue}) — ${fieldLabel}`);
 
   // Apply stored ticket if no --ticket flag
   const storedTicket = await applyStoredTicketToSubmission(dataExprs, entity, uid || id, uid || id, options);
@@ -1449,7 +1446,7 @@ async function checkPathMismatch(meta, metaPath, entity, options) {
   if (ENTITY_DIR_NAMES.has(entity)) return;
 
   const metaDir = dirname(metaPath);
-  const metaBase = basename(metaPath, '.metadata.json');
+  const metaBase = parseMetaFilename(basename(metaPath))?.naturalBase ?? basename(metaPath, '.metadata.json');
 
   // Find the content file referenced by @filename
   const contentCols = meta._contentColumns || [];

package/src/commands/rm.js

@@ -5,9 +5,10 @@ import { log } from '../lib/logger.js';
 import { formatError } from '../lib/formatter.js';
 import { addDeleteEntry, removeAppJsonReference } from '../lib/config.js';
 import { findMetadataFiles } from '../lib/diff.js';
-import { findMetadataForCompanion } from '../lib/filenames.js';
+import { isMetadataFile, parseMetaFilename, findMetadataForCompanion } from '../lib/filenames.js';
 import { loadStructureFile, findBinByPath, findChildBins, BINS_DIR } from '../lib/structure.js';
 import { runPendingMigrations } from '../lib/migrations.js';
+import { removeDeployEntry } from '../lib/deploy-config.js';
 
 export const rmCommand = new Command('rm')
   .description('Remove a file or directory locally and stage server deletions for the next dbo push')
@@ -42,7 +43,7 @@ export const rmCommand = new Command('rm')
  * Resolve a file path to its metadata.json path.
  */
 function resolveMetaPath(filePath) {
-  if (filePath.endsWith('.metadata.json')) {
+  if (isMetadataFile(basename(filePath)) || filePath.endsWith('.metadata.json')) {
     return filePath;
   }
   const dir = dirname(filePath);
@@ -101,7 +102,7 @@ async function rmFileRecord(metaPath, options, { skipPrompt = false } = {}) {
     localFiles.push(join(metaDir, String(meta._mediaFile).substring(1)));
   }
 
-  const displayName = basename(metaPath, '.metadata.json');
+  const displayName = parseMetaFilename(basename(metaPath))?.naturalBase ?? basename(metaPath, '.metadata.json');
 
   // Prompt if needed
   if (!skipPrompt && !options.force) {
@@ -121,6 +122,7 @@ async function rmFileRecord(metaPath, options, { skipPrompt = false } = {}) {
   // Stage deletion (include metaPath for Trash workflow in push.js)
   const expression = `RowID:del${rowId};entity:${entity}=true`;
   await addDeleteEntry({ UID: uid, RowID: rowId, entity, name: displayName, expression, metaPath });
+  await removeDeployEntry(uid);
   log.success(`  Staged: ${displayName} → ${expression}`);
 
   // Remove from app.json
@@ -205,7 +207,7 @@ async function rmFile(filePath, options) {
     localFiles.push(join(metaDir, String(meta._mediaFile).substring(1)));
   }
 
-  const displayName = basename(metaPath, '.metadata.json');
+  const displayName = parseMetaFilename(basename(metaPath))?.naturalBase ?? basename(metaPath, '.metadata.json');
   log.info(`Removing "${displayName}" (${entity}:${uid || rowId})`);
   for (const f of localFiles) {
     log.dim(`  ${f}`);

package/src/commands/tag.js

@@ -0,0 +1,65 @@
+import { Command } from 'commander';
+import chalk from 'chalk';
+import { tagProjectFiles } from '../lib/tagging.js';
+import { loadTagConfig, saveTagConfig } from '../lib/config.js';
+import { loadIgnore } from '../lib/ignore.js';
+import { join } from 'path';
+
+export const tagCommand = new Command('tag')
+  .description('Apply sync-status tags (Finder color tags / gio emblems) to project files')
+  .argument('[path]', 'File or directory to tag (defaults to entire project)')
+  .option('--clear', 'Remove all dbo:* tags from companion files')
+  .option('--status', 'Show counts of synced / modified / untracked / trashed files')
+  .option('--enable', 'Enable automatic tagging after clone/pull/push')
+  .option('--disable', 'Disable automatic tagging after clone/pull/push')
+  .option('--verbose', 'Log each file with its status')
+  .action(async (pathArg, options) => {
+    if (options.enable) {
+      await saveTagConfig(true);
+      console.log(chalk.green('✔ Automatic file tagging enabled'));
+      return;
+    }
+    if (options.disable) {
+      await saveTagConfig(false);
+      console.log(chalk.yellow('Automatic file tagging disabled'));
+      return;
+    }
+
+    // Verify project is initialized
+    const ig = await loadIgnore().catch(() => null);
+    if (!ig) {
+      console.error(chalk.red('Not a dbo project'));
+      process.exit(1);
+    }
+
+    const dir = pathArg ? join(process.cwd(), pathArg) : process.cwd();
+
+    if (options.clear) {
+      await tagProjectFiles({ clearAll: true, dir, verbose: options.verbose });
+      console.log(chalk.green('✔ All dbo:* tags cleared'));
+      return;
+    }
+
+    const counts = await tagProjectFiles({ verbose: options.verbose, dir });
+
+    if (counts === null) {
+      const { tagFiles } = await loadTagConfig();
+      if (!tagFiles) {
+        console.log(chalk.yellow('File tagging is disabled. Run `dbo tag --enable` to enable.'));
+      } else {
+        console.log(chalk.dim('File tagging is not supported on this platform.'));
+      }
+      return;
+    }
+
+    if (options.status || options.verbose) {
+      console.log(
+        `${chalk.green(counts.synced)} synced, ` +
+        `${chalk.blue(counts.modified)} modified, ` +
+        `${chalk.yellow(counts.untracked)} untracked, ` +
+        `${chalk.red(counts.trashed)} trashed`
+      );
+    } else {
+      console.log(chalk.green(`✔ Tags applied (${counts.synced} synced, ${counts.modified} modified, ${counts.untracked} untracked)`));
+    }
+  });

package/src/lib/config.js

@@ -936,3 +936,31 @@ export async function loadScriptsLocal() {
     throw new SyntaxError(`Invalid JSON in .dbo/scripts.local.json: ${err.message}`);
   }
 }
+
+// ─── Tag Config ───────────────────────────────────────────────────────────────
+
+/**
+ * Load the tagFiles setting from config.json.
+ * @returns {Promise<{tagFiles: boolean}>} defaults to true
+ */
+export async function loadTagConfig() {
+  try {
+    const raw = await readFile(join(process.cwd(), DBO_DIR, CONFIG_FILE), 'utf8');
+    const config = JSON.parse(raw);
+    return { tagFiles: config.tagFiles !== false };
+  } catch {
+    return { tagFiles: true };
+  }
+}
+
+/**
+ * Enable or disable automatic file tagging by writing to config.json.
+ * @param {boolean} enabled
+ */
+export async function saveTagConfig(enabled) {
+  const configPath = join(process.cwd(), DBO_DIR, CONFIG_FILE);
+  let config = {};
+  try { config = JSON.parse(await readFile(configPath, 'utf8')); } catch {}
+  config.tagFiles = enabled;
+  await writeFile(configPath, JSON.stringify(config, null, 2));
+}