@dboio/cli 0.7.2 → 0.8.0

package/src/commands/init.js

@@ -4,6 +4,7 @@ import { join } from 'path';
 import { isInitialized, hasLegacyConfig, readLegacyConfig, initConfig, saveCredentials, ensureGitignore, saveTransactionKeyPreset, saveTicketSuggestionOutput } from '../lib/config.js';
 import { installOrUpdateClaudeCommands } from './install.js';
 import { scaffoldProjectDirs, logScaffoldResult } from '../lib/scaffold.js';
+import { createDboignore, loadIgnore } from '../lib/ignore.js';
 import { log } from '../lib/logger.js';
 import { checkDomainChange, writeAppJsonDomain } from '../lib/domain-guard.js';
 
@@ -19,10 +20,22 @@ export const initCommand = new Command('init')
   .option('-g, --global', 'Install Claude commands to user home directory (~/.claude/commands/)')
   .option('--local', 'Install Claude commands to project directory (.claude/commands/)')
   .option('--scaffold', 'Create standard project directories (App Versions, Automations, Bins, …)')
+  .option('--dboignore', 'Create or reset .dboignore to defaults (use with --force to overwrite)')
   .action(async (options) => {
     // Merge --yes into nonInteractive
     if (options.yes) options.nonInteractive = true;
     try {
+      // --dboignore: standalone operation, works regardless of init state
+      if (options.dboignore) {
+        const created = await createDboignore(process.cwd(), { force: options.force });
+        if (created) {
+          log.success(options.force ? 'Reset .dboignore to default patterns' : 'Created .dboignore with default patterns');
+        } else {
+          log.warn('.dboignore already exists. Use --force to overwrite with defaults.');
+        }
+        return;
+      }
+
       if (await isInitialized() && !options.force) {
         if (options.scaffold) {
           const result = await scaffoldProjectDirs();
@@ -86,6 +99,9 @@ export const initCommand = new Command('init')
       // Ensure sensitive files are gitignored
       await ensureGitignore(['.dbo/credentials.json', '.dbo/cookies.txt', '.dbo/config.local.json', '.dbo/ticketing.local.json']);
 
+      const createdIgnore = await createDboignore();
+      if (createdIgnore) log.dim('  Created .dboignore');
+
       log.success(`Initialized .dbo/ for ${domain}`);
       log.dim('  Run "dbo login" to authenticate.');
 
@@ -130,9 +146,9 @@ export const initCommand = new Command('init')
       let shouldScaffold = options.scaffold;
 
       if (!shouldScaffold && !options.nonInteractive) {
-        const entries = await readdir(process.cwd());
-        const IGNORED = new Set(['.dbo', '.claude', '.idea', '.vscode']);
-        const isEmpty = entries.every(e => IGNORED.has(e));
+        const entries = await readdir(process.cwd(), { withFileTypes: true });
+        const ig = await loadIgnore();
+        const isEmpty = entries.every(e => ig.ignores(e.isDirectory() ? e.name + '/' : e.name));
 
         const inquirer = (await import('inquirer')).default;
         const { doScaffold } = await inquirer.prompt([{

package/src/commands/install.js

@@ -235,7 +235,7 @@ async function promptForScope(pluginName) {
 
 /**
  * Resolve the scope for a plugin based on flags and stored preferences.
- * Priority: explicit flag > stored preference > prompt.
+ * Priority: explicit flag > stored preference > existing installation > prompt.
  * @param {string} pluginName - Plugin name without .md
  * @param {object} options - Command options with global/local flags
  * @returns {Promise<'project' | 'global'>}
@@ -247,6 +247,15 @@ async function resolvePluginScope(pluginName, options) {
   const storedScope = await getPluginScope(pluginName);
   if (storedScope) return storedScope;
 
+  // Infer from existing installation — avoids re-prompting on re-installs
+  // (e.g. postinstall after npm install when .dbo/ isn't in cwd)
+  const registry = await readPluginRegistry();
+  const key = `${pluginName}@${PLUGIN_MARKETPLACE}`;
+  if (registry.plugins[key]) return 'global';
+
+  const projectPluginDir = join(process.cwd(), '.claude', 'plugins', pluginName);
+  if (existsSync(projectPluginDir)) return 'project';
+
   return await promptForScope(pluginName);
 }
 

package/src/commands/push.js

@@ -13,6 +13,18 @@ import { resolveTransactionKey } from '../lib/transaction-key.js';
 import { setFileTimestamps } from '../lib/timestamps.js';
 import { findMetadataFiles } from '../lib/diff.js';
 import { detectChangedColumns, findBaselineEntry } from '../lib/delta.js';
+
+/**
+ * Resolve an @reference file path to an absolute filesystem path.
+ * "@filename.ext"         → relative to the metadata file's directory (existing behaviour)
+ * "@/Documentation/..."  → relative to project root (process.cwd())
+ */
+function resolveAtReference(refFile, metaDir) {
+  if (refFile.startsWith('/')) {
+    return join(process.cwd(), refFile);
+  }
+  return join(metaDir, refFile);
+}
 import { ENTITY_DEPENDENCIES } from '../lib/dependencies.js';
 
 export const pushCommand = new Command('push')
@@ -214,7 +226,7 @@ async function pushDirectory(dirPath, client, options, modifyKey = null, transac
     for (const col of contentCols) {
       const ref = meta[col];
       if (ref && ref.startsWith('@')) {
-        const refPath = join(dirname(metaPath), ref.substring(1));
+        const refPath = resolveAtReference(ref.substring(1), dirname(metaPath));
         try {
           await stat(refPath);
         } catch {
@@ -378,7 +390,7 @@ async function pushFromMetadata(meta, metaPath, client, options, changedColumns
     if (strValue.startsWith('@')) {
       // @filename reference — resolve to actual file path
       const refFile = strValue.substring(1);
-      const refPath = join(metaDir, refFile);
+      const refPath = resolveAtReference(refFile, metaDir);
       dataExprs.push(`${rowKeyPrefix}:${rowKeyValue};column:${entity}.${key}@${refPath}`);
     } else {
       dataExprs.push(`${rowKeyPrefix}:${rowKeyValue};column:${entity}.${key}=${strValue}`);
@@ -647,7 +659,7 @@ async function updateBaselineAfterPush(baseline, successfulPushes) {
       if (strValue.startsWith('@')) {
         try {
           const refFile = strValue.substring(1);
-          const refPath = join(dirname(metaPath), refFile);
+          const refPath = resolveAtReference(refFile, dirname(metaPath));
           const fileContent = await readFile(refPath, 'utf8');
           baselineEntry[col] = fileContent;
           modified = true;

package/src/lib/config.js

@@ -724,3 +724,104 @@ export async function loadAppJsonBaseline() {
 export async function saveAppJsonBaseline(data) {
   await writeFile(baselinePath(), JSON.stringify(data, null, 2) + '\n');
 }
+
+/**
+ * Save the clone source to .dbo/config.json.
+ * "default" = fetched from server via AppShortName.
+ * Any other value = explicit local file path or URL provided by the user.
+ */
+export async function saveCloneSource(source) {
+  await mkdir(dboDir(), { recursive: true });
+  let existing = {};
+  try {
+    existing = JSON.parse(await readFile(configPath(), 'utf8'));
+  } catch { /* no existing config */ }
+  existing.cloneSource = source;
+  await writeFile(configPath(), JSON.stringify(existing, null, 2) + '\n');
+}
+
+/**
+ * Load the stored clone source from .dbo/config.json.
+ * Returns null if not set.
+ */
+export async function loadCloneSource() {
+  try {
+    const raw = await readFile(configPath(), 'utf8');
+    const config = JSON.parse(raw);
+    return config.cloneSource || null;
+  } catch {
+    return null;
+  }
+}
+
+// ─── Descriptor-level Extension Preferences ───────────────────────────────
+
+/** Save filename column preference for a specific Descriptor value.
+ *  Config key: "Extension_<descriptor>_FilenameCol"
+ */
+export async function saveDescriptorFilenamePreference(descriptor, columnName) {
+  await mkdir(dboDir(), { recursive: true });
+  let cfg = {};
+  try { cfg = JSON.parse(await readFile(configPath(), 'utf8')); } catch {}
+  if (columnName === null) {
+    delete cfg[`Extension_${descriptor}_FilenameCol`];
+  } else {
+    cfg[`Extension_${descriptor}_FilenameCol`] = columnName;
+  }
+  await writeFile(configPath(), JSON.stringify(cfg, null, 2) + '\n');
+}
+
+/** Load filename column preference for a specific Descriptor value. Returns null if not set. */
+export async function loadDescriptorFilenamePreference(descriptor) {
+  try {
+    const cfg = JSON.parse(await readFile(configPath(), 'utf8'));
+    return cfg[`Extension_${descriptor}_FilenameCol`] || null;
+  } catch { return null; }
+}
+
+/** Save content extraction preferences for a specific Descriptor value.
+ *  Config key: "Extension_<descriptor>_ContentExtractions"
+ *  Value: { "ColName": "css", "Other": false, ... }
+ */
+export async function saveDescriptorContentExtractions(descriptor, extractions) {
+  await mkdir(dboDir(), { recursive: true });
+  let cfg = {};
+  try { cfg = JSON.parse(await readFile(configPath(), 'utf8')); } catch {}
+  if (extractions === null) {
+    delete cfg[`Extension_${descriptor}_ContentExtractions`];
+  } else {
+    cfg[`Extension_${descriptor}_ContentExtractions`] = extractions;
+  }
+  await writeFile(configPath(), JSON.stringify(cfg, null, 2) + '\n');
+}
+
+/** Load content extraction preferences for a specific Descriptor value. Returns null if not saved. */
+export async function loadDescriptorContentExtractions(descriptor) {
+  try {
+    const cfg = JSON.parse(await readFile(configPath(), 'utf8'));
+    return cfg[`Extension_${descriptor}_ContentExtractions`] || null;
+  } catch { return null; }
+}
+
+/** Save ExtensionDocumentationMDPlacement preference.
+ *  @param {'inline'|'root'|null} placement  — null clears the key
+ */
+export async function saveExtensionDocumentationMDPlacement(placement) {
+  await mkdir(dboDir(), { recursive: true });
+  let cfg = {};
+  try { cfg = JSON.parse(await readFile(configPath(), 'utf8')); } catch {}
+  if (placement === null) {
+    delete cfg.ExtensionDocumentationMDPlacement;
+  } else {
+    cfg.ExtensionDocumentationMDPlacement = placement;
+  }
+  await writeFile(configPath(), JSON.stringify(cfg, null, 2) + '\n');
+}
+
+/** Load ExtensionDocumentationMDPlacement preference. Returns 'inline', 'root', or null. */
+export async function loadExtensionDocumentationMDPlacement() {
+  try {
+    const cfg = JSON.parse(await readFile(configPath(), 'utf8'));
+    return cfg.ExtensionDocumentationMDPlacement || null;
+  } catch { return null; }
+}

package/src/lib/diff.js

@@ -1,6 +1,7 @@
 import chalk from 'chalk';
 import { readFile, writeFile, readdir, access, stat } from 'fs/promises';
-import { join, dirname, basename, extname } from 'path';
+import { join, dirname, basename, extname, relative } from 'path';
+import { loadIgnore } from './ignore.js';
 import { parseServerDate, setFileTimestamps } from './timestamps.js';
 import { loadConfig, loadUserInfo } from './config.js';
 import { log } from './logger.js';
@@ -31,16 +32,18 @@ async function fileExists(path) {
  * Recursively find all metadata files in a directory.
  * Includes .metadata.json files and output hierarchy files (_output~*.json).
  */
-export async function findMetadataFiles(dir) {
+export async function findMetadataFiles(dir, ig) {
+  if (!ig) ig = await loadIgnore();
+
   const results = [];
   const entries = await readdir(dir, { withFileTypes: true });
 
   for (const entry of entries) {
     const fullPath = join(dir, entry.name);
     if (entry.isDirectory()) {
-      // Skip hidden dirs, node_modules, .dbo
-      if (entry.name.startsWith('.') || entry.name === 'node_modules') continue;
-      results.push(...await findMetadataFiles(fullPath));
+      const relPath = relative(process.cwd(), fullPath).replace(/\\/g, '/');
+      if (ig.ignores(relPath + '/') || ig.ignores(relPath)) continue;
+      results.push(...await findMetadataFiles(fullPath, ig));
     } else if (entry.name.endsWith('.metadata.json')) {
       results.push(fullPath);
     } else if (entry.name.startsWith('_output~') && entry.name.endsWith('.json') && !entry.name.includes('.CustomSQL.')) {
@@ -498,21 +501,67 @@ export async function applyServerChanges(diffResult, acceptedFields, config) {
   }
 }
 
+// ─── Diffability ─────────────────────────────────────────────────────────────
+
+// Extensions that can be meaningfully text-diffed
+const DIFFABLE_EXTENSIONS = new Set([
+  'js', 'mjs', 'cjs', 'ts', 'tsx', 'jsx',
+  'css', 'scss', 'less', 'sass',
+  'html', 'htm', 'xhtml',
+  'sql', 'xml', 'json', 'yaml', 'yml', 'toml', 'ini', 'env',
+  'md', 'txt', 'csv', 'tsv',
+  'sh', 'bash', 'zsh', 'ps1', 'bat', 'cmd',
+  'py', 'rb', 'php', 'java', 'c', 'cpp', 'h', 'cs', 'go', 'rs', 'swift', 'kt',
+  'vue', 'svelte', 'astro',
+  'graphql', 'gql', 'proto',
+  'htaccess', 'gitignore', 'dockerignore', 'editorconfig',
+]);
+
+/**
+ * Returns true if the file extension suggests it can be meaningfully text-diffed.
+ * Images, videos, audio, fonts, archives, and other binary formats return false.
+ */
+export function isDiffable(ext) {
+  if (!ext) return false;
+  return DIFFABLE_EXTENSIONS.has(String(ext).toLowerCase().replace(/^\./, ''));
+}
+
 // ─── Change Detection Prompt ────────────────────────────────────────────────
 
 /**
  * Build the change detection message describing who changed the file.
  */
-function buildChangeMessage(recordName, serverRecord, config) {
+function buildChangeMessage(recordName, serverRecord, config, options = {}) {
   const userInfo = loadUserInfoSync();
   const updatedBy = serverRecord._LastUpdatedUserID;
 
+  let who;
   if (updatedBy && userInfo && String(updatedBy) === String(userInfo.userId)) {
-    return `"${recordName}" was updated on server by you (from another session)`;
+    who = 'you (from another session)';
   } else if (updatedBy) {
-    return `"${recordName}" was updated on server by user ${updatedBy}`;
+    who = `user ${updatedBy}`;
+  }
+
+  const datePart = formatDateHint(options.serverDate, options.localDate);
+
+  if (who) {
+    return `"${recordName}" was updated on server by ${who}${datePart}`;
   }
-  return `"${recordName}" has updates newer than your local version`;
+  return `"${recordName}" has updates newer than your local version${datePart}`;
+}
+
+/**
+ * Format a "(server: X, local: Y)" hint when date info is available.
+ */
+function formatDateHint(serverDate, localDate) {
+  const fmt = (d) => d instanceof Date && !isNaN(d)
+    ? d.toLocaleString('en-US', { month: 'short', day: 'numeric', hour: '2-digit', minute: '2-digit' })
+    : null;
+  const s = fmt(serverDate);
+  const l = fmt(localDate);
+  if (s && l) return `\n  server: ${s}  |  local: ${l}`;
+  if (s) return `\n  server: ${s}`;
+  return '';
 }
 
 // Sync version for message building (cached)
@@ -524,31 +573,36 @@ function loadUserInfoSync() {
 /**
  * Prompt the user when a record has changed.
  * options.localIsNewer: when true, the local file has modifications not on server.
+ * options.diffable: when false, omit the "Compare differences" choice.
+ * options.serverDate / options.localDate: Date objects shown as hints.
  * Returns: 'overwrite' | 'compare' | 'skip' | 'overwrite_all' | 'skip_all'
  */
 export async function promptChangeDetection(recordName, serverRecord, config, options = {}) {
   const localIsNewer = options.localIsNewer || false;
+  const diffable = options.diffable !== false; // default true for text records
 
   // Cache user info for message building
   _cachedUserInfo = await loadUserInfo();
 
+  const datePart = formatDateHint(options.serverDate, options.localDate);
+
   const message = localIsNewer
-    ? `"${recordName}" has local changes not on the server`
-    : buildChangeMessage(recordName, serverRecord, config);
+    ? `"${recordName}" has local changes not on the server${datePart}`
+    : buildChangeMessage(recordName, serverRecord, config, options);
 
   const inquirer = (await import('inquirer')).default;
 
   const choices = localIsNewer
     ? [
         { name: 'Restore server version (discard local changes)', value: 'overwrite' },
-        { name: 'Compare differences (dbo diff)', value: 'compare' },
+        ...(diffable ? [{ name: 'Compare differences (dbo diff)', value: 'compare' }] : []),
         { name: 'Keep local changes', value: 'skip' },
         { name: 'Restore all to server version', value: 'overwrite_all' },
         { name: 'Keep all local changes', value: 'skip_all' },
       ]
     : [
         { name: 'Overwrite local file with server version', value: 'overwrite' },
-        { name: 'Compare differences (dbo diff)', value: 'compare' },
+        ...(diffable ? [{ name: 'Compare differences (dbo diff)', value: 'compare' }] : []),
         { name: 'Skip this file', value: 'skip' },
         { name: 'Overwrite this and all remaining changed files', value: 'overwrite_all' },
         { name: 'Skip all remaining changed files', value: 'skip_all' },

package/src/lib/ignore.js

@@ -0,0 +1,145 @@
+import { readFile, writeFile, access } from 'fs/promises';
+import { join } from 'path';
+import ignore from 'ignore';
+
+const DBOIGNORE_FILE = '.dboignore';
+
+/**
+ * Default .dboignore file content — shipped with `dbo init`.
+ * Gitignore-style syntax. Users can edit after creation.
+ */
+const DEFAULT_FILE_CONTENT = `# DBO CLI ignore patterns
+# (gitignore-style syntax — works like .gitignore)
+
+# DBO internal
+.dbo/
+.dboignore
+*.dboio.json
+app.json
+.app.json
+dbo.deploy.json
+
+# Editor / IDE
+.idea/
+.vscode/
+*.codekit3
+
+# Version control
+.git/
+.svn/
+.hg/
+.gitignore
+
+# AI / tooling
+.claude/
+.mcp.json
+
+# Node
+node_modules/
+package.json
+package-lock.json
+
+# Documentation (repo scaffolding)
+SETUP.md
+README.md
+`;
+
+// Session-level cache (one process = one command invocation)
+let _cachedIg = null;
+let _cachedRoot = null;
+
+/**
+ * Return the full default .dboignore file content (with comments).
+ */
+export function getDefaultFileContent() {
+  return DEFAULT_FILE_CONTENT;
+}
+
+/**
+ * Extract just the active pattern lines from DEFAULT_FILE_CONTENT.
+ */
+function getDefaultPatternLines() {
+  return DEFAULT_FILE_CONTENT
+    .split('\n')
+    .filter(l => l && !l.startsWith('#'));
+}
+
+/**
+ * Load and return a cached `ignore` instance for the current project.
+ * Reads .dboignore if it exists; falls back to built-in defaults.
+ *
+ * @param {string} [cwd=process.cwd()] - Project root
+ * @returns {Promise<import('ignore').Ignore>}
+ */
+export async function loadIgnore(cwd = process.cwd()) {
+  if (_cachedIg && _cachedRoot === cwd) return _cachedIg;
+
+  const ig = ignore();
+  const filePath = join(cwd, DBOIGNORE_FILE);
+
+  try {
+    const content = await readFile(filePath, 'utf8');
+    ig.add(content);
+  } catch {
+    // No .dboignore — use built-in defaults
+    ig.add(getDefaultPatternLines());
+  }
+
+  _cachedIg = ig;
+  _cachedRoot = cwd;
+  return ig;
+}
+
+/**
+ * Check whether a relative path should be ignored.
+ *
+ * @param {string} relativePath - Path relative to project root (forward slashes)
+ * @param {string} [cwd=process.cwd()]
+ * @returns {Promise<boolean>}
+ */
+export async function isIgnored(relativePath, cwd = process.cwd()) {
+  const ig = await loadIgnore(cwd);
+  return ig.ignores(relativePath);
+}
+
+/**
+ * Filter an array of relative paths, returning only those NOT ignored.
+ *
+ * @param {string[]} paths - Relative paths
+ * @param {string} [cwd=process.cwd()]
+ * @returns {Promise<string[]>}
+ */
+export async function filterIgnored(paths, cwd = process.cwd()) {
+  const ig = await loadIgnore(cwd);
+  return ig.filter(paths);
+}
+
+/**
+ * Create a .dboignore file with default patterns.
+ * Does nothing if the file already exists (unless force=true).
+ *
+ * @param {string} [cwd=process.cwd()]
+ * @param {{ force?: boolean }} [opts]
+ * @returns {Promise<boolean>} true if file was created/overwritten
+ */
+export async function createDboignore(cwd = process.cwd(), { force = false } = {}) {
+  const filePath = join(cwd, DBOIGNORE_FILE);
+  if (!force) {
+    try {
+      await access(filePath);
+      return false; // already exists
+    } catch { /* doesn't exist — create it */ }
+  }
+  await writeFile(filePath, DEFAULT_FILE_CONTENT);
+  _cachedIg = null;
+  _cachedRoot = null;
+  return true;
+}
+
+/**
+ * Reset the session cache. Call between tests that change cwd or .dboignore.
+ */
+export function resetCache() {
+  _cachedIg = null;
+  _cachedRoot = null;
+}

package/src/lib/structure.js

@@ -179,3 +179,117 @@ export function findBinByPath(dirPath, structure) {
 export function findChildBins(binId, structure) {
   return Object.values(structure).filter(e => e.parentBinID === binId);
 }
+
+// ─── Extension Descriptor Sub-directory Support ───────────────────────────
+
+/** Root for all extension descriptor-grouped sub-directories */
+export const EXTENSION_DESCRIPTORS_DIR = 'Extensions';
+
+/** Extensions that cannot be mapped go here (always created, even if empty) */
+export const EXTENSION_UNSUPPORTED_DIR = 'Extensions/Unsupported';
+
+/** Root-level documentation directory for alternate placement */
+export const DOCUMENTATION_DIR = 'Documentation';
+
+/**
+ * Build a descriptor→dirName mapping from a flat array of extension records.
+ * Scans records where Descriptor === "descriptor_definition".
+ * Maps String1 (key) → Name (directory name).
+ *
+ * Rules:
+ *   - Null/empty String1: skip, push to warnings[]
+ *   - Null/empty Name: use String1 as the directory name
+ *   - Duplicate String1: last one wins, push to warnings[]
+ *
+ * @param {Object[]} extensionRecords
+ * @returns {{ mapping: Object<string,string>, warnings: string[] }}
+ */
+export function buildDescriptorMapping(extensionRecords) {
+  const mapping = {};
+  const warnings = [];
+
+  for (const rec of extensionRecords) {
+    if (rec.Descriptor !== 'descriptor_definition') continue;
+
+    const rawKey = rec.String1;
+    // String1 may be a base64-encoded object from the server API
+    const key = resolveFieldValue(rawKey);
+    if (!key || String(key).trim() === '') {
+      warnings.push(`descriptor_definition UID=${rec.UID} has null/empty String1 — skipped`);
+      continue;
+    }
+    const keyStr = String(key).trim();
+
+    const rawName = rec.Name;
+    const nameStr = resolveFieldValue(rawName);
+    const dirName = (nameStr && String(nameStr).trim())
+      ? String(nameStr).trim()
+      : keyStr;
+
+    if (keyStr in mapping) {
+      warnings.push(`Duplicate descriptor_definition key "${keyStr}" — overwriting with UID=${rec.UID}`);
+    }
+    mapping[keyStr] = dirName;
+  }
+
+  return { mapping, warnings };
+}
+
+/**
+ * Resolve a field value that may be a base64-encoded object from the server API.
+ * Server returns large text as: { bytes: N, value: "base64string", encoding: "base64" }
+ */
+function resolveFieldValue(value) {
+  if (value && typeof value === 'object' && !Array.isArray(value)
+      && value.encoding === 'base64' && typeof value.value === 'string') {
+    return Buffer.from(value.value, 'base64').toString('utf8');
+  }
+  return value;
+}
+
+/**
+ * Persist descriptorMapping and extensionDescriptorDirs into .dbo/structure.json.
+ * Extends the existing structure object (already contains bin entries).
+ *
+ * @param {Object} structure  - Current structure from loadStructureFile()
+ * @param {Object} mapping    - descriptor key → dir name
+ */
+export async function saveDescriptorMapping(structure, mapping) {
+  const descriptorDirs = [
+    EXTENSION_UNSUPPORTED_DIR,
+    ...Object.values(mapping).map(name => `${EXTENSION_DESCRIPTORS_DIR}/${name}`),
+  ];
+  const uniqueDirs = [...new Set(descriptorDirs)];
+
+  const extended = {
+    ...structure,
+    descriptorMapping: mapping,
+    extensionDescriptorDirs: uniqueDirs,
+  };
+  await saveStructureFile(extended);
+}
+
+/**
+ * Load descriptorMapping from .dbo/structure.json.
+ * Returns {} if not yet persisted.
+ */
+export async function loadDescriptorMapping() {
+  const structure = await loadStructureFile();
+  return structure.descriptorMapping || {};
+}
+
+/**
+ * Resolve the sub-directory path for a single extension record.
+ * Returns "Extensions/<MappedName>" or "Extensions/Unsupported".
+ *
+ * @param {Object} record   - Extension record with a .Descriptor field
+ * @param {Object} mapping  - descriptor key → dir name (from buildDescriptorMapping)
+ * @returns {string}
+ */
+export function resolveExtensionSubDir(record, mapping) {
+  const descriptor = record.Descriptor;
+  if (!descriptor || !mapping[descriptor]) {
+    return EXTENSION_UNSUPPORTED_DIR;
+  }
+  return `${EXTENSION_DESCRIPTORS_DIR}/${mapping[descriptor]}`;
+}