@dboio/cli 0.6.14 → 0.8.0

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';
@@ -28,20 +29,26 @@ async function fileExists(path) {
 }
 
 /**
- * Recursively find all .metadata.json files in a directory.
+ * 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.')) {
+      // Output hierarchy files: _output~<name>~<uid>.json and nested entity files
+      results.push(fullPath);
     }
   }
 
@@ -494,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}`;
   }
-  return `"${recordName}" has updates newer than your local version`;
+
+  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${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)
@@ -520,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/input-parser.js

@@ -1,7 +1,8 @@
 import { readFile } from 'fs/promises';
 import { log } from './logger.js';
-import { loadUserInfo } from './config.js';
+import { loadUserInfo, loadTicketSuggestionOutput } from './config.js';
 import { buildTicketExpression, setGlobalTicket, setRecordTicket, getGlobalTicket, getRecordTicket } from './ticketing.js';
+import { DboClient } from './client.js';
 
 /**
  * Parse DBO input syntax and build form data.
@@ -84,6 +85,7 @@ function findValueAtSign(expr) {
 }
 
 // Patterns that indicate a missing user identity in the server response
+// Note: the user entity only has an ID (never a UID), so all patterns resolve to _OverrideUserID.
 const USER_ID_PATTERNS = [
   'LoggedInUser_UID',
   'LoggedInUserID',
@@ -101,7 +103,7 @@ const USER_ID_PATTERNS = [
  * - repo_mismatch → repository mismatch recovery (6 options)
  * - ticket_lookup_required_error → prompts for Ticket ID (legacy)
  * - LoggedInUser_UID, LoggedInUserID, CurrentUserID, UserID not found
- *   → prompts for User ID or UID (session not authenticated)
+ *   → prompts for User ID (session not authenticated)
  *
  * Returns an object with retry information, or null if no recoverable errors found.
  *
@@ -109,9 +111,9 @@ const USER_ID_PATTERNS = [
  *   { retryParams, ticketExpressions, skipRecord, skipAll }
  *
  * Return shape for legacy/user errors (backward compatible):
- *   { _OverrideTicketID, _OverrideUserUID, _OverrideUserID, ... }
+ *   { _OverrideTicketID, _OverrideUserID, ... }
  */
-export async function checkSubmitErrors(result) {
+export async function checkSubmitErrors(result, context = {}) {
   const messages = result.messages || result.data?.Messages || [];
   const allText = messages.filter(m => typeof m === 'string').join(' ');
 
@@ -121,7 +123,7 @@ export async function checkSubmitErrors(result) {
   const hasRepoMismatch = allText.includes('repo_mismatch');
 
   if (hasTicketError) {
-    return await handleTicketError(allText);
+    return await handleTicketError(allText, context);
   }
 
   if (hasRepoMismatch) {
@@ -132,7 +134,6 @@ export async function checkSubmitErrors(result) {
   const needsTicket = allText.includes('ticket_lookup_required_error');
   const matchedUserPattern = USER_ID_PATTERNS.find(p => allText.includes(p));
   const needsUser = !!matchedUserPattern;
-  const needsUserUid = matchedUserPattern && matchedUserPattern.includes('UID');
 
   if (!needsTicket && !needsUser) return null;
 
@@ -142,14 +143,9 @@ export async function checkSubmitErrors(result) {
   if (!process.stdin.isTTY) {
     if (needsUser) {
       const stored = await loadUserInfo();
-      const storedValue = needsUserUid ? stored.userUid : (stored.userId || stored.userUid);
-      if (storedValue) {
-        log.info(`Using stored user ${needsUserUid ? 'UID' : 'ID'}: ${storedValue} (non-interactive mode)`);
-        if (needsUserUid) {
-          retryParams['_OverrideUserUID'] = storedValue;
-        } else {
-          retryParams['_OverrideUserID'] = storedValue;
-        }
+      if (stored.userId) {
+        log.info(`Using stored user ID: ${stored.userId} (non-interactive mode)`);
+        retryParams['_OverrideUserID'] = stored.userId;
       } else {
         log.error(`This operation requires an authenticated user (${matchedUserPattern}).`);
         log.dim('  Run "dbo login" first, or use an interactive terminal.');
@@ -167,41 +163,36 @@ export async function checkSubmitErrors(result) {
   const prompts = [];
 
   if (needsUser) {
-    const idType = needsUserUid ? 'UID' : 'ID';
     log.warn(`This operation requires an authenticated user (${matchedUserPattern}).`);
     log.dim('  Your session may have expired, or you may not be logged in.');
     log.dim('  You can log in with "dbo login" to avoid this prompt in the future.');
 
     const stored = await loadUserInfo();
-    const storedValue = needsUserUid ? stored.userUid : (stored.userId || stored.userUid);
-    const storedLabel = needsUserUid
-      ? (stored.userUid ? `UID: ${stored.userUid}` : null)
-      : (stored.userId ? `ID: ${stored.userId}` : (stored.userUid ? `UID: ${stored.userUid}` : null));
 
-    if (storedValue) {
-      log.dim(`  Stored session user ${storedLabel}`);
+    if (stored.userId) {
+      log.dim(`  Stored session user ID: ${stored.userId}`);
       prompts.push({
         type: 'list',
         name: 'userChoice',
-        message: `User ${idType} Required:`,
+        message: 'User ID Required:',
         choices: [
-          { name: `Use session user (${storedLabel})`, value: storedValue },
-          { name: `Enter a different User ${idType}`, value: '_custom' },
+          { name: `Use session user (ID: ${stored.userId})`, value: stored.userId },
+          { name: 'Enter a different User ID', value: '_custom' },
         ],
       });
       prompts.push({
         type: 'input',
         name: 'customUserValue',
-        message: `Custom User ${idType}:`,
+        message: 'Custom User ID:',
         when: (answers) => answers.userChoice === '_custom',
-        validate: v => v.trim() ? true : `User ${idType} is required`,
+        validate: v => v.trim() ? true : 'User ID is required',
       });
     } else {
       prompts.push({
         type: 'input',
         name: 'userValue',
-        message: `User ${idType} Required:`,
-        validate: v => v.trim() ? true : `User ${idType} is required`,
+        message: 'User ID Required:',
+        validate: v => v.trim() ? true : 'User ID is required',
       });
     }
   }
@@ -224,11 +215,7 @@ export async function checkSubmitErrors(result) {
   const userValue = answers.userValue
     || (answers.userChoice === '_custom' ? answers.customUserValue : answers.userChoice);
   if (userValue) {
-    if (needsUserUid) {
-      retryParams['_OverrideUserUID'] = userValue.trim();
-    } else {
-      retryParams['_OverrideUserID'] = userValue.trim();
-    }
+    retryParams['_OverrideUserID'] = userValue.trim();
   }
 
   return retryParams;
@@ -238,7 +225,7 @@ export async function checkSubmitErrors(result) {
  * Handle ticket_error: Record update requires a Ticket ID but none was provided.
  * Prompts the user with 4 recovery options.
  */
-async function handleTicketError(allText) {
+async function handleTicketError(allText, context = {}) {
   // Try to extract record details from error text
   const entityMatch = allText.match(/entity:(\w+)/);
   const rowIdMatch = allText.match(/RowID:(\d+)/);
@@ -262,9 +249,63 @@ async function handleTicketError(allText) {
     return null;
   }
 
+  // Fetch ticket suggestions if configured
+  let suggestionChoices = [];
+  const ticketSuggestionUid = await loadTicketSuggestionOutput();
+  const rowUid = context.rowUid || uid || null;
+
+  if (ticketSuggestionUid && rowUid) {
+    try {
+      const client = new DboClient();
+      const suggestResult = await client.get(`/api/output/${ticketSuggestionUid}`, {
+        '_limit': '5',
+        '_rowcount': 'false',
+        '_template': 'json_raw',
+        '_filter@AssetUID': rowUid,
+      });
+      const rows = suggestResult.payload || suggestResult.data;
+      const rowArray = Array.isArray(rows) ? rows : (rows?.Rows || rows?.rows || []);
+      for (let i = 0; i < rowArray.length; i++) {
+        const row = rowArray[i];
+        const ticketId = row.TicketID || row.ticket_id;
+        const title = row.Title || row.Name || '';
+        const shortName = row.ShortName || row.short_name || '';
+        if (ticketId) {
+          const label = `${i + 1} (${ticketId}): ${title}${shortName ? ` [${shortName}]` : ''}`;
+          suggestionChoices.push({ name: label, value: String(ticketId) });
+        }
+      }
+    } catch (err) {
+      log.dim(`  (Could not fetch ticket suggestions: ${err.message})`);
+    }
+  }
+
   log.warn('This record update requires a Ticket ID.');
 
   const inquirer = (await import('inquirer')).default;
+
+  // Build the ticket ID prompt — list with suggestions or manual input
+  const needsTicket = (a) => a.ticketAction === 'apply_one' || a.ticketAction === 'apply_all';
+
+  const ticketIdPrompt = suggestionChoices.length > 0
+    ? {
+        type: 'list',
+        name: 'ticketId',
+        message: 'Select a Ticket ID:',
+        choices: [
+          ...suggestionChoices,
+          { name: 'Enter a Ticket ID manually\u2026', value: '_manual' },
+        ],
+        when: needsTicket,
+      }
+    : {
+        type: 'input',
+        name: 'ticketId',
+        message: 'Enter Ticket ID:',
+        when: needsTicket,
+        validate: v => v.trim() ? true : 'Ticket ID is required',
+      };
+
   const answers = await inquirer.prompt([
     {
       type: 'list',
@@ -277,11 +318,12 @@ async function handleTicketError(allText) {
         { name: 'Skip all updates that require a Ticket ID', value: 'skip_all' },
       ],
     },
+    ticketIdPrompt,
     {
       type: 'input',
-      name: 'ticketId',
-      message: 'Enter Ticket ID:',
-      when: (a) => a.ticketAction === 'apply_one' || a.ticketAction === 'apply_all',
+      name: 'ticketIdManual',
+      message: 'Ticket ID:',
+      when: (a) => needsTicket(a) && a.ticketId === '_manual',
       validate: v => v.trim() ? true : 'Ticket ID is required',
     },
   ]);
@@ -293,7 +335,14 @@ async function handleTicketError(allText) {
     return { skipAll: true };
   }
 
-  const ticketId = answers.ticketId.trim();
+  const ticketId = (answers.ticketIdManual?.trim()) ||
+    (answers.ticketId !== '_manual' ? answers.ticketId?.trim() : null);
+
+  if (!ticketId) {
+    log.error('  No Ticket ID provided. Skipping record.');
+    return { skipRecord: true };
+  }
+
   const ticketExpressions = [];
 
   if (entity && rowId) {

package/src/lib/structure.js

@@ -19,6 +19,22 @@ export const DEFAULT_PROJECT_DIRS = [
   'Integrations',
 ];
 
+/** Map from physical output table names → documentation/display names */
+export const OUTPUT_ENTITY_MAP = {
+  output: 'output',
+  output_value: 'column',
+  output_value_filter: 'filter',
+  output_value_entity_column_rel: 'join',
+};
+
+/** All output hierarchy entity types (physical table names) */
+export const OUTPUT_HIERARCHY_ENTITIES = [
+  'output',
+  'output_value',
+  'output_value_filter',
+  'output_value_entity_column_rel',
+];
+
 /** Map from server entity key → local project directory name */
 export const ENTITY_DIR_MAP = {
   extension:    'Extensions',
@@ -163,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]}`;
+}