@dboio/cli 0.13.2 → 0.15.1

package/src/lib/tagging.js

@@ -0,0 +1,380 @@
+import { execFile } from 'child_process';
+import { writeFile, readFile, unlink, stat, access } from 'fs/promises';
+import { join, dirname, relative } from 'path';
+import { readdir } from 'fs/promises';
+import { tmpdir } from 'os';
+import { promisify } from 'util';
+import { findMetadataFiles, hasLocalModifications } from './diff.js';
+import { loadIgnore } from './ignore.js';
+import { loadAppConfig, loadTagConfig } from './config.js';
+
+const execFileAsync = promisify(execFile);
+
+// ── Tag status map ─────────────────────────────────────────────────────────────
+// Tag names use 'dbo:' prefix so --clear only removes dbo-applied tags.
+// macCode values: 0=None 1=Grey 2=Green 3=Purple 4=Blue 5=Yellow 6=Orange 7=Red
+const TAG_MAP = {
+  synced:    { name: 'dbo:Synced',    macCode: 2, linuxEmblem: 'emblem-default'    },
+  modified:  { name: 'dbo:Modified',  macCode: 4, linuxEmblem: 'emblem-important'  },
+  untracked: { name: 'dbo:Untracked', macCode: 5, linuxEmblem: 'emblem-new'        },
+  conflict:  { name: 'dbo:Conflict',  macCode: 6, linuxEmblem: 'emblem-urgent'     },
+  trashed:   { name: 'dbo:Trashed',   macCode: 7, linuxEmblem: 'emblem-unreadable' },
+};
+
+// ── Public API ─────────────────────────────────────────────────────────────────
+
+/**
+ * Apply sync-status tag to a single file. Best-effort, never throws.
+ * @param {string} filePath  Absolute path to the content/companion file.
+ * @param {string} status    One of: synced | modified | untracked | conflict | trashed
+ */
+export async function setFileTag(filePath, status) {
+  try {
+    const info = TAG_MAP[status];
+    if (!info) return;
+    switch (process.platform) {
+      case 'darwin': await _setMacTag(filePath, info); break;
+      case 'linux':  await _setLinuxTag(filePath, info); break;
+      // win32 and others: silently skip
+    }
+  } catch { /* best-effort */ }
+}
+
+/**
+ * Remove all dbo:* tags from a single file. Best-effort, never throws.
+ * @param {string} filePath  Absolute path to the content/companion file.
+ */
+export async function clearFileTag(filePath) {
+  try {
+    switch (process.platform) {
+      case 'darwin': await _clearMacTag(filePath); break;
+      case 'linux':  await _clearLinuxTag(filePath); break;
+    }
+  } catch { /* best-effort */ }
+}
+
+/**
+ * Scan all companion files in the project and apply sync-status tags.
+ * Respects .dboignore. Skips if tagFiles config is false or platform unsupported.
+ *
+ * @param {Object}  [options]
+ * @param {boolean} [options.verbose]   Log each file tagged.
+ * @param {boolean} [options.clearAll]  Remove all dbo:* tags instead of applying.
+ * @param {string}  [options.dir]       Root directory to scan (defaults to cwd).
+ * @returns {Promise<{synced:number,modified:number,untracked:number,conflict:number,trashed:number}|null>}
+ *   Returns null on unsupported platform or when tagFiles is disabled.
+ */
+export async function tagProjectFiles(options = {}) {
+  const { verbose = false, clearAll = false, dir = process.cwd() } = options;
+  const platform = process.platform;
+  if (platform !== 'darwin' && platform !== 'linux') return null;
+
+  const { tagFiles } = await loadTagConfig().catch(() => ({ tagFiles: true }));
+  if (!tagFiles) return null;
+
+  let config;
+  try { config = await loadAppConfig(); } catch { config = {}; }
+
+  const ig = await loadIgnore();
+  const metaPaths = await findMetadataFiles(dir, ig);
+  const counts = { synced: 0, modified: 0, untracked: 0, conflict: 0, trashed: 0 };
+
+  if (clearAll) {
+    const companions = (await Promise.all(metaPaths.map(mp => _getCompanionPaths(mp)))).flat();
+    await _bulkApplyTags(companions.map(fp => ({ filePath: fp, clear: true })));
+    return null;
+  }
+
+  // Collect file→status pairs from metadata
+  const toTag = [];
+  for (const metaPath of metaPaths) {
+    const inTrash = metaPath.replace(/\\/g, '/').includes('/trash/');
+    const status = inTrash
+      ? 'trashed'
+      : (await hasLocalModifications(metaPath, config).catch(() => false)) ? 'modified'
+      : 'synced';
+    const companions = await _getCompanionPaths(metaPath);
+    for (const filePath of companions) {
+      toTag.push({ filePath, status });
+      counts[status]++;
+      if (verbose) console.log(`  ${status.padEnd(10)} ${relative(dir, filePath)}`);
+    }
+  }
+
+  // Detect untracked files (content files without any metadata)
+  const untrackedFiles = await _findUntrackedFiles(dir, ig, metaPaths);
+  for (const filePath of untrackedFiles) {
+    toTag.push({ filePath, status: 'untracked' });
+    counts.untracked++;
+    if (verbose) console.log(`  untracked  ${relative(dir, filePath)}`);
+  }
+
+  await _bulkApplyTags(toTag);
+
+  // Re-apply trash folder icon (best-effort, in case it was cleared)
+  const trashDir = join(dir, 'trash');
+  ensureTrashIcon(trashDir).catch(() => {});
+
+  return counts;
+}
+
+// ── Private helpers ────────────────────────────────────────────────────────────
+
+async function _getCompanionPaths(metaPath) {
+  try {
+    const meta = JSON.parse(await readFile(metaPath, 'utf8'));
+    const dir = dirname(metaPath);
+    const paths = [];
+    for (const col of (meta._contentColumns || [])) {
+      const ref = meta[col];
+      if (ref && String(ref).startsWith('@')) {
+        const candidate = join(dir, String(ref).substring(1));
+        try { await stat(candidate); paths.push(candidate); } catch { /* missing */ }
+      }
+    }
+    for (const col of (meta._mediaColumns || [])) {
+      const ref = meta[col];
+      if (ref && String(ref).startsWith('@')) {
+        const candidate = join(dir, String(ref).substring(1));
+        try { await stat(candidate); paths.push(candidate); } catch { /* missing */ }
+      }
+    }
+    return paths;
+  } catch { return []; }
+}
+
+async function _findUntrackedFiles(dir, ig, knownMetaPaths) {
+  const knownCompanions = new Set();
+  for (const mp of knownMetaPaths) {
+    for (const fp of await _getCompanionPaths(mp)) knownCompanions.add(fp);
+  }
+  const all = await _collectContentFiles(dir, ig);
+  return all.filter(fp => !knownCompanions.has(fp));
+}
+
+// Recursively collect non-metadata, non-hidden, non-.dbo content files
+async function _collectContentFiles(dir, ig) {
+  const results = [];
+  let entries;
+  try { entries = await readdir(dir, { withFileTypes: true }); } catch { return []; }
+  for (const entry of entries) {
+    if (entry.name.startsWith('.')) continue; // skip hidden and .dbo
+    const fullPath = join(dir, entry.name);
+    const relPath = relative(process.cwd(), fullPath).replace(/\\/g, '/');
+    if (entry.isDirectory()) {
+      if (ig.ignores(relPath + '/') || ig.ignores(relPath)) continue;
+      results.push(...await _collectContentFiles(fullPath, ig));
+    } else {
+      if (entry.name.endsWith('.json')) continue; // skip metadata and config files
+      if (ig.ignores(relPath)) continue;
+      results.push(fullPath);
+    }
+  }
+  return results;
+}
+
+// Apply tags in bulk. For macOS with >50 files, uses a shell script for performance.
+// items: Array<{ filePath: string, status?: string, clear?: boolean }>
+async function _bulkApplyTags(items) {
+  if (!items.length) return;
+  const platform = process.platform;
+
+  if (platform === 'darwin') {
+    if (items.length <= 50) {
+      await Promise.all(items.map(({ filePath, status, clear }) =>
+        clear ? _clearMacTag(filePath) : _setMacTag(filePath, TAG_MAP[status])
+      ));
+    } else {
+      // Batch mode: write one shell script and execute it once
+      const lines = items.map(({ filePath, status, clear }) => {
+        const escaped = filePath.replace(/'/g, "'\\''");
+        if (clear) return `xattr -d com.apple.metadata:_kMDItemUserTags '${escaped}' 2>/dev/null || true`;
+        const info = TAG_MAP[status];
+        if (!info) return '';
+        return `xattr -w com.apple.metadata:_kMDItemUserTags '("${info.name}\\n${info.macCode}")' '${escaped}'`;
+      }).filter(Boolean);
+      const tmpFile = join(tmpdir(), `dbo-tag-${Date.now()}.sh`);
+      await writeFile(tmpFile, `#!/bin/sh\n${lines.join('\n')}\n`);
+      try {
+        await execFileAsync('sh', [tmpFile], { timeout: 30000 });
+      } finally {
+        await unlink(tmpFile).catch(() => {});
+      }
+    }
+  } else if (platform === 'linux') {
+    await Promise.all(items.map(({ filePath, status, clear }) =>
+      clear ? _clearLinuxTag(filePath) : _setLinuxTag(filePath, TAG_MAP[status])
+    ));
+  }
+}
+
+// ── macOS implementation ───────────────────────────────────────────────────────
+
+async function _setMacTag(filePath, tagInfo) {
+  // Read existing non-dbo tags, append the new dbo: tag, write back.
+  const existing = await _readMacTags(filePath);
+  const filtered = existing.filter(t => !t.startsWith('dbo:'));
+  filtered.push(`${tagInfo.name}\n${tagInfo.macCode}`);
+  await _writeMacTags(filePath, filtered);
+}
+
+async function _clearMacTag(filePath) {
+  const existing = await _readMacTags(filePath);
+  const remaining = existing.filter(t => !t.startsWith('dbo:'));
+  if (remaining.length === 0) {
+    await execFileAsync('xattr', ['-d', 'com.apple.metadata:_kMDItemUserTags', filePath], { timeout: 5000 }).catch(() => {});
+  } else {
+    await _writeMacTags(filePath, remaining);
+  }
+}
+
+// Use python3 (always on macOS 10.15+) to read binary plist — no third-party modules needed.
+async function _readMacTags(filePath) {
+  try {
+    const script =
+      `import plistlib,sys,subprocess\n` +
+      `r=subprocess.run(['xattr','-px','com.apple.metadata:_kMDItemUserTags',sys.argv[1]],capture_output=True,text=True)\n` +
+      `if r.returncode!=0:print('');exit()\n` +
+      `hex_=r.stdout.strip().replace(' ','').replace('\\n','')\n` +
+      `tags=plistlib.loads(bytes.fromhex(hex_))\n` +
+      `print('\\x00'.join(tags))`;
+    const { stdout } = await execFileAsync('python3', ['-c', script, filePath], { timeout: 5000 });
+    return stdout.trim() ? stdout.trim().split('\x00') : [];
+  } catch { return []; }
+}
+
+async function _writeMacTags(filePath, tags) {
+  const script =
+    `import plistlib,sys,subprocess\n` +
+    `tags=sys.argv[2:]\n` +
+    `data=plistlib.dumps(tags,fmt=plistlib.FMT_BINARY)\n` +
+    `hex_=data.hex()\n` +
+    `subprocess.run(['xattr','-wx','com.apple.metadata:_kMDItemUserTags',hex_,sys.argv[1]],check=True)`;
+  await execFileAsync('python3', ['-c', script, filePath, ...tags], { timeout: 5000 });
+}
+
+// ── Linux implementation ───────────────────────────────────────────────────────
+
+async function _setLinuxTag(filePath, tagInfo) {
+  await execFileAsync('gio', ['set', filePath, 'metadata::emblems', tagInfo.linuxEmblem], { timeout: 5000 });
+}
+
+async function _clearLinuxTag(filePath) {
+  await execFileAsync('gio', ['set', filePath, 'metadata::emblems', ''], { timeout: 5000 }).catch(() => {});
+}
+
+// ── Folder icon (consolidated from folder-icon.js) ────────────────────────────
+
+/**
+ * Best-effort: apply the system trash/recycle-bin icon to a folder.
+ * Never throws — all errors are silently swallowed.
+ *
+ * @param {string} folderPath  Absolute path to the trash directory
+ */
+export async function applyTrashIcon(folderPath) {
+  try {
+    const s = await stat(folderPath);
+    if (!s.isDirectory()) return;
+
+    switch (process.platform) {
+      case 'darwin':
+        await applyMacIcon(folderPath);
+        break;
+      case 'win32':
+        await applyWindowsIcon(folderPath);
+        break;
+      case 'linux':
+        await applyLinuxIcon(folderPath);
+        break;
+    }
+  } catch {
+    // Best-effort — never propagate
+  }
+}
+
+/**
+ * Re-apply the trash icon only if the icon marker file is missing.
+ * Much cheaper than applyTrashIcon — skips the osascript/attrib call
+ * when the icon is already in place.
+ *
+ * Call this after moving files into trash/ to self-heal the icon
+ * in case the user cleared the directory contents.
+ *
+ * @param {string} folderPath  Absolute path to the trash directory
+ */
+export async function ensureTrashIcon(folderPath) {
+  try {
+    switch (process.platform) {
+      case 'darwin': {
+        // macOS: Icon\r file exists when icon is applied
+        const iconFile = join(folderPath, 'Icon\r');
+        try { await access(iconFile); return; } catch { /* missing — re-apply */ }
+        await applyMacIcon(folderPath);
+        break;
+      }
+      case 'win32': {
+        const iniPath = join(folderPath, 'desktop.ini');
+        try { await access(iniPath); return; } catch { /* missing */ }
+        await applyWindowsIcon(folderPath);
+        break;
+      }
+      case 'linux': {
+        const dirFile = join(folderPath, '.directory');
+        try { await access(dirFile); return; } catch { /* missing */ }
+        await applyLinuxIcon(folderPath);
+        break;
+      }
+    }
+  } catch {
+    // Best-effort — never propagate
+  }
+}
+
+// ── macOS ──────────────────────────────────────────────────────────────
+
+const MACOS_TRASH_ICON =
+  '/System/Library/CoreServices/CoreTypes.bundle/Contents/Resources/TrashIcon.icns';
+
+async function applyMacIcon(folderPath) {
+  await access(MACOS_TRASH_ICON);
+
+  const script =
+    'use framework "AppKit"\n' +
+    `set iconImage to (current application's NSImage's alloc()'s initWithContentsOfFile:"${MACOS_TRASH_ICON}")\n` +
+    `(current application's NSWorkspace's sharedWorkspace()'s setIcon:iconImage forFile:"${folderPath}" options:0)`;
+
+  await execFileAsync('osascript', ['-e', script], { timeout: 5000 });
+}
+
+// ── Windows ────────────────────────────────────────────────────────────
+
+async function applyWindowsIcon(folderPath) {
+  const iniPath = join(folderPath, 'desktop.ini');
+  const iniContent =
+    '[.ShellClassInfo]\r\nIconResource=%SystemRoot%\\System32\\shell32.dll,31\r\n';
+
+  await writeFile(iniPath, iniContent);
+  await execFileAsync('attrib', ['+H', '+S', iniPath], { timeout: 5000 });
+  await execFileAsync('attrib', ['+S', folderPath], { timeout: 5000 });
+}
+
+// ── Linux ──────────────────────────────────────────────────────────────
+
+async function applyLinuxIcon(folderPath) {
+  // KDE Dolphin — .directory file
+  await writeFile(
+    join(folderPath, '.directory'),
+    '[Desktop Entry]\nIcon=user-trash\n',
+  );
+
+  // GNOME Nautilus — gio metadata (may not be available on KDE-only systems)
+  try {
+    await execFileAsync(
+      'gio',
+      ['set', folderPath, 'metadata::custom-icon-name', 'user-trash'],
+      { timeout: 5000 },
+    );
+  } catch {
+    // gio not available — .directory file is enough for KDE
+  }
+}

package/src/lib/toe-stepping.js

@@ -4,6 +4,7 @@ import { readFile } from 'fs/promises';
 import { findBaselineEntry, shouldSkipColumn, normalizeValue, isReference, resolveReferencePath } from './delta.js';
 import { resolveContentValue } from '../commands/clone.js';
 import { computeLineDiff, formatDiff } from './diff.js';
+import { parseMetaFilename } from './filenames.js';
 import { log } from './logger.js';
 
 /**
@@ -358,7 +359,7 @@ export async function checkToeStepping(records, client, baseline, options, appSh
 
     // Conflict detected: server changed since our baseline
     const metaDir = dirname(metaPath);
-    const label = basename(metaPath, '.metadata.json');
+    const label = parseMetaFilename(basename(metaPath))?.naturalBase ?? basename(metaPath, '.metadata.json');
     const diffColumns = await buildRecordDiff(serverEntry, baselineEntry, meta, metaDir);
 
     // If the only server-side changes are metadata columns (_LastUpdated,

package/src/migrations/006-remove-uid-companion-filenames.js

@@ -1,8 +1,8 @@
 import { readdir, readFile, writeFile, rename, access, mkdir } from 'fs/promises';
 import { join, extname, basename, dirname } from 'path';
 import { log } from '../lib/logger.js';
-import { stripUidFromFilename, hasUidInFilename } from '../lib/filenames.js';
-import { ensureTrashIcon } from '../lib/folder-icon.js';
+import { stripUidFromFilename, hasUidInFilename, isMetadataFile } from '../lib/filenames.js';
+import { ensureTrashIcon } from '../lib/tagging.js';
 
 export const description = 'Rename legacy ~UID companion files to natural filenames';
 
@@ -172,7 +172,7 @@ async function findAllMetadataFiles(dir) {
       const full = join(dir, entry.name);
       if (entry.isDirectory()) {
         results.push(...await findAllMetadataFiles(full));
-      } else if (entry.name.endsWith('.metadata.json')) {
+      } else if (isMetadataFile(entry.name)) {
         results.push(full);
       }
     }

package/src/migrations/007-natural-entity-companion-filenames.js

@@ -0,0 +1,165 @@
+import { readdir, readFile, writeFile, rename, access, mkdir } from 'fs/promises';
+import { join, basename, dirname } from 'path';
+import { log } from '../lib/logger.js';
+import { stripUidFromFilename, hasUidInFilename, isMetadataFile } from '../lib/filenames.js';
+import { ensureTrashIcon } from '../lib/tagging.js';
+
+export const description = 'Rename entity/extension companion files from name~uid.Col.ext to name.Col.ext';
+
+/**
+ * Migration 007 — Strip ~UID from entity and extension companion files.
+ *
+ * Previous convention: entity companion files included ~UID in the filename,
+ * e.g. "Add-Asst-Execute-Security~wxl6ivcwfkix3zgantszjg.String16.js".
+ *
+ * New convention: only .metadata.json files carry ~UID. Companion files use
+ * the natural base name, e.g. "Add-Asst-Execute-Security.String16.js".
+ *
+ * For each metadata file in entity directories (lib/extension/, lib/automation/,
+ * lib/data_source/, etc.):
+ *   1. Check each @reference in _contentColumns
+ *   2. If the reference contains ~UID, strip it, rename the file, update the reference
+ *   3. If both natural and legacy files exist, move the legacy to trash/
+ *
+ * Also handles name collisions: if stripping ~UID from two different records
+ * produces the same natural companion name, the second keeps its ~UID reference
+ * to avoid data loss.
+ */
+export default async function run(_options) {
+  const cwd = process.cwd();
+  let totalRenamed = 0;
+  let totalRefsUpdated = 0;
+
+  const metaFiles = await findEntityMetadataFiles(cwd);
+  if (metaFiles.length === 0) return;
+
+  // Track natural names we've claimed, to detect collisions
+  // Key: absolute natural path → true
+  const claimedNaturals = new Set();
+
+  for (const metaPath of metaFiles) {
+    try {
+      const meta = JSON.parse(await readFile(metaPath, 'utf8'));
+      const uid = meta.UID;
+      if (!uid) continue;
+
+      const metaDir = dirname(metaPath);
+      const contentCols = [...(meta._contentColumns || [])];
+      if (meta._mediaFile) contentCols.push('_mediaFile');
+      let metaChanged = false;
+
+      for (const col of contentCols) {
+        const ref = meta[col];
+        if (!ref || !String(ref).startsWith('@')) continue;
+
+        const refName = String(ref).substring(1);
+
+        // Only process references that contain ~UID
+        if (!hasUidInFilename(refName, uid)) continue;
+
+        const naturalName = stripUidFromFilename(refName, uid);
+        const legacyPath = refName.startsWith('/')
+          ? join(cwd, refName)
+          : join(metaDir, refName);
+        const naturalPath = refName.startsWith('/')
+          ? join(cwd, naturalName)
+          : join(metaDir, naturalName);
+
+        // Collision check: if another record already claimed this natural path, skip
+        if (claimedNaturals.has(naturalPath)) {
+          log.dim(`  Skipped ${refName} (natural name collision with another record)`);
+          continue;
+        }
+
+        let legacyExists = false;
+        let naturalExists = false;
+        try { await access(legacyPath); legacyExists = true; } catch { /* missing */ }
+        try { await access(naturalPath); naturalExists = true; } catch { /* missing */ }
+
+        if (legacyExists && !naturalExists) {
+          // Rename legacy → natural
+          try {
+            await rename(legacyPath, naturalPath);
+            log.dim(`  ${refName} → ${naturalName}`);
+            totalRenamed++;
+          } catch { /* rename failed — keep reference as-is */ continue; }
+        } else if (legacyExists && naturalExists) {
+          // Both exist — move orphaned legacy to trash
+          try {
+            const trashDir = join(cwd, 'trash');
+            await mkdir(trashDir, { recursive: true });
+            await rename(legacyPath, join(trashDir, basename(legacyPath)));
+            await ensureTrashIcon(trashDir);
+            log.dim(`  Trashed orphan: ${refName}`);
+            totalRenamed++;
+          } catch { /* non-critical */ }
+        }
+        // else: legacy doesn't exist — just update the reference
+
+        // Update @reference to natural name
+        meta[col] = `@${naturalName}`;
+        metaChanged = true;
+        claimedNaturals.add(naturalPath);
+      }
+
+      // Rewrite metadata if @references were updated
+      if (metaChanged) {
+        try {
+          await writeFile(metaPath, JSON.stringify(meta, null, 2) + '\n');
+          totalRefsUpdated++;
+        } catch { /* non-critical */ }
+      }
+    } catch { /* skip unreadable metadata */ }
+  }
+
+  if (totalRenamed > 0 || totalRefsUpdated > 0) {
+    log.dim(`  Renamed ${totalRenamed} entity companion file(s), updated ${totalRefsUpdated} metadata @reference(s)`);
+  }
+}
+
+/** Directories that hold entity/extension metadata (under lib/) */
+const ENTITY_DIRS = new Set([
+  'extension', 'automation', 'app_version', 'entity', 'entity_column',
+  'entity_column_value', 'integration', 'security', 'security_column',
+  'data_source', 'group', 'site', 'redirect',
+]);
+
+const SKIP = new Set(['.dbo', 'node_modules', 'trash', '.git', '.claude']);
+
+/**
+ * Find all .metadata.json files inside entity directories (lib/<entity>/).
+ * Skips content/media in Bins/ — those are handled by migration 006.
+ */
+async function findEntityMetadataFiles(cwd) {
+  const results = [];
+  const libDir = join(cwd, 'lib');
+
+  let libEntries;
+  try { libEntries = await readdir(libDir, { withFileTypes: true }); } catch { return results; }
+
+  for (const entry of libEntries) {
+    if (!entry.isDirectory()) continue;
+    if (SKIP.has(entry.name)) continue;
+    if (!ENTITY_DIRS.has(entry.name)) continue;
+
+    await scanDir(join(libDir, entry.name), results);
+  }
+
+  return results;
+}
+
+async function scanDir(dir, results) {
+  let entries;
+  try { entries = await readdir(dir, { withFileTypes: true }); } catch { return; }
+
+  for (const entry of entries) {
+    if (SKIP.has(entry.name) || entry.name.startsWith('.')) continue;
+    const full = join(dir, entry.name);
+
+    if (entry.isDirectory()) {
+      await scanDir(full, results);
+    } else if (isMetadataFile(entry.name)) {
+      results.push(full);
+    }
+  }
+}

package/src/migrations/008-metadata-uid-in-suffix.js

@@ -0,0 +1,70 @@
+import { readdir, rename, access } from 'fs/promises';
+import { join, basename, dirname } from 'path';
+import { log } from '../lib/logger.js';
+import { detectLegacyTildeMetadata, buildMetaFilename } from '../lib/filenames.js';
+
+export const description = 'Rename metadata files from name~uid.metadata.json to name.metadata~uid.json';
+
+/**
+ * Migration 008 — Move UID from metadata filename base to suffix.
+ *
+ * Old format: colors~abc123.metadata.json
+ * New format: colors.metadata~abc123.json
+ *
+ * Also handles media metadata: logo~uid.png.metadata.json → logo.png.metadata~uid.json
+ *
+ * Does NOT rename companion files (they are already natural-named).
+ * Updates no @references — @references point to companion files, which are unchanged.
+ */
+export default async function run(_options) {
+  const cwd = process.cwd();
+  let totalRenamed = 0;
+
+  const metaFiles = await findAllLegacyMetadataFiles(cwd);
+  if (metaFiles.length === 0) return;
+
+  for (const metaPath of metaFiles) {
+    const filename = basename(metaPath);
+    const dir = dirname(metaPath);
+
+    // Detect legacy tilde format: name~uid.metadata.json or name~uid.ext.metadata.json
+    const parsed = detectLegacyTildeMetadata(filename);
+    if (!parsed) continue;
+
+    const { naturalBase, uid } = parsed;
+    const newFilename = buildMetaFilename(naturalBase, uid);
+    const newPath = join(dir, newFilename);
+
+    // Skip if target already exists (avoid overwrite)
+    try { await access(newPath); continue; } catch { /* doesn't exist, safe to rename */ }
+
+    try {
+      await rename(metaPath, newPath);
+      log.dim(`  ${filename} → ${newFilename}`);
+      totalRenamed++;
+    } catch { /* non-critical: leave as-is */ }
+  }
+
+  if (totalRenamed > 0) {
+    log.dim(`  Renamed ${totalRenamed} metadata file(s) to new suffix convention`);
+  }
+}
+
+const SKIP = new Set(['.dbo', 'node_modules', 'trash', '.git', '.claude']);
+
+async function findAllLegacyMetadataFiles(dir) {
+  const results = [];
+  try {
+    const entries = await readdir(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      if (SKIP.has(entry.name)) continue;
+      const full = join(dir, entry.name);
+      if (entry.isDirectory()) {
+        results.push(...await findAllLegacyMetadataFiles(full));
+      } else if (detectLegacyTildeMetadata(entry.name)) {
+        results.push(full);
+      }
+    }
+  } catch { /* skip unreadable dirs */ }
+  return results;
+}