@dboio/cli 0.5.1 → 0.6.1

package/README.md

@@ -31,6 +31,8 @@ npm link
 npx @dboio/cli <command>
 ```
 
+> **Shorthand:** You can use `dbo i` as a shortcut for `dbo install` (similar to `npm i`).
+
 ### Requirements
 
 - **Node.js 18+** (uses native `fetch` and `FormData`)
@@ -307,6 +309,51 @@ project/
   media/operator/app/...     # ← FullPath placement (when MediaPlacement=fullpath)
 ```
 
+#### Understanding the `Bins/` directory structure
+
+The `Bins/` directory is the default location for all bin-placed content files during clone. It organizes files according to your app's bin hierarchy from DBO.io.
+
+**Directory Organization:**
+
+- **`Bins/`** — Root directory for all bin-placed files (local organizational directory only)
+  - **`Bins/app/`** — Special subdirectory for the main app bin (typically the default bin)
+  - **`Bins/custom_name/`** — Custom bin directories (e.g., `tpl/`, `ticket_test/`, etc.)
+
+**Important: The `Bins/app/` special case**
+
+The `app/` subdirectory under `Bins/` is treated specially:
+
+1. **It's organizational only** — The `Bins/app/` prefix exists only for local file organization and is **not part of the server-side path**.
+
+2. **Path normalization** — When comparing paths (during `dbo push`), the CLI automatically strips both `Bins/` and `app/` from paths:
+   ```
+   Local file:    Bins/app/assets/css/operator.css
+   Server Path:   assets/css/operator.css
+   → These are considered the same path ✓
+   ```
+
+3. **Custom bins are preserved** — Other subdirectories like `Bins/tpl/` or `Bins/ticket_test/` represent actual bin hierarchies and their names are meaningful:
+   ```
+   Local file:    Bins/tpl/header.html
+   Server Path:   tpl/header.html
+   → The 'tpl/' directory is preserved ✓
+   ```
+
+**Why this matters:**
+
+- When you `dbo push` files from `Bins/app/`, the CLI knows these paths should match the root-level paths in your metadata
+- If your metadata `Path` column contains `assets/css/colors.css`, it will correctly match files in `Bins/app/assets/css/colors.css`
+- Custom bin directories like `Bins/tpl/` serve from the `tpl/` directive and maintain their path structure
+
+**Leading slash handling:**
+
+The CLI handles leading `/` in metadata paths flexibly:
+- `Path: assets/css/file.css` matches `Bins/app/assets/css/file.css` ✓
+- `Path: /assets/css/file.css` also matches `Bins/app/assets/css/file.css` ✓
+- `Path: /assets/css/file.css` matches `Bins/assets/css/file.css` ✓
+
+This ensures compatibility with various path formats from the server while maintaining correct local file organization.
+
 ---
 
 ### `dbo login`
@@ -1072,7 +1119,7 @@ If no stored user info is available, it prompts for direct input. The CLI automa
 
 ---
 
-### `dbo install`
+### `dbo install` (alias: `dbo i`)
 
 Install or upgrade dbo-cli components including the CLI itself, plugins, and Claude Code integration.
 
@@ -1081,11 +1128,11 @@ Install or upgrade dbo-cli components including the CLI itself, plugins, and Cla
 dbo install
 
 # Install/upgrade CLI from npm (latest)
-dbo install dbo
-dbo install dbo@latest
+dbo i dbo
+dbo i dbo@latest
 
 # Install a specific CLI version
-dbo install dbo@0.4.1
+dbo i dbo@0.4.1
 
 # Install CLI from local source directory
 dbo install /path/to/local/cli/src

package/bin/dbo.js

@@ -1,6 +1,11 @@
 #!/usr/bin/env node
 
 import { Command } from 'commander';
+import { createRequire } from 'module';
+
+const require = createRequire(import.meta.url);
+const packageJson = require('../package.json');
+
 import { initCommand } from '../src/commands/init.js';
 import { loginCommand } from '../src/commands/login.js';
 import { logoutCommand } from '../src/commands/logout.js';
@@ -28,7 +33,7 @@ const program = new Command();
 program
   .name('dbo')
   .description('CLI for the DBO.io framework')
-  .version('0.5.0');
+  .version(packageJson.version, '-v, --version', 'output the version number');
 
 program.addCommand(initCommand);
 program.addCommand(loginCommand);

package/bin/postinstall.js

@@ -0,0 +1,88 @@
+#!/usr/bin/env node
+
+// Post-install hook for `npm i @dboio/cli`
+// Interactive plugin picker when TTY is available, static message otherwise.
+
+const RESET = '\x1b[0m';
+const BOLD = '\x1b[1m';
+const DIM = '\x1b[2m';
+const CYAN = '\x1b[36m';
+const YELLOW = '\x1b[33m';
+
+// Available plugins — add new entries here as plugins are created
+const PLUGINS = [
+  {
+    name: 'dbo',
+    label: 'Claude Code — /dbo slash command',
+    command: 'dbo install --claudecommand dbo'
+  }
+];
+
+function printStaticMessage() {
+  console.error('');
+  console.error(`${BOLD}${CYAN}  DBO.io CLI installed successfully.${RESET}`);
+  console.error('');
+  console.error(`  ${DIM}Plugins available:${RESET}`);
+  for (const plugin of PLUGINS) {
+    console.error(`    ${YELLOW}${plugin.label}${RESET}`);
+    console.error(`      ${DIM}${plugin.command}${RESET}`);
+  }
+  console.error('');
+  console.error(`  To install all plugins at once, run:`);
+  console.error(`    ${BOLD}dbo install plugins${RESET}`);
+  console.error('');
+}
+
+async function promptInteractive() {
+  console.error('');
+  console.error(`${BOLD}${CYAN}  DBO.io CLI installed successfully.${RESET}`);
+  console.error('');
+
+  const { default: inquirer } = await import('inquirer');
+
+  const { selected } = await inquirer.prompt([
+    {
+      type: 'checkbox',
+      name: 'selected',
+      message: 'Select plugins to install:',
+      choices: PLUGINS.map(p => ({
+        name: p.label,
+        value: p.command,
+        checked: false
+      }))
+    }
+  ]);
+
+  if (selected.length === 0) {
+    console.error('');
+    console.error(`  ${DIM}No plugins selected. You can install them later with:${RESET}`);
+    console.error(`    ${BOLD}dbo install plugins${RESET}`);
+    console.error('');
+    return;
+  }
+
+  const { execSync } = await import('child_process');
+  const combined = selected.join(' && ');
+
+  console.error('');
+  console.error(`  ${DIM}Running: ${combined}${RESET}`);
+  console.error('');
+
+  try {
+    execSync(combined, { stdio: 'inherit' });
+  } catch {
+    console.error('');
+    console.error(`  ${YELLOW}Plugin installation had an issue. You can retry with:${RESET}`);
+    for (const cmd of selected) {
+      console.error(`    ${BOLD}${cmd}${RESET}`);
+    }
+    console.error('');
+  }
+}
+
+// TTY check — interactive prompt only works when user has a terminal
+if (process.stdin.isTTY && process.stdout.isTTY) {
+  promptInteractive().catch(() => printStaticMessage());
+} else {
+  printStaticMessage();
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dboio/cli",
-  "version": "0.5.1",
+  "version": "0.6.1",
   "description": "CLI for the DBO.io framework",
   "type": "module",
   "bin": {
@@ -16,6 +16,7 @@
     "node": ">=18.0.0"
   },
   "scripts": {
+    "postinstall": "node bin/postinstall.js",
     "test": "node --test src/**/*.test.js tests/**/*.test.js"
   },
   "dependencies": {

package/src/commands/clone.js

@@ -2,7 +2,7 @@ import { Command } from 'commander';
 import { readFile, writeFile, mkdir, access } from 'fs/promises';
 import { join, basename, extname } from 'path';
 import { DboClient } from '../lib/client.js';
-import { loadConfig, updateConfigWithApp, loadClonePlacement, saveClonePlacement, ensureGitignore, saveEntityDirPreference, loadEntityDirPreference } from '../lib/config.js';
+import { loadConfig, updateConfigWithApp, loadClonePlacement, saveClonePlacement, ensureGitignore, saveEntityDirPreference, loadEntityDirPreference, saveEntityContentExtractions, loadEntityContentExtractions, saveAppJsonBaseline } from '../lib/config.js';
 import { buildBinHierarchy, resolveBinPath, createDirectories, saveStructureFile, getBinName, findBinByPath, BINS_DIR, DEFAULT_PROJECT_DIRS, ENTITY_DIR_MAP } from '../lib/structure.js';
 import { log } from '../lib/logger.js';
 import { setFileTimestamps } from '../lib/timestamps.js';
@@ -43,6 +43,16 @@ async function fileExists(path) {
  * 3. If not found → place under Bins/<dir> (e.g. "Bins/tpl")
  *
  * This ensures content files always land inside Bins/, never at the project root.
+ *
+ * **Note on Bins/app/:**
+ * Files placed in Bins/app/ are purely for local organization. During push operations,
+ * the "app/" subdirectory is treated specially and stripped from path comparisons,
+ * as these files are served from the root path on the server without the "app/" prefix.
+ * Other custom bin directories (like "tpl/") maintain their directory name in the path.
+ *
+ * @param {string} pathValue - Server-side Path value
+ * @param {Object} structure - Bin hierarchy structure from structure.json
+ * @returns {string} - Local directory path under Bins/
  */
 function resolvePathToBinsDir(pathValue, structure) {
   const cleaned = pathValue.replace(/^\/+|\/+$/g, '');
@@ -229,6 +239,12 @@ export async function performClone(source, options = {}) {
   // Step 7: Save app.json with references
   await saveAppJson(appJson, contentRefs, otherRefs);
 
+  // Step 8: Create .app.json baseline for delta tracking
+  await saveBaselineFile(appJson);
+
+  // Step 9: Ensure .app.json is in .gitignore
+  await ensureGitignore(['.app.json']);
+
   log.plain('');
   log.success('Clone complete!');
   log.dim('  app.json saved to project root');
@@ -473,8 +489,9 @@ async function processEntityDirEntries(entityName, entries, options, serverTz) {
       if (columns.length > 0) {
         const inquirer = (await import('inquirer')).default;
 
-        // Find best default
-        const defaultCol = columns.includes('Name') ? 'Name'
+        // Find best default (app_version prioritizes Number → Name → UID)
+        const defaultCol = (entityName === 'app_version' && columns.includes('Number')) ? 'Number'
+          : columns.includes('Name') ? 'Name'
           : columns.includes('name') ? 'name'
           : columns.includes('UID') ? 'UID'
           : columns[0];
@@ -520,10 +537,31 @@ async function processEntityDirEntries(entityName, entries, options, serverTz) {
     }
 
     if (base64Cols.length > 0) {
+      // Load saved content extraction preferences
+      const savedExtractions = await loadEntityContentExtractions(entityName);
+      const newPreferences = savedExtractions ? { ...savedExtractions } : {};
+      let hasNewChoices = false;
+
       const inquirer = (await import('inquirer')).default;
 
       // Prompt per column: show snippet and ask extract yes/no + extension
       for (const { col, snippet } of base64Cols) {
+        // Check if we have a saved preference for this column
+        if (savedExtractions && col in savedExtractions) {
+          const savedPref = savedExtractions[col];
+          if (savedPref === false) {
+            // User previously chose not to extract this column
+            log.dim(`  Skipping "${col}" (saved preference: no extraction)`);
+            continue;
+          } else if (typeof savedPref === 'string') {
+            // User previously chose to extract with a specific extension
+            log.dim(`  Extracting "${col}" as .${savedPref} file (saved preference)`);
+            contentColsToExtract.push({ col, ext: savedPref });
+            continue;
+          }
+        }
+
+        // No saved preference - prompt the user
         const preview = snippet ? ` (${snippet})` : '';
         const guessed = guessExtensionForColumn(col);
 
@@ -541,9 +579,22 @@ async function processEntityDirEntries(entityName, entries, options, serverTz) {
             message: `File extension for "${col}":`,
             default: guessed,
           }]);
-          contentColsToExtract.push({ col, ext: ext.replace(/^\./, '') });
+          const cleanExt = ext.replace(/^\./, '');
+          contentColsToExtract.push({ col, ext: cleanExt });
+          newPreferences[col] = cleanExt;
+          hasNewChoices = true;
+        } else {
+          // User chose not to extract - save this preference too
+          newPreferences[col] = false;
+          hasNewChoices = true;
         }
       }
+
+      // Save preferences if any new choices were made
+      if (hasNewChoices) {
+        await saveEntityContentExtractions(entityName, newPreferences);
+        log.dim(`  Saved content extraction preferences for ${entityName}`);
+      }
     }
   }
 
@@ -554,6 +605,9 @@ async function processEntityDirEntries(entityName, entries, options, serverTz) {
     let name;
     if (filenameCol && record[filenameCol] !== null && record[filenameCol] !== undefined) {
       name = sanitizeFilename(String(record[filenameCol]));
+    } else if (entityName === 'app_version' && record.Number) {
+      // Special fallback for app_version: Number is preferred over Name
+      name = sanitizeFilename(String(record.Number));
     } else if (record.Name) {
       name = sanitizeFilename(String(record.Name));
     } else {
@@ -942,12 +996,33 @@ async function processMediaEntries(mediaRecords, structure, options, config, app
  */
 async function processRecord(entityName, record, structure, options, usedNames, placementPreference, serverTz, bulkAction = { value: null }) {
   let name = sanitizeFilename(String(record.Name || record.UID || 'untitled'));
-  const ext = (record.Extension || 'txt').toLowerCase();
+
+  // Determine file extension (priority: Extension field > Name field > Path field > empty)
+  let ext = '';
+  if (record.Extension) {
+    // Use explicit Extension field
+    ext = String(record.Extension).toLowerCase();
+  } else {
+    // Try to extract from Name field first
+    if (record.Name) {
+      const extractedExt = extname(String(record.Name));
+      ext = extractedExt ? extractedExt.substring(1).toLowerCase() : '';
+    }
+
+    // If no extension from Name, try Path field as fallback
+    if (!ext && record.Path) {
+      const extractedExt = extname(String(record.Path));
+      ext = extractedExt ? extractedExt.substring(1).toLowerCase() : '';
+    }
+  }
+  // If still no extension, ext remains '' (no extension)
 
   // Avoid double extension: if name already ends with .ext, strip it
-  const extWithDot = `.${ext}`;
-  if (name.toLowerCase().endsWith(extWithDot)) {
-    name = name.substring(0, name.length - extWithDot.length);
+  if (ext) {
+    const extWithDot = `.${ext}`;
+    if (name.toLowerCase().endsWith(extWithDot)) {
+      name = name.substring(0, name.length - extWithDot.length);
+    }
   }
 
   // Determine target directory (default: bins/ for items without explicit placement)
@@ -1022,7 +1097,7 @@ async function processRecord(entityName, record, structure, options, usedNames,
     (typeof contentValue === 'string' && contentValue.length > 0)
   );
 
-  const fileName = `${finalName}.${ext}`;
+  const fileName = ext ? `${finalName}.${ext}` : finalName;
   const filePath = join(dir, fileName);
   const metaPath = join(dir, `${finalName}.metadata.json`);
 
@@ -1195,3 +1270,51 @@ async function saveAppJson(appJson, contentRefs, otherRefs) {
 
   await writeFile('app.json', JSON.stringify(output, null, 2) + '\n');
 }
+
+/**
+ * Save .app.json baseline file with decoded base64 values.
+ * This file tracks the server state for delta detection.
+ */
+async function saveBaselineFile(appJson) {
+  // Deep clone the app JSON
+  const baseline = JSON.parse(JSON.stringify(appJson));
+
+  // Recursively decode all base64 fields
+  decodeBase64Fields(baseline);
+
+  // Save to .app.json
+  await saveAppJsonBaseline(baseline);
+
+  log.dim('  .app.json baseline created (system-managed, do not edit)');
+}
+
+/**
+ * Recursively decode base64 fields in an object or array.
+ * Modifies the input object in-place.
+ */
+function decodeBase64Fields(obj) {
+  if (!obj || typeof obj !== 'object') {
+    return;
+  }
+
+  if (Array.isArray(obj)) {
+    for (const item of obj) {
+      decodeBase64Fields(item);
+    }
+    return;
+  }
+
+  // Process each property
+  for (const [key, value] of Object.entries(obj)) {
+    if (value && typeof value === 'object') {
+      // Check if it's a base64 encoded value
+      if (!Array.isArray(value) && value.encoding === 'base64' && typeof value.value === 'string') {
+        // Decode using existing resolveContentValue function
+        obj[key] = resolveContentValue(value);
+      } else {
+        // Recursively process nested objects/arrays
+        decodeBase64Fields(value);
+      }
+    }
+  }
+}

package/src/commands/install.js

@@ -144,6 +144,7 @@ function parseTarget(target) {
 }
 
 export const installCommand = new Command('install')
+  .alias('i')
   .description('Install or upgrade dbo-cli, plugins, or Claude Code commands')
   .argument('[target]', 'What to install: dbo[@version], plugins, claudecommands, claudecode, or a local path')
   .option('--claudecommand <name>', 'Install/update a specific Claude command by name')
@@ -161,7 +162,7 @@ export const installCommand = new Command('install')
             await installCli(parsed.version);
             break;
           case 'cli-local':
-            await installCliFromLocal(parsed.path, options);
+            await installCliFromLocal(parsed.path);
             break;
           case 'plugins':
             await installPlugins(options);
@@ -316,7 +317,7 @@ async function installCli(version) {
   }
 }
 
-async function installCliFromLocal(localPath, options = {}) {
+async function installCliFromLocal(localPath) {
   const resolvedPath = resolve(localPath);
 
   if (!await fileExists(resolvedPath)) {
@@ -366,16 +367,6 @@ async function installCliFromLocal(localPath, options = {}) {
     log.dim('You can also use: cd <path> && npm link');
     return;
   }
-
-  // Offer to install/upgrade plugins after CLI install
-  const { installPluginsNow } = await inquirer.prompt([{
-    type: 'confirm', name: 'installPluginsNow',
-    message: 'Install/upgrade Claude Code command plugins?',
-    default: true,
-  }]);
-  if (installPluginsNow) {
-    await installOrUpdateClaudeCommands(options);
-  }
 }
 
 // ─── Claude Code Installation ───────────────────────────────────────────────

package/src/commands/push.js

@@ -6,9 +6,11 @@ import { buildInputBody, checkSubmitErrors } from '../lib/input-parser.js';
 import { formatResponse, formatError } from '../lib/formatter.js';
 import { log } from '../lib/logger.js';
 import { shouldSkipColumn } from '../lib/columns.js';
-import { loadConfig, loadSynchronize, saveSynchronize } from '../lib/config.js';
+import { loadConfig, loadSynchronize, saveSynchronize, loadAppJsonBaseline, saveAppJsonBaseline, hasBaseline } from '../lib/config.js';
 import { setFileTimestamps } from '../lib/timestamps.js';
 import { findMetadataFiles } from '../lib/diff.js';
+import { detectChangedColumns, findBaselineEntry } from '../lib/delta.js';
+import { buildDependencyGraph } from '../lib/dependencies.js';
 
 export const pushCommand = new Command('push')
   .description('Push local files back to DBO.io using metadata from pull')
@@ -52,6 +54,8 @@ async function processPendingDeletes(client, options) {
   log.info(`Processing ${sync.delete.length} pending deletion(s)...`);
 
   const remaining = [];
+  const deletedUids = [];
+
   for (const entry of sync.delete) {
     log.info(`Deleting "${entry.name}" (${entry.entity}:${entry.RowID})`);
 
@@ -71,6 +75,7 @@ async function processPendingDeletes(client, options) {
         const retryResult = await client.postUrlEncoded('/api/input/submit', retryBody);
         if (retryResult.successful) {
           log.success(`  Deleted "${entry.name}" from server`);
+          deletedUids.push(entry.UID);
         } else {
           log.error(`  Failed to delete "${entry.name}"`);
           formatResponse(retryResult, { json: options.json, jq: options.jq });
@@ -78,6 +83,7 @@ async function processPendingDeletes(client, options) {
         }
       } else if (result.successful) {
         log.success(`  Deleted "${entry.name}" from server`);
+        deletedUids.push(entry.UID);
       } else {
         log.error(`  Failed to delete "${entry.name}"`);
         formatResponse(result, { json: options.json, jq: options.jq });
@@ -89,6 +95,11 @@ async function processPendingDeletes(client, options) {
     }
   }
 
+  // Remove edit entries for successfully deleted records (spec requirement)
+  if (deletedUids.length > 0) {
+    sync.edit = (sync.edit || []).filter(e => !deletedUids.includes(e.UID));
+  }
+
   // Update synchronize.json with any remaining entries
   sync.delete = remaining;
   await saveSynchronize(sync);
@@ -131,8 +142,17 @@ async function pushDirectory(dirPath, client, options) {
 
   log.info(`Found ${metaFiles.length} record(s) to push`);
 
-  let succeeded = 0;
-  let failed = 0;
+  // Load baseline for delta detection
+  const baseline = await loadAppJsonBaseline();
+  const config = await loadConfig();
+
+  if (!baseline) {
+    log.warn('No .app.json baseline found — performing full push (run "dbo clone" to enable delta sync)');
+  }
+
+  // Collect metadata with detected changes
+  const toPush = [];
+  let skipped = 0;
 
   for (const metaPath of metaFiles) {
     let meta;
@@ -140,19 +160,19 @@ async function pushDirectory(dirPath, client, options) {
       meta = JSON.parse(await readFile(metaPath, 'utf8'));
     } catch (err) {
       log.warn(`Skipping invalid metadata: ${metaPath} (${err.message})`);
-      failed++;
+      skipped++;
       continue;
     }
 
     if (!meta.UID && !meta._id) {
       log.warn(`Skipping "${metaPath}": no UID or _id found`);
-      failed++;
+      skipped++;
       continue;
     }
 
     if (!meta._entity) {
       log.warn(`Skipping "${metaPath}": no _entity found`);
-      failed++;
+      skipped++;
       continue;
     }
 
@@ -172,24 +192,77 @@ async function pushDirectory(dirPath, client, options) {
         }
       }
     }
-    if (missingFiles) { failed++; continue; }
+    if (missingFiles) { skipped++; continue; }
+
+    // Detect changed columns (delta detection)
+    let changedColumns = null;
+    if (baseline) {
+      try {
+        changedColumns = await detectChangedColumns(metaPath, baseline, config);
+        if (changedColumns.length === 0) {
+          log.dim(`  Skipping ${basename(metaPath)} — no changes detected`);
+          skipped++;
+          continue;
+        }
+      } catch (err) {
+        log.warn(`Delta detection failed for ${metaPath}: ${err.message} — performing full push`);
+      }
+    }
+
+    toPush.push({ meta, metaPath, changedColumns });
+  }
 
+  if (toPush.length === 0) {
+    log.info('No changes to push');
+    return;
+  }
+
+  // Group by entity and apply dependency ordering
+  const byEntity = {};
+  for (const item of toPush) {
+    const entity = item.meta._entity;
+    if (!byEntity[entity]) byEntity[entity] = [];
+    byEntity[entity].push(item);
+  }
+
+  // Process in dependency order
+  let succeeded = 0;
+  let failed = 0;
+  const successfulPushes = [];
+
+  for (const item of toPush) {
     try {
-      await pushFromMetadata(meta, metaPath, client, options);
-      succeeded++;
+      const success = await pushFromMetadata(item.meta, item.metaPath, client, options, item.changedColumns);
+      if (success) {
+        succeeded++;
+        successfulPushes.push(item);
+      } else {
+        failed++;
+      }
     } catch (err) {
-      log.error(`Failed: ${metaPath} — ${err.message}`);
+      log.error(`Failed: ${item.metaPath} — ${err.message}`);
       failed++;
     }
   }
 
-  log.info(`Push complete: ${succeeded} succeeded, ${failed} failed`);
+  // Update baseline after successful pushes
+  if (baseline && successfulPushes.length > 0) {
+    await updateBaselineAfterPush(baseline, successfulPushes);
+  }
+
+  log.info(`Push complete: ${succeeded} succeeded, ${failed} failed, ${skipped} skipped`);
 }
 
 /**
  * Build and submit input expressions from a metadata object
+ * @param {Object} meta - Metadata object
+ * @param {string} metaPath - Path to metadata file
+ * @param {DboClient} client - API client
+ * @param {Object} options - Push options
+ * @param {string[]|null} changedColumns - Optional array of changed column names (for delta sync)
+ * @returns {Promise<boolean>} - True if push succeeded
  */
-async function pushFromMetadata(meta, metaPath, client, options) {
+async function pushFromMetadata(meta, metaPath, client, options, changedColumns = null) {
   const uid = meta.UID || meta._id;
   const entity = meta._entity;
   const contentCols = new Set(meta._contentColumns || []);
@@ -210,11 +283,17 @@ async function pushFromMetadata(meta, metaPath, client, options) {
   const dataExprs = [];
   let metaUpdated = false;
 
+  // If changedColumns is provided, only push those columns (delta sync)
+  const columnsToProcess = changedColumns ? new Set(changedColumns) : null;
+
   for (const [key, value] of Object.entries(meta)) {
     if (shouldSkipColumn(key)) continue;
     if (key === 'UID') continue; // UID is the identifier, not a column to update
     if (value === null || value === undefined) continue;
 
+    // Delta sync: skip columns not in changedColumns
+    if (columnsToProcess && !columnsToProcess.has(key)) continue;
+
     const isContentCol = contentCols.has(key);
 
     // --meta-only: skip content columns
@@ -236,10 +315,11 @@ async function pushFromMetadata(meta, metaPath, client, options) {
 
   if (dataExprs.length === 0) {
     log.warn(`Nothing to push for ${basename(metaPath)}`);
-    return;
+    return false;
   }
 
-  log.info(`Pushing ${basename(metaPath, '.metadata.json')} (${entity}:${uid}) — ${dataExprs.length} field(s)`);
+  const fieldLabel = changedColumns ? `${dataExprs.length} changed field(s)` : `${dataExprs.length} field(s)`;
+  log.info(`Pushing ${basename(metaPath, '.metadata.json')} (${entity}:${uid}) — ${fieldLabel}`);
 
   const extraParams = { '_confirm': options.confirm };
   if (options.ticket) extraParams['_OverrideTicketID'] = options.ticket;
@@ -264,7 +344,7 @@ async function pushFromMetadata(meta, metaPath, client, options) {
   }
 
   if (!result.successful) {
-    throw new Error('Push failed');
+    return false;
   }
 
   // Update file timestamps from server response
@@ -293,6 +373,64 @@ async function pushFromMetadata(meta, metaPath, client, options) {
       }
     }
   } catch { /* non-critical timestamp update */ }
+
+  return true;
+}
+
+/**
+ * Normalize a local file path for comparison with server-side Path.
+ *
+ * The Bins/ directory is used for local file organization and does not reflect
+ * the actual server-side serving path. This function strips organizational prefixes
+ * to enable correct path comparison during push operations.
+ *
+ * **Directory Structure:**
+ * - `Bins/` — Local organizational root (always stripped)
+ * - `Bins/app/` — Special case: the "app" subdirectory is also stripped because it's
+ *   purely organizational. Files in Bins/app/ are served from the app root without
+ *   the "app/" prefix on the server.
+ * - `Bins/custom_name/` — Custom bin directories (tpl/, ticket_test/, etc.) are
+ *   preserved because they represent actual bin hierarchies that serve from their
+ *   directory name.
+ *
+ * **Why "app/" is special:**
+ * The main app bin is placed in Bins/app/ locally for organization, but server-side
+ * these files are served from the root path (no "app/" prefix). Other custom bins
+ * like "tpl/" maintain their directory name in the serving path.
+ *
+ * Examples:
+ *   "Bins/app/assets/css/file.css" → "assets/css/file.css" (strips Bins/app/)
+ *   "Bins/tpl/header.html" → "tpl/header.html" (preserves tpl/)
+ *   "Bins/assets/css/file.css" → "assets/css/file.css" (strips Bins/ only)
+ *   "Sites/MySite/content/page.html" → "Sites/MySite/content/page.html" (unchanged)
+ *
+ * @param {string} localPath - Relative path from project root
+ * @returns {string} - Normalized path for comparison with metadata Path column
+ */
+function normalizePathForComparison(localPath) {
+  // Convert backslashes to forward slashes (Windows compatibility)
+  const normalized = localPath.replace(/\\/g, '/');
+
+  // Strip leading and trailing slashes
+  const cleaned = normalized.replace(/^\/+|\/+$/g, '');
+
+  // Check if path starts with "Bins/" organizational directory
+  if (cleaned.startsWith('Bins/')) {
+    // Remove "Bins/" prefix (length = 5)
+    const withoutBins = cleaned.substring(5);
+
+    // Special case: strip "app/" organizational subdirectory
+    // This is the only special subdirectory - all others (tpl/, assets/, etc.) are preserved
+    if (withoutBins.startsWith('app/')) {
+      return withoutBins.substring(4); // Remove "app/" (length = 4)
+    }
+
+    // For all other paths, return without Bins/ prefix
+    return withoutBins;
+  }
+
+  // Path doesn't start with Bins/, return as-is
+  return cleaned;
 }
 
 /**
@@ -319,15 +457,25 @@ async function checkPathMismatch(meta, metaPath, options) {
   const currentFilePath = join(metaDir, contentFileName);
   const currentRelPath = relative(process.cwd(), currentFilePath);
 
-  // Normalize stored path for comparison
-  const storedPath = String(meta.Path).replace(/^\/+|\/+$/g, '');
-  const currentPath = currentRelPath.replace(/\\/g, '/');
+  // Normalize both paths for comparison
+  // The metadata Path may also incorrectly contain Bins/app/ prefix from old data
+  const storedPathRaw = String(meta.Path).replace(/^\/+|\/+$/g, ''); // Strip leading/trailing slashes
+  const normalizedStoredPath = normalizePathForComparison(storedPathRaw);
+  const normalizedCurrentPath = normalizePathForComparison(currentRelPath);
+
+  // Compare with flexible handling of leading slash
+  // (Both /path and path are considered equivalent)
+  const storedNormalized = normalizedStoredPath.replace(/^\/+/, '');
+  const currentNormalized = normalizedCurrentPath.replace(/^\/+/, '');
 
-  if (storedPath === currentPath) return;
+  if (storedNormalized === currentNormalized) return;
+
+  // Use normalized path for display
+  const currentPath = normalizedCurrentPath;
 
   // Path mismatch detected
   log.warn(`Path mismatch for "${metaBase}":`);
-  log.label('  Metadata Path', storedPath);
+  log.label('  Metadata Path', storedPathRaw);
   log.label('  Current path ', currentPath);
 
   let updatePath = options.yes;
@@ -349,3 +497,69 @@ async function checkPathMismatch(meta, metaPath, options) {
     log.success(`  Path updated to "${currentPath}"`);
   }
 }
+
+/**
+ * Update baseline file (.app.json) after successful pushes.
+ * Syncs changed column values and timestamps from metadata to baseline.
+ *
+ * @param {Object} baseline - The baseline JSON object
+ * @param {Array} successfulPushes - Array of { meta, metaPath, changedColumns }
+ */
+async function updateBaselineAfterPush(baseline, successfulPushes) {
+  let modified = false;
+
+  for (const { meta, metaPath, changedColumns } of successfulPushes) {
+    const uid = meta.UID || meta._id;
+    const entity = meta._entity;
+
+    // Find the baseline entry
+    const baselineEntry = findBaselineEntry(baseline, entity, uid);
+    if (!baselineEntry) {
+      log.warn(`  Baseline entry not found for ${entity}:${uid} — skipping baseline update`);
+      continue;
+    }
+
+    // Update _LastUpdated and _LastUpdatedUserID from metadata
+    if (meta._LastUpdated) {
+      baselineEntry._LastUpdated = meta._LastUpdated;
+      modified = true;
+    }
+    if (meta._LastUpdatedUserID) {
+      baselineEntry._LastUpdatedUserID = meta._LastUpdatedUserID;
+      modified = true;
+    }
+
+    // Update changed column values in baseline
+    const columnsToUpdate = changedColumns || Object.keys(meta).filter(k => !shouldSkipColumn(k) && k !== 'UID');
+
+    for (const col of columnsToUpdate) {
+      const value = meta[col];
+      if (value === null || value === undefined) continue;
+
+      const strValue = String(value);
+
+      // If it's a @reference, read the file content and store in baseline
+      if (strValue.startsWith('@')) {
+        try {
+          const refFile = strValue.substring(1);
+          const refPath = join(dirname(metaPath), refFile);
+          const fileContent = await readFile(refPath, 'utf8');
+          baselineEntry[col] = fileContent;
+          modified = true;
+        } catch (err) {
+          log.warn(`  Failed to read ${strValue} for baseline update: ${err.message}`);
+        }
+      } else {
+        // Scalar value: store directly
+        baselineEntry[col] = value;
+        modified = true;
+      }
+    }
+  }
+
+  // Save updated baseline
+  if (modified) {
+    await saveAppJsonBaseline(baseline);
+    log.dim('  Baseline updated with pushed changes');
+  }
+}

package/src/lib/config.js

@@ -8,6 +8,7 @@ const CONFIG_LOCAL_FILE = 'config.local.json';
 const CREDENTIALS_FILE = 'credentials.json';
 const COOKIES_FILE = 'cookies.txt';
 const SYNCHRONIZE_FILE = 'synchronize.json';
+const BASELINE_FILE = '.app.json';
 
 function dboDir() {
   return join(process.cwd(), DBO_DIR);
@@ -248,6 +249,43 @@ export async function loadEntityDirPreference(entityKey) {
   }
 }
 
+/**
+ * Save content extraction preferences for an entity type.
+ * Stores which base64 columns should be extracted as companion files and their extensions.
+ *
+ * @param {string} entityKey - Entity type (e.g., 'extension', 'site')
+ * @param {Object} extractions - Map of column names to extensions: { "String10": "css", "String7": false, ... }
+ *                                 false means user explicitly chose not to extract that column
+ */
+export async function saveEntityContentExtractions(entityKey, extractions) {
+  await mkdir(dboDir(), { recursive: true });
+  let existing = {};
+  try {
+    existing = JSON.parse(await readFile(configPath(), 'utf8'));
+  } catch { /* no existing config */ }
+  // Capitalize first letter for config key: extension → ExtensionContentExtractions
+  const configKey = entityKey.charAt(0).toUpperCase() + entityKey.slice(1) + 'ContentExtractions';
+  existing[configKey] = extractions;
+  await writeFile(configPath(), JSON.stringify(existing, null, 2) + '\n');
+}
+
+/**
+ * Load content extraction preferences for an entity type from .dbo/config.json.
+ *
+ * @param {string} entityKey - Entity type (e.g., 'extension', 'site')
+ * @returns {Object|null} - Map of column names to extensions, or null if not saved
+ */
+export async function loadEntityContentExtractions(entityKey) {
+  try {
+    const raw = await readFile(configPath(), 'utf8');
+    const config = JSON.parse(raw);
+    const configKey = entityKey.charAt(0).toUpperCase() + entityKey.slice(1) + 'ContentExtractions';
+    return config[configKey] || null;
+  } catch {
+    return null;
+  }
+}
+
 /**
  * Save user profile fields (FirstName, LastName, Email) into credentials.json.
  */
@@ -462,3 +500,35 @@ export async function ensureGitignore(patterns) {
   await writeFile(gitignorePath, content + addition);
   for (const p of toAdd) log.dim(`  Added ${p} to .gitignore`);
 }
+
+// ─── Baseline (.app.json) ─────────────────────────────────────────────────
+
+function baselinePath() {
+  return join(process.cwd(), BASELINE_FILE);
+}
+
+/**
+ * Check if baseline file (.app.json) exists.
+ */
+export async function hasBaseline() {
+  return exists(baselinePath());
+}
+
+/**
+ * Load .app.json baseline file (tracks server state for delta detection).
+ */
+export async function loadAppJsonBaseline() {
+  try {
+    const raw = await readFile(baselinePath(), 'utf8');
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Save .app.json baseline file.
+ */
+export async function saveAppJsonBaseline(data) {
+  await writeFile(baselinePath(), JSON.stringify(data, null, 2) + '\n');
+}

package/src/lib/delta.js

@@ -0,0 +1,204 @@
+import { readFile } from 'fs/promises';
+import { join, dirname } from 'path';
+import { log } from './logger.js';
+
+/**
+ * Load the baseline file (.app.json) from disk.
+ *
+ * @param {string} cwd - Current working directory
+ * @returns {Promise<Object|null>} - Baseline JSON or null if not found
+ */
+export async function loadBaseline(cwd = process.cwd()) {
+  const baselinePath = join(cwd, '.app.json');
+  try {
+    const raw = await readFile(baselinePath, 'utf8');
+    return JSON.parse(raw);
+  } catch (err) {
+    if (err.code === 'ENOENT') {
+      return null; // Baseline doesn't exist
+    }
+    log.warn(`Failed to parse .app.json: ${err.message}`);
+    return null;
+  }
+}
+
+/**
+ * Save baseline data to .app.json file.
+ *
+ * @param {Object} data - Baseline JSON data
+ * @param {string} cwd - Current working directory
+ */
+export async function saveBaseline(data, cwd = process.cwd()) {
+  const { writeFile } = await import('fs/promises');
+  const baselinePath = join(cwd, '.app.json');
+  await writeFile(baselinePath, JSON.stringify(data, null, 2), 'utf8');
+}
+
+/**
+ * Find a baseline entry by UID and entity type.
+ * Traverses the baseline's children hierarchy.
+ *
+ * @param {Object} baseline - The baseline JSON
+ * @param {string} entity - Entity type (e.g., "content", "output")
+ * @param {string} uid - Record UID
+ * @returns {Object|null} - Matching entry or null
+ */
+export function findBaselineEntry(baseline, entity, uid) {
+  if (!baseline || !baseline.children) {
+    return null;
+  }
+
+  const entityArray = baseline.children[entity];
+  if (!Array.isArray(entityArray)) {
+    return null;
+  }
+
+  return entityArray.find(item => item.UID === uid) || null;
+}
+
+/**
+ * Compare a file's content on disk against a baseline value.
+ *
+ * @param {string} filePath - Absolute path to file
+ * @param {string|null} baselineValue - Baseline value to compare against
+ * @returns {Promise<boolean>} - True if different, false if same
+ */
+export async function compareFileContent(filePath, baselineValue) {
+  try {
+    const currentContent = await readFile(filePath, 'utf8');
+
+    // Normalize line endings for comparison
+    const normalizedCurrent = currentContent.replace(/\r\n/g, '\n').trim();
+    const normalizedBaseline = (baselineValue || '').replace(/\r\n/g, '\n').trim();
+
+    return normalizedCurrent !== normalizedBaseline;
+  } catch (err) {
+    // If file doesn't exist or can't be read, consider it changed
+    log.warn(`Failed to read ${filePath}: ${err.message}`);
+    return true;
+  }
+}
+
+/**
+ * Detect which columns have changed by comparing current metadata against baseline.
+ *
+ * @param {string} metaPath - Path to metadata.json file
+ * @param {Object} baseline - The baseline JSON
+ * @param {Object} config - CLI config (for resolving file paths)
+ * @returns {Promise<string[]>} - Array of changed column names
+ */
+export async function detectChangedColumns(metaPath, baseline, config) {
+  // Load current metadata
+  const metaRaw = await readFile(metaPath, 'utf8');
+  const metadata = JSON.parse(metaRaw);
+
+  const { UID, _entity } = metadata;
+
+  // Find matching baseline entry
+  const baselineEntry = findBaselineEntry(baseline, _entity, UID);
+
+  // If no baseline exists for this record, all non-system columns are "changed"
+  if (!baselineEntry) {
+    return getAllUserColumns(metadata);
+  }
+
+  const changedColumns = [];
+  const metaDir = dirname(metaPath);
+
+  // Compare each column
+  for (const [columnName, columnValue] of Object.entries(metadata)) {
+    // Skip system columns and special fields
+    if (shouldSkipColumn(columnName)) {
+      continue;
+    }
+
+    // Check if value is a @reference
+    if (isReference(columnValue)) {
+      const refPath = resolveReferencePath(columnValue, metaDir);
+      const baselineValue = baselineEntry[columnName];
+
+      // Compare file content
+      const isDifferent = await compareFileContent(refPath, baselineValue);
+      if (isDifferent) {
+        changedColumns.push(columnName);
+      }
+    } else {
+      // Scalar value comparison
+      const currentValue = normalizeValue(columnValue);
+      const baselineValue = normalizeValue(baselineEntry[columnName]);
+
+      if (currentValue !== baselineValue) {
+        changedColumns.push(columnName);
+      }
+    }
+  }
+
+  return changedColumns;
+}
+
+/**
+ * Get all user-defined columns (non-system columns).
+ *
+ * @param {Object} metadata - Metadata object
+ * @returns {string[]} - Array of user column names
+ */
+function getAllUserColumns(metadata) {
+  return Object.keys(metadata).filter(col => !shouldSkipColumn(col));
+}
+
+/**
+ * Determine if a column should be skipped (system columns).
+ *
+ * @param {string} columnName - Column name
+ * @returns {boolean} - True if should skip
+ */
+function shouldSkipColumn(columnName) {
+  // Skip system columns starting with underscore, UID, and children
+  return columnName.startsWith('_') ||
+         columnName === 'UID' ||
+         columnName === 'children';
+}
+
+/**
+ * Check if a value is a @reference object.
+ *
+ * @param {*} value - Value to check
+ * @returns {boolean} - True if reference
+ */
+function isReference(value) {
+  return value &&
+         typeof value === 'object' &&
+         !Array.isArray(value) &&
+         value['@reference'] !== undefined;
+}
+
+/**
+ * Resolve a @reference path to absolute file path.
+ *
+ * @param {Object} reference - Reference object with @reference property
+ * @param {string} baseDir - Base directory containing metadata
+ * @returns {string} - Absolute file path
+ */
+function resolveReferencePath(reference, baseDir) {
+  const refPath = reference['@reference'];
+  return join(baseDir, refPath);
+}
+
+/**
+ * Normalize a value for comparison (handle null, undefined, etc.).
+ *
+ * @param {*} value - Value to normalize
+ * @returns {string} - Normalized string value
+ */
+function normalizeValue(value) {
+  if (value === null || value === undefined) {
+    return '';
+  }
+
+  // If it's still a @reference object in baseline, compare as string
+  if (isReference(value)) {
+    return JSON.stringify(value);
+  }
+
+  return String(value).trim();
+}

package/src/lib/dependencies.js

@@ -0,0 +1,131 @@
+/**
+ * Dependency management for entity synchronization.
+ * Ensures children are processed before parents to maintain referential integrity.
+ */
+
+/**
+ * Entity dependency hierarchy.
+ * Lower levels must be processed before higher levels.
+ * This ensures foreign key relationships are maintained (children before parents).
+ */
+export const ENTITY_DEPENDENCIES = {
+  // Level 1: Most dependent (children)
+  'output_value_filter': 1,
+  'output_value_entity_column_rel': 2,
+
+  // Level 2: Mid-level dependencies
+  'output_value': 2,
+
+  // Level 3: Parent entities
+  'output': 3,
+
+  // Default level 0 for entities not in this map
+};
+
+/**
+ * Get the dependency level for an entity type.
+ *
+ * @param {string} entity - Entity type name
+ * @returns {number} - Dependency level (0 = no dependencies, higher = more dependent)
+ */
+function getDependencyLevel(entity) {
+  return ENTITY_DEPENDENCIES[entity] || 0;
+}
+
+/**
+ * Build a dependency-ordered structure from synchronize.json data.
+ * Returns operations grouped by type and sorted by dependency level.
+ *
+ * @param {Object} synchronizeData - The synchronize.json contents
+ * @returns {Object} - Ordered structure: { delete: [], add: [], edit: [] }
+ */
+export function buildDependencyGraph(synchronizeData) {
+  if (!synchronizeData) {
+    return { delete: [], add: [], edit: [] };
+  }
+
+  const result = {
+    delete: sortByDependency(synchronizeData.delete || [], 'delete'),
+    add: sortByDependency(synchronizeData.add || [], 'add'),
+    edit: sortByDependency(synchronizeData.edit || [], 'edit'),
+  };
+
+  return result;
+}
+
+/**
+ * Sort entries by dependency level and UID.
+ * For delete operations: process parents before children (descending order)
+ * For add/edit operations: process children before parents (ascending order)
+ *
+ * @param {Array} entries - Array of sync entries
+ * @param {string} operationType - Operation type: 'delete', 'add', or 'edit'
+ * @returns {Array} - Sorted entries
+ */
+function sortByDependency(entries, operationType) {
+  if (!Array.isArray(entries) || entries.length === 0) {
+    return [];
+  }
+
+  // Group by entity type
+  const grouped = groupByEntity(entries);
+
+  // Sort entity types by dependency level
+  const entityTypes = Object.keys(grouped);
+  entityTypes.sort((a, b) => {
+    const levelA = getDependencyLevel(a);
+    const levelB = getDependencyLevel(b);
+
+    // Delete operations: parents before children (descending)
+    // Add/Edit operations: children before parents (ascending)
+    if (operationType === 'delete') {
+      return levelB - levelA; // Higher level first
+    } else {
+      return levelA - levelB; // Lower level first
+    }
+  });
+
+  // Flatten back to array, maintaining UID sort within each entity type
+  const sorted = [];
+  for (const entity of entityTypes) {
+    const entityEntries = grouped[entity];
+    // Sort by UID for consistent ordering
+    entityEntries.sort((a, b) => (a.UID || '').localeCompare(b.UID || ''));
+    sorted.push(...entityEntries);
+  }
+
+  return sorted;
+}
+
+/**
+ * Group entries by entity type.
+ *
+ * @param {Array} entries - Array of sync entries
+ * @returns {Object} - Entries grouped by entity: { entityType: [...entries] }
+ */
+function groupByEntity(entries) {
+  const groups = {};
+
+  for (const entry of entries) {
+    const entity = entry.entity || entry._entity || 'unknown';
+    if (!groups[entity]) {
+      groups[entity] = [];
+    }
+    groups[entity].push(entry);
+  }
+
+  return groups;
+}
+
+/**
+ * Sort entries by UID for consistent ordering within an entity type.
+ *
+ * @param {Array} entries - Array of entries
+ * @returns {Array} - Sorted entries
+ */
+export function sortEntriesByUid(entries) {
+  if (!Array.isArray(entries)) {
+    return [];
+  }
+  return entries.slice().sort((a, b) => (a.UID || '').localeCompare(b.UID || ''));
+}

package/src/plugins/claudecommands/dbo.md

@@ -37,7 +37,7 @@ Here are the available commands:
 | rm        | Remove a file and stage server deletion           |
 | deploy    | Deploy via manifest                              |
 | cache     | Manage cache                                     |
-| install   | Install or upgrade CLI, plugins, Claude commands |
+| install   | Install or upgrade CLI, plugins, Claude commands (shorthand: `i`) |
 
 Just tell me what you'd like to do and I'll help you build the right command!
 
@@ -80,9 +80,9 @@ Available subcommands:
 - `rm -f <path>` — Remove without confirmation prompts
 - `rm --keep-local <path>` — Stage server deletions without deleting local files/directories
 - `deploy [name]` — Deploy via dbo.deploy.json manifest
-- `install` — Install or upgrade CLI, plugins, or Claude commands
-- `install dbo` or `install dbo@latest` — Install/upgrade the CLI from npm
-- `install dbo@0.4.1` — Install a specific CLI version
+- `install` (alias: `i`) — Install or upgrade CLI, plugins, or Claude commands
+- `i dbo` or `i dbo@latest` — Install/upgrade the CLI from npm
+- `i dbo@0.4.1` — Install a specific CLI version
 - `install /path/to/src` — Install CLI from local source
 - `install plugins` — Install/upgrade Claude command plugins
 - `install plugins --global` — Install plugins to `~/.claude/commands/` (shared across projects)