@dboio/cli 0.9.8 → 0.11.1

package/src/lib/diff.js

@@ -3,9 +3,120 @@ import { readFile, writeFile, readdir, access, stat } from 'fs/promises';
 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 { loadConfig, loadUserInfo, loadAppJsonBaseline } from './config.js';
+import { findBaselineEntry } from './delta.js';
 import { log } from './logger.js';
 
+// ─── Baseline Cache ─────────────────────────────────────────────────────────
+// Cached baseline used by isServerNewer to compare raw _LastUpdated strings
+// and avoid false-positive conflicts from timezone conversion drift.
+let _cachedBaseline;
+
+/**
+ * Pre-load the previous baseline into memory so that isServerNewer can
+ * do a fast string comparison.  Call once at the start of clone/pull.
+ */
+export async function loadBaselineForComparison() {
+  _cachedBaseline = await loadAppJsonBaseline();
+  return _cachedBaseline;
+}
+
+/**
+ * Clear the cached baseline.
+ * Call after saving a new baseline (e.g. after clone completes).
+ */
+export function resetBaselineCache() {
+  _cachedBaseline = undefined;
+}
+
+/**
+ * Look up the baseline _LastUpdated for a given entity/uid pair.
+ * Requires loadBaselineForComparison() to have been called first.
+ */
+function getBaselineLastUpdated(entity, uid) {
+  if (!_cachedBaseline) return undefined;
+  const entry = findBaselineEntry(_cachedBaseline, entity, uid);
+  return entry?._LastUpdated;
+}
+
+// ─── File Finding ───────────────────────────────────────────────────────────
+
+/**
+ * Recursively search the project directory for a file matching a bare filename.
+ * Respects .dboignore and skips known non-project dirs.
+ *
+ * @param {string} filename - Bare filename (e.g., "myfile.md", "myfile.metadata.json")
+ * @param {string} [dir=process.cwd()] - Starting directory
+ * @param {import('ignore').Ignore} [ig] - Ignore instance
+ * @returns {Promise<string[]>} - Array of matching absolute paths
+ */
+export async function findFileInProject(filename, dir, ig) {
+  if (!dir) dir = process.cwd();
+  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()) {
+      const relPath = relative(process.cwd(), fullPath).replace(/\\/g, '/');
+      if (ig.ignores(relPath + '/') || ig.ignores(relPath)) continue;
+      results.push(...await findFileInProject(filename, fullPath, ig));
+    } else if (entry.name === filename) {
+      const relPath = relative(process.cwd(), fullPath).replace(/\\/g, '/');
+      if (!ig.ignores(relPath)) results.push(fullPath);
+    }
+  }
+
+  return results;
+}
+
+// ─── UID Lookup ─────────────────────────────────────────────────────────────
+
+/**
+ * Find records by UID across all metadata files and structure.json bins.
+ *
+ * @param {string[]} uids - Array of UIDs to search for
+ * @returns {Promise<Array<{ uid: string, metaPath?: string, meta?: Object, binEntry?: Object }>>}
+ */
+export async function findByUID(uids) {
+  const uidSet = new Set(uids);
+  const results = [];
+  const found = new Set();
+
+  // Search metadata files
+  const ig = await loadIgnore();
+  const metaFiles = await findMetadataFiles(process.cwd(), ig);
+
+  for (const metaPath of metaFiles) {
+    try {
+      const raw = await readFile(metaPath, 'utf8');
+      const meta = JSON.parse(raw);
+      if (meta.UID && uidSet.has(meta.UID)) {
+        results.push({ uid: meta.UID, metaPath, meta });
+        found.add(meta.UID);
+      }
+    } catch { /* skip unreadable files */ }
+  }
+
+  // Search structure.json bin entries
+  if (found.size < uidSet.size) {
+    try {
+      const { loadStructureFile } = await import('./structure.js');
+      const structure = await loadStructureFile();
+      for (const [binId, entry] of Object.entries(structure)) {
+        if (entry.uid && uidSet.has(entry.uid) && !found.has(entry.uid)) {
+          results.push({ uid: entry.uid, binEntry: { binId: Number(binId), ...entry } });
+          found.add(entry.uid);
+        }
+      }
+    } catch { /* no structure file */ }
+  }
+
+  return results;
+}
+
 // ─── Content Value Resolution ───────────────────────────────────────────────
 
 /**
@@ -30,7 +141,7 @@ async function fileExists(path) {
 
 /**
  * Recursively find all metadata files in a directory.
- * Includes .metadata.json files and output hierarchy files (_output~*.json).
+ * Includes .metadata.json files and output hierarchy files (Name~UID.json).
  */
 export async function findMetadataFiles(dir, ig) {
   if (!ig) ig = await loadIgnore();
@@ -47,10 +158,15 @@ export async function findMetadataFiles(dir, ig) {
     } else if (entry.name.endsWith('.metadata.json')) {
       const relPath = relative(process.cwd(), fullPath).replace(/\\/g, '/');
       if (!ig.ignores(relPath)) 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
-      const relPath = relative(process.cwd(), fullPath).replace(/\\/g, '/');
-      if (!ig.ignores(relPath)) results.push(fullPath);
+    } else if (entry.name.endsWith('.json') && !entry.name.endsWith('.metadata.json') && !entry.name.includes('.CustomSQL.') && entry.name.includes('~')) {
+      // Output hierarchy root files: Name~UID.json (or legacy _output~Name~UID.json)
+      // Exclude old-format child output files — they contain a dot-prefixed
+      // child-type segment (.column~, .join~, .filter~) before .json.
+      const isChildFile = /\.(column|join|filter)~/.test(entry.name);
+      if (!isChildFile) {
+        const relPath = relative(process.cwd(), fullPath).replace(/\\/g, '/');
+        if (!ig.ignores(relPath)) results.push(fullPath);
+      }
     }
   }
 
@@ -134,11 +250,30 @@ export async function hasLocalModifications(metaPath, config = {}) {
 /**
  * Compare local sync time against server's _LastUpdated.
  * Returns true if the server record is newer than local files.
+ *
+ * When entity + uid are provided AND a baseline has been pre-loaded via
+ * loadBaselineForComparison(), the raw _LastUpdated strings are compared
+ * first.  If they match exactly, the record hasn't changed on the server
+ * and we skip the timezone conversion entirely — preventing false positives
+ * caused by DST-related rounding in the mtime ↔ parseServerDate round-trip.
+ *
+ * @param {Date}   localSyncTime      - File mtime (from getLocalSyncTime)
+ * @param {string} serverLastUpdated  - Raw _LastUpdated from the fresh server fetch
+ * @param {Object} config             - Must include ServerTimezone
+ * @param {string} [entity]           - Entity name for baseline lookup
+ * @param {string} [uid]              - Record UID for baseline lookup
  */
-export function isServerNewer(localSyncTime, serverLastUpdated, config) {
+export function isServerNewer(localSyncTime, serverLastUpdated, config, entity, uid) {
   if (!serverLastUpdated) return false;
   if (!localSyncTime) return true;
 
+  // Fast path: compare raw server string against baseline.
+  // If identical, the record hasn't changed — no timezone math needed.
+  if (entity && uid) {
+    const baselineLastUpdated = getBaselineLastUpdated(entity, uid);
+    if (baselineLastUpdated && serverLastUpdated === baselineLastUpdated) return false;
+  }
+
   const serverTz = config.ServerTimezone;
   const serverDate = parseServerDate(serverLastUpdated, serverTz);
   if (!serverDate) return false;
@@ -149,17 +284,8 @@ export function isServerNewer(localSyncTime, serverLastUpdated, config) {
 
 // ─── Server Fetching ────────────────────────────────────────────────────────
 
-/**
- * Fetch a single record from the server by entity and UID.
- */
-export async function fetchServerRecord(client, entity, uid) {
-  const result = await client.get(`/api/output/entity/${entity}/${uid}`, {
-    '_format': 'json_raw',
-  });
-  const data = result.payload || result.data;
-  const rows = Array.isArray(data) ? data : (data?.Rows || data?.rows || [data]);
-  return rows.length > 0 ? rows[0] : null;
-}
+// Per-record fetch removed — all server record fetching now goes through
+// fetchServerRecordsBatch() in toe-stepping.js via /api/app/object/.
 
 // ─── Diff Algorithm ─────────────────────────────────────────────────────────
 
@@ -321,8 +447,12 @@ function buildHunk(entries, start, end) {
 /**
  * Compare a local record (metadata.json + content files) against the server.
  * Returns a DiffResult object.
+ *
+ * @param {string} metaPath - Absolute path to the .metadata.json file
+ * @param {Object} config
+ * @param {Map<string, Object>} serverRecordsMap - Pre-fetched server records (uid → record)
  */
-export async function compareRecord(metaPath, client, config) {
+export async function compareRecord(metaPath, config, serverRecordsMap) {
   let localMeta;
   try {
     localMeta = JSON.parse(await readFile(metaPath, 'utf8'));
@@ -337,7 +467,7 @@ export async function compareRecord(metaPath, client, config) {
     return { error: `Missing _entity or UID in ${metaPath}` };
   }
 
-  const serverRecord = await fetchServerRecord(client, entity, uid);
+  const serverRecord = serverRecordsMap?.get(uid) || null;
   if (!serverRecord) {
     return { error: `Record not found on server: ${entity}/${uid}` };
   }

package/src/lib/folder-icon.js

@@ -0,0 +1,120 @@
+import { execFile } from 'child_process';
+import { writeFile, stat, access } from 'fs/promises';
+import { join } from 'path';
+import { promisify } from 'util';
+
+const execFileAsync = promisify(execFile);
+
+/**
+ * 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/ignore.js

@@ -16,12 +16,11 @@ const DEFAULT_FILE_CONTENT = `# DBO CLI ignore patterns
 .dboignore
 *.dboio.json
 app.json
-.app.json
-dbo.deploy.json
 
 # Editor / IDE / OS
 .DS_Store
 Thumbs.db
+Icon\\r
 .idea/
 .vscode/
 *.codekit3
@@ -43,7 +42,7 @@ package-lock.json
 
 # Local development (not pushed to DBO server)
 src/
-tests/
+test/
 
 # Documentation (repo scaffolding)
 SETUP.md

package/src/lib/input-parser.js

@@ -1,6 +1,6 @@
 import { readFile } from 'fs/promises';
 import { log } from './logger.js';
-import { loadUserInfo, loadTicketSuggestionOutput } from './config.js';
+import { loadConfig, loadUserInfo, loadTicketSuggestionOutput } from './config.js';
 import { buildTicketExpression, setGlobalTicket, setRecordTicket, getGlobalTicket, getRecordTicket, setTicketingRequired } from './ticketing.js';
 import { DboClient } from './client.js';
 
@@ -186,7 +186,6 @@ export async function checkSubmitErrors(result, context = {}) {
   if (needsUser && !userResolved) {
     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();
 
@@ -197,6 +196,7 @@ export async function checkSubmitErrors(result, context = {}) {
         name: 'userChoice',
         message: 'User ID Required:',
         choices: [
+          { name: 'Re-login now (recommended)', value: '_relogin' },
           { name: `Use session user (ID: ${stored.userId})`, value: stored.userId },
           { name: 'Enter a different User ID', value: '_custom' },
         ],
@@ -210,9 +210,19 @@ export async function checkSubmitErrors(result, context = {}) {
       });
     } else {
       prompts.push({
-        type: 'input',
-        name: 'userValue',
+        type: 'list',
+        name: 'userChoice',
         message: 'User ID Required:',
+        choices: [
+          { name: 'Re-login now', value: '_relogin' },
+          { name: 'Enter User ID manually', value: '_custom' },
+        ],
+      });
+      prompts.push({
+        type: 'input',
+        name: 'customUserValue',
+        message: 'User ID:',
+        when: (answers) => answers.userChoice === '_custom',
         validate: v => v.trim() ? true : 'User ID is required',
       });
     }
@@ -233,12 +243,29 @@ export async function checkSubmitErrors(result, context = {}) {
 
   if (answers.ticketId) retryParams['_OverrideTicketID'] = answers.ticketId.trim();
 
-  const userValue = answers.userValue
-    || (answers.userChoice === '_custom' ? answers.customUserValue : answers.userChoice);
-  if (userValue) {
-    const resolved = userValue.trim();
-    retryParams['_OverrideUserID'] = resolved;
-    _sessionUserOverride = resolved; // cache for remaining records in this batch
+  if (answers.userChoice === '_relogin') {
+    // Run login flow inline, then use the stored user ID
+    try {
+      const config = await loadConfig();
+      const { performLogin } = await import('../commands/login.js');
+      await performLogin(config.domain);
+      const refreshed = await loadUserInfo();
+      if (refreshed.userId) {
+        retryParams['_OverrideUserID'] = refreshed.userId;
+        _sessionUserOverride = refreshed.userId;
+      }
+    } catch (err) {
+      log.error(`Re-login failed: ${err.message}`);
+      return null;
+    }
+  } else {
+    const userValue = answers.userValue
+      || (answers.userChoice === '_custom' ? answers.customUserValue : answers.userChoice);
+    if (userValue) {
+      const resolved = userValue.trim();
+      retryParams['_OverrideUserID'] = resolved;
+      _sessionUserOverride = resolved;
+    }
   }
 
   return retryParams;

package/src/lib/metadata-templates.js

@@ -28,20 +28,37 @@ export function resolveDirective(filePath) {
   const parts = rel.split('/');
   const topDir = parts[0];
 
-  // docs/ prefix → static mapping
+  // docs/ prefix at project root → static mapping (docs/ stays at root)
   if (topDir === 'docs') {
     return { ...STATIC_DIRECTIVE_MAP.docs };
   }
 
-  // extension/<descriptor>/ — need at least 3 parts (extension/descriptor/file)
+  // lib/<subDir>/... — all server-managed dirs are now under lib/
+  if (topDir === 'lib') {
+    const subDir = parts[1];
+    if (!subDir) return null;
+
+    // lib/extension/<descriptor>/<file> — need at least 4 parts
+    if (subDir === 'extension') {
+      if (parts.length < 4) return null;
+      const descriptorDir = parts[2];
+      if (descriptorDir.startsWith('.') || descriptorDir === '_unsupported') return null;
+      return { entity: 'extension', descriptor: descriptorDir };
+    }
+
+    // lib/<entityType>/<file> — other entity dirs
+    if (ENTITY_DIR_NAMES.has(subDir)) {
+      return { entity: subDir, descriptor: null };
+    }
+  }
+
+  // Legacy fallback: bare entity-dir paths (pre-migration projects)
   if (topDir === 'extension') {
     if (parts.length < 3) return null;
     const secondDir = parts[1];
     if (secondDir.startsWith('.')) return null;
     return { entity: 'extension', descriptor: secondDir };
   }
-
-  // Other entity-dir types
   if (ENTITY_DIR_NAMES.has(topDir)) {
     return { entity: topDir, descriptor: null };
   }

package/src/lib/migrations.js

@@ -0,0 +1,75 @@
+import { readdir } from 'fs/promises';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+import { isInitialized, loadCompletedMigrations, saveCompletedMigration } from './config.js';
+import { log } from './logger.js';
+
+const MIGRATIONS_DIR = join(dirname(fileURLToPath(import.meta.url)), '../migrations');
+const MIGRATION_FILE_RE = /^(\d{3})-[\w-]+\.js$/;
+
+/**
+ * Run all pending migrations in sequence.
+ * Called at the start of every command handler unless options.migrate === false.
+ *
+ * @param {object} options - Command options object (checked for migrate flag)
+ */
+export async function runPendingMigrations(options = {}) {
+  // --no-migrate suppresses for this invocation
+  if (options.migrate === false) return;
+
+  // No .dbo/ project in this directory — nothing to migrate
+  if (!(await isInitialized())) return;
+
+  // Discover migration files
+  let files;
+  try {
+    files = await readdir(MIGRATIONS_DIR);
+  } catch {
+    return; // migrations/ directory absent — safe no-op
+  }
+
+  const migrationFiles = files
+    .filter(f => MIGRATION_FILE_RE.test(f))
+    .sort(); // ascending by NNN prefix
+
+  if (migrationFiles.length === 0) return;
+
+  const completed = new Set(await loadCompletedMigrations());
+  const pending = migrationFiles.filter(f => {
+    const id = f.match(MIGRATION_FILE_RE)?.[1];
+    return id && !completed.has(id);
+  });
+
+  if (pending.length === 0) return;
+
+  for (const file of pending) {
+    const id = file.match(MIGRATION_FILE_RE)[1];
+    try {
+      const migrationPath = join(MIGRATIONS_DIR, file);
+      const { default: run, description } = await import(migrationPath);
+      await run(options);
+      await saveCompletedMigration(id);
+      log.success(`Migration ${id}: ${description}`);
+    } catch (err) {
+      log.warn(`Migration ${id} failed: ${err.message} — skipped`);
+    }
+  }
+}
+
+/**
+ * Count pending (unrun) migrations without executing them.
+ * Used by `dbo status` to report pending count.
+ *
+ * @returns {Promise<number>}
+ */
+export async function countPendingMigrations() {
+  if (!(await isInitialized())) return 0;
+  let files;
+  try { files = await readdir(MIGRATIONS_DIR); } catch { return 0; }
+  const migrationFiles = files.filter(f => MIGRATION_FILE_RE.test(f));
+  const completed = new Set(await loadCompletedMigrations());
+  return migrationFiles.filter(f => {
+    const id = f.match(MIGRATION_FILE_RE)?.[1];
+    return id && !completed.has(id);
+  }).length;
+}

package/src/lib/save-to-disk.js

@@ -230,7 +230,7 @@ export async function saveToDisk(rows, columns, options = {}) {
 
       if (bulkAction !== 'overwrite_all') {
         const localSyncTime = await diffModule.getLocalSyncTime(metaPath);
-        const serverIsNewer = diffModule.isServerNewer(localSyncTime, row._LastUpdated, options.config || {});
+        const serverIsNewer = diffModule.isServerNewer(localSyncTime, row._LastUpdated, options.config || {}, options.entity, row.UID);
 
         if (serverIsNewer) {
           const action = await diffModule.promptChangeDetection(finalName, row, options.config || {});

package/src/lib/scaffold.js

@@ -1,7 +1,8 @@
-import { mkdir, stat, writeFile, access } from 'fs/promises';
+import { mkdir, stat, readFile, writeFile, access } from 'fs/promises';
 import { join } from 'path';
-import { DEFAULT_PROJECT_DIRS } from './structure.js';
+import { SCAFFOLD_DIRS } from './structure.js';
 import { log } from './logger.js';
+import { applyTrashIcon } from './folder-icon.js';
 
 /**
  * Scaffold the standard DBO project directory structure in cwd.
@@ -16,7 +17,7 @@ export async function scaffoldProjectDirs(cwd = process.cwd()) {
   const skipped = [];
   const warned  = [];
 
-  for (const dir of DEFAULT_PROJECT_DIRS) {
+  for (const dir of SCAFFOLD_DIRS) {
     const target = join(cwd, dir);
     try {
       const s = await stat(target);
@@ -33,6 +34,9 @@ export async function scaffoldProjectDirs(cwd = process.cwd()) {
     }
   }
 
+  // Best-effort: apply trash icon to the trash directory
+  await applyTrashIcon(join(cwd, 'trash'));
+
   // Create app.json if absent
   const appJsonPath = join(cwd, 'app.json');
   try {
@@ -42,6 +46,57 @@ export async function scaffoldProjectDirs(cwd = process.cwd()) {
     created.push('app.json');
   }
 
+  // Create manifest.json if absent
+  const manifestPath = join(cwd, 'manifest.json');
+  try {
+    await access(manifestPath);
+  } catch {
+    // Try to resolve values from local app.json; fall back to empty strings
+    let appName = '';
+    let shortName = '';
+    let description = '';
+    let bgColor = '#ffffff';
+    let domain = '';
+
+    try {
+      const appData = JSON.parse(await readFile(appJsonPath, 'utf8'));
+      appName = appData.Name || '';
+      shortName = appData.ShortName || '';
+      description = appData.Description || '';
+      domain = appData._domain || '';
+
+      // Find background_color from extension children (widget matching ShortName)
+      if (shortName && Array.isArray(appData.children?.extension)) {
+        for (const ext of appData.children.extension) {
+          if (ext.Descriptor === 'widget' && ext.String1 === shortName && ext.String4) {
+            bgColor = ext.String4;
+            break;
+          }
+        }
+      }
+    } catch { /* app.json missing or unparseable — use empty defaults */ }
+
+    const manifest = {
+      name: `${appName} | ${domain}`,
+      short_name: shortName,
+      description,
+      orientation: 'portrait',
+      start_url: shortName ? `/app/${shortName}/ui/` : '',
+      lang: 'en',
+      scope: shortName ? `/app/${shortName}/ui/` : '',
+      display_override: ['window-control-overlay', 'minimal-ui'],
+      display: 'standalone',
+      background_color: bgColor,
+      theme_color: '#000000',
+      id: shortName,
+      screenshots: [],
+      ios: {},
+      icons: [],
+    };
+    await writeFile(manifestPath, JSON.stringify(manifest, null, 2) + '\n');
+    created.push('manifest.json');
+  }
+
   return { created, skipped, warned };
 }