@dboio/cli 0.11.3 → 0.13.2

package/src/commands/run.js

@@ -0,0 +1,81 @@
+// src/commands/run.js
+import { Command } from 'commander';
+import { loadScripts, loadScriptsLocal, loadConfig, loadAppConfig } from '../lib/config.js';
+import { mergeScriptsConfig, buildHookEnv, runHook } from '../lib/scripts.js';
+import { log } from '../lib/logger.js';
+
+export const runCommand = new Command('run')
+  .description('Run a named script from .dbo/scripts.json (like npm run)')
+  .argument('[script-name]', 'Name of the script to run (omit to list all scripts)')
+  .action(async (scriptName, options) => {
+    try {
+      const base = await loadScripts();
+      const local = await loadScriptsLocal();
+
+      if (!base && !local) {
+        log.error('No .dbo/scripts.json found');
+        process.exit(1);
+      }
+
+      const config = mergeScriptsConfig(base, local);
+      const scripts = config.scripts || {};
+
+      if (!scriptName) {
+        // List all script names
+        const allNames = Object.keys(scripts);
+        if (allNames.length === 0) {
+          log.info('No scripts defined in .dbo/scripts.json');
+          return;
+        }
+        log.info('Available scripts:');
+        for (const name of allNames) {
+          const value = scripts[name];
+          const preview = Array.isArray(value) ? value[0] : (value === false ? '(skip)' : String(value));
+          log.plain(`  ${name}: ${preview}`);
+        }
+        return;
+      }
+
+      if (!(scriptName in scripts)) {
+        log.error(`Script "${scriptName}" not found in .dbo/scripts.json`);
+        process.exit(1);
+      }
+
+      const cfg = await loadConfig();
+      const app = await loadAppConfig();
+      const appConfig = { ...app, domain: cfg.domain };
+      const env = buildHookEnv('', scriptName, appConfig);
+
+      // Pre/post auto-resolution
+      const preKey = `pre${scriptName}`;
+      const postKey = `post${scriptName}`;
+
+      if (preKey in scripts) {
+        log.dim(`  Running ${preKey}...`);
+        const result = await runHook(scripts[preKey], env, { cwd: process.cwd() });
+        if (!result.skipped && result.exitCode !== 0 && result.exitCode !== null) {
+          log.error(`Script "${preKey}" failed with exit code ${result.exitCode}`);
+          process.exit(result.exitCode);
+        }
+      }
+
+      log.dim(`  Running ${scriptName}...`);
+      const result = await runHook(scripts[scriptName], env, { cwd: process.cwd() });
+      if (!result.skipped && result.exitCode !== 0 && result.exitCode !== null) {
+        log.error(`Script "${scriptName}" failed with exit code ${result.exitCode}`);
+        process.exit(result.exitCode);
+      }
+
+      if (postKey in scripts) {
+        log.dim(`  Running ${postKey}...`);
+        const postResult = await runHook(scripts[postKey], env, { cwd: process.cwd() });
+        if (!postResult.skipped && postResult.exitCode !== 0 && postResult.exitCode !== null) {
+          log.error(`Script "${postKey}" failed with exit code ${postResult.exitCode}`);
+          process.exit(postResult.exitCode);
+        }
+      }
+    } catch (err) {
+      log.error(err.message);
+      process.exit(1);
+    }
+  });

package/src/lib/client.js

@@ -124,15 +124,12 @@ export class DboClient {
   }
 
   /**
-   * Clear the server-side cache so that subsequent GET requests return fresh data.
-   * Called before comparison fetches (toe-stepping, diff) and after POST submissions.
+   * No-op placeholder. Server-side cache voiding (/?voidcache=true) has been
+   * disabled as it was causing server issues. Callers remain unchanged so the
+   * hook can be re-enabled later if needed.
    */
   async voidCache() {
-    try {
-      const baseUrl = await this.getBaseUrl();
-      if (this.verbose) log.verbose(`VoidCache: ${baseUrl}/?voidcache=true`);
-      await this.request('/?voidcache=true');
-    } catch { /* best-effort — don't block on failure */ }
+    // intentionally empty
   }
 
   /**

package/src/lib/config.js

@@ -9,6 +9,8 @@ const CREDENTIALS_FILE = 'credentials.json';
 const COOKIES_FILE = 'cookies.txt';
 const SYNCHRONIZE_FILE = 'synchronize.json';
 const BASELINE_FILE = '.app_baseline.json';
+const SCRIPTS_FILE = 'scripts.json';
+const SCRIPTS_LOCAL_FILE = 'scripts.local.json';
 
 function dboDir() {
   return join(process.cwd(), DBO_DIR);
@@ -897,3 +899,40 @@ export async function loadExtensionDocumentationMDPlacement() {
     return cfg.ExtensionDocumentationMDPlacement || null;
   } catch { return null; }
 }
+
+// ─── Script Hooks (.dbo/scripts.json, .dbo/scripts.local.json) ────────────
+
+function scriptsPath() {
+  return join(dboDir(), SCRIPTS_FILE);
+}
+
+function scriptsLocalPath() {
+  return join(dboDir(), SCRIPTS_LOCAL_FILE);
+}
+
+/**
+ * Load .dbo/scripts.json. Returns parsed object or null if missing.
+ * Throws SyntaxError with clear message if JSON is malformed.
+ */
+export async function loadScripts() {
+  const path = scriptsPath();
+  let raw;
+  try { raw = await readFile(path, 'utf8'); } catch { return null; }
+  try { return JSON.parse(raw); } catch (err) {
+    throw new SyntaxError(`Invalid JSON in .dbo/scripts.json: ${err.message}`);
+  }
+}
+
+/**
+ * Load .dbo/scripts.local.json (gitignored per-user overrides).
+ * Returns parsed object or null if missing.
+ * Throws SyntaxError with clear message if JSON is malformed.
+ */
+export async function loadScriptsLocal() {
+  const path = scriptsLocalPath();
+  let raw;
+  try { raw = await readFile(path, 'utf8'); } catch { return null; }
+  try { return JSON.parse(raw); } catch (err) {
+    throw new SyntaxError(`Invalid JSON in .dbo/scripts.local.json: ${err.message}`);
+  }
+}

package/src/lib/delta.js

@@ -81,7 +81,13 @@ export async function compareFileContent(filePath, baselineValue) {
 
     return normalizedCurrent !== normalizedBaseline;
   } catch (err) {
-    // If file doesn't exist or can't be read, consider it changed
+    if (err.code === 'ENOENT') {
+      // File doesn't exist on disk — nothing to push regardless of baseline.
+      // This commonly happens with CustomSQL companion files that clone
+      // didn't extract (e.g. non-CustomSQL type with server-side content).
+      return false;
+    }
+    // Other read errors — treat as changed to be safe
     log.warn(`Failed to read ${filePath}: ${err.message}`);
     return true;
   }

package/src/lib/diff.js

@@ -155,7 +155,7 @@ export async function findMetadataFiles(dir, ig) {
       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')) {
+    } else if (entry.name.endsWith('.metadata.json') && !entry.name.startsWith('__WILL_DELETE__')) {
       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('~')) {
@@ -217,6 +217,14 @@ export async function hasLocalModifications(metaPath, config = {}) {
     const metaDir = dirname(metaPath);
     const contentCols = meta._contentColumns || [];
 
+    // Load baseline for content comparison fallback (build tools can
+    // rewrite files with identical content, bumping mtime without any
+    // real change — e.g. sass recompile producing the same CSS).
+    const baseline = _cachedBaseline || await loadAppJsonBaseline();
+    const baselineEntry = baseline
+      ? findBaselineEntry(baseline, meta._entity, meta.UID)
+      : null;
+
     for (const col of contentCols) {
       const ref = meta[col];
       if (ref && String(ref).startsWith('@')) {
@@ -224,6 +232,20 @@ export async function hasLocalModifications(metaPath, config = {}) {
         try {
           const contentStat = await stat(contentPath);
           if (contentStat.mtime.getTime() > syncTime + 2000) {
+            // mtime says modified — verify with content comparison against
+            // baseline to rule out false positives from build tools.
+            if (baselineEntry && baselineEntry[col] != null) {
+              try {
+                const localContent = await readFile(contentPath, 'utf8');
+                const normalizedLocal = localContent.replace(/\r\n/g, '\n').trimEnd();
+                const normalizedBaseline = String(baselineEntry[col]).replace(/\r\n/g, '\n').trimEnd();
+                if (normalizedLocal === normalizedBaseline) {
+                  // Content identical — false positive mtime bump, fix timestamp
+                  await setFileTimestamps(contentPath, meta._CreatedOn, meta._LastUpdated, serverTz);
+                  continue;
+                }
+              } catch { /* read failed — treat as modified */ }
+            }
             return true;
           }
         } catch { /* missing file */ }
@@ -687,7 +709,7 @@ function buildChangeMessage(recordName, serverRecord, config, options = {}) {
  */
 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' })
+    ? d.toLocaleString('en-US', { month: 'short', day: 'numeric', hour: '2-digit', minute: '2-digit', second: '2-digit' })
     : null;
   const s = fmt(serverDate);
   const l = fmt(localDate);

package/src/lib/filenames.js

@@ -3,7 +3,7 @@
  * All entity files use <basename>~<uid>.<ext> as the local filename.
  */
 
-import { rename, writeFile } from 'fs/promises';
+import { rename, unlink, writeFile, readFile, readdir } from 'fs/promises';
 import { join, dirname, basename, extname } from 'path';
 
 /**
@@ -20,6 +20,65 @@ export function buildUidFilename(name, uid, ext = '') {
   return ext ? `${base}.${ext}` : base;
 }
 
+/**
+ * Build the natural companion filename for a content record.
+ * No ~UID suffix is embedded. Implements Name/Path/Extension priority.
+ *
+ * Priority:
+ *   1. Name is null → last segment of Path (includes ext if present)
+ *   2. Name present + Extension present → name.ext (lowercased ext, double-ext stripped)
+ *   3. Name present + Extension null + Path last segment matches Name with ext → path segment
+ *   4. Name present + Extension null + no usable Path → just Name (no ext)
+ *   5. No Name and no Path → fallback (typically UID)
+ *
+ * @param {Object} record   - Server record with Name, Path, Extension fields
+ * @param {string} fallback - Value when nothing else is available (e.g. record UID)
+ * @returns {string}
+ */
+export function buildContentFileName(record, fallback = 'untitled') {
+  const { Name, Path, Extension } = record;
+
+  // Priority 1: Name is null → use last segment of Path
+  if (!Name) {
+    if (Path) {
+      const segs = String(Path).replace(/\\/g, '/').split('/').filter(Boolean);
+      const last = segs[segs.length - 1];
+      if (last) return last;
+    }
+    return fallback;
+  }
+
+  const name = String(Name);
+
+  // Priority 2: Extension present → name.ext
+  if (Extension) {
+    const ext = String(Extension).toLowerCase();
+    const dotExt = `.${ext}`;
+    // Strip double extension (Name="colors.css", Extension="css" → "colors.css")
+    const nameClean = name.toLowerCase().endsWith(dotExt)
+      ? name.slice(0, -dotExt.length)
+      : name;
+    return `${nameClean}.${ext}`;
+  }
+
+  // Priority 3: Extension null → check if Path last segment provides the extension
+  if (Path) {
+    const segs = String(Path).replace(/\\/g, '/').split('/').filter(Boolean);
+    const last = segs[segs.length - 1];
+    if (last) {
+      const lastExt = extname(last);
+      if (lastExt) {
+        const lastBase = basename(last, lastExt);
+        // If Path's last segment base matches Name, treat it as the canonical filename+ext
+        if (lastBase === name || last === name) return last;
+      }
+    }
+  }
+
+  // Priority 4: No extension available → just name
+  return name;
+}
+
 /**
  * Strip the ~<uid> portion from a local filename.
  * Used when the local file is "logo~def456.png" but the upload should send "logo.png".
@@ -58,6 +117,55 @@ export function detectLegacyDotUid(filename) {
   return match ? { name: match[1], uid: match[2] } : null;
 }
 
+/**
+ * Find the metadata file that references a given companion file via @reference.
+ *
+ * Lookup order:
+ *   1. Direct: base.metadata.json (natural name match)
+ *   2. Scan: all *.metadata.json in the same directory, check @reference values
+ *
+ * @param {string} companionPath - Absolute path to the companion file
+ * @returns {Promise<string|null>} - Absolute path to the metadata file, or null
+ */
+export async function findMetadataForCompanion(companionPath) {
+  const dir = dirname(companionPath);
+  const companionName = basename(companionPath);
+  const ext = extname(companionName);
+  const base = basename(companionName, ext);
+
+  // 1. Direct match: base.metadata.json
+  const directMeta = join(dir, `${base}.metadata.json`);
+  try {
+    await readFile(directMeta, 'utf8');
+    return directMeta;
+  } catch { /* not found */ }
+
+  // 2. Scan sibling *.metadata.json files for @reference match
+  let entries;
+  try { entries = await readdir(dir); } catch { return null; }
+
+  for (const entry of entries) {
+    if (!entry.endsWith('.metadata.json')) continue;
+    const metaPath = join(dir, entry);
+    try {
+      const meta = JSON.parse(await readFile(metaPath, 'utf8'));
+      const cols = [...(meta._contentColumns || [])];
+      if (meta._mediaFile) cols.push('_mediaFile');
+      for (const col of cols) {
+        const ref = meta[col];
+        if (!ref || !String(ref).startsWith('@')) continue;
+        const refName = String(ref).substring(1);
+        // Match both relative and root-relative (@/) references
+        if (refName === companionName || refName === `/${companionName}`) {
+          return metaPath;
+        }
+      }
+    } catch { /* skip unreadable */ }
+  }
+
+  return null;
+}
+
 /**
  * Rename a file pair (content + metadata) to the ~uid convention after server assigns a UID.
  * Updates @reference values inside the metadata file.
@@ -75,68 +183,40 @@ export async function renameToUidConvention(meta, metaPath, uid, lastUpdated, se
   const metaBase = basename(metaPath, '.metadata.json'); // e.g. "colors" or "logo.png"
 
   if (hasUidInFilename(metaBase, uid)) {
-    return { newMetaPath: metaPath, newFilePath: null }; // already renamed
+    return { newMetaPath: metaPath, newFilePath: null, updatedMeta: meta };
   }
 
+  // Compute new metadata filename with ~UID
   // For media files: metaBase = "logo.png", newBase = "logo~uid.png"
   // For content files: metaBase = "colors", newBase = "colors~uid"
   const metaBaseExt = extname(metaBase); // ".png" for media metadata, "" for content metadata
   let newMetaBase;
   if (metaBaseExt) {
-    // Media: "logo.png" → "logo~uid.png"
     const nameWithoutExt = metaBase.slice(0, -metaBaseExt.length);
     newMetaBase = `${buildUidFilename(nameWithoutExt, uid)}${metaBaseExt}`;
   } else {
-    // Content/entity-dir: "colors" → "colors~uid"
     newMetaBase = buildUidFilename(metaBase, uid);
   }
 
   const newMetaPath = join(metaDir, `${newMetaBase}.metadata.json`);
 
-  // Update metadata in memory
-  meta.UID = uid;
-  const updatedMeta = { ...meta };
-
-  // Rename content files referenced in _contentColumns and _mediaFile
-  const contentCols = [...(meta._contentColumns || [])];
-  if (meta._mediaFile) contentCols.push('_mediaFile');
-
-  let newFilePath = null;
-
-  for (const col of contentCols) {
-    const ref = meta[col];
-    if (!ref || !String(ref).startsWith('@')) continue;
-
-    const oldRefFile = String(ref).substring(1);
-    const oldFilePath = join(metaDir, oldRefFile);
-
-    // Compute new filename: insert uid
-    const oldExt = extname(oldRefFile); // ".css", ".png"
-    const oldBase = basename(oldRefFile, oldExt); // "colors" or "logo"
-    const newRefBase = buildUidFilename(oldBase, uid);
-    const newRefFile = oldExt ? `${newRefBase}${oldExt}` : newRefBase;
-    const newRefPath = join(metaDir, newRefFile);
-
-    try {
-      await rename(oldFilePath, newRefPath);
-      updatedMeta[col] = `@${newRefFile}`;
-      if (!newFilePath) newFilePath = newRefPath;
-    } catch {
-      // File may already be renamed or may not exist
-    }
-  }
+  // Update only the UID field; @reference values are UNCHANGED (companions keep natural names)
+  const updatedMeta = { ...meta, UID: uid };
 
   // Write updated metadata to new path
   await writeFile(newMetaPath, JSON.stringify(updatedMeta, null, 2) + '\n');
 
-  // Remove old metadata file if it's different from newMetaPath
+  // Remove old metadata file (new content already written to newMetaPath above)
   if (metaPath !== newMetaPath) {
-    try { await rename(metaPath, newMetaPath); } catch { /* already written above */ }
+    try { await unlink(metaPath); } catch { /* old file already gone */ }
   }
 
-  // Restore timestamps
+  // Restore timestamps for metadata file and companions (companions are not renamed)
   if (serverTz && lastUpdated) {
     const { setFileTimestamps } = await import('./timestamps.js');
+    try { await setFileTimestamps(newMetaPath, lastUpdated, lastUpdated, serverTz); } catch {}
+    const contentCols = [...(meta._contentColumns || [])];
+    if (meta._mediaFile) contentCols.push('_mediaFile');
     for (const col of contentCols) {
       const ref = updatedMeta[col];
       if (ref && String(ref).startsWith('@')) {
@@ -144,8 +224,7 @@ export async function renameToUidConvention(meta, metaPath, uid, lastUpdated, se
         try { await setFileTimestamps(fp, lastUpdated, lastUpdated, serverTz); } catch {}
       }
     }
-    try { await setFileTimestamps(newMetaPath, lastUpdated, lastUpdated, serverTz); } catch {}
   }
 
-  return { newMetaPath, newFilePath, updatedMeta };
+  return { newMetaPath, newFilePath: null, updatedMeta };
 }

package/src/lib/ignore.js

@@ -44,6 +44,12 @@ package-lock.json
 src/
 test/
 
+# Scaffold directories (managed by server, not user content)
+trash/
+
+# Build artifacts
+*.map
+
 # Documentation (repo scaffolding)
 SETUP.md
 README.md

package/src/lib/input-parser.js

@@ -48,6 +48,15 @@ export async function buildInputBody(dataExpressions, extraParams = {}) {
   return parts.join('&');
 }
 
+/**
+ * Encode a DBO input key for URL-encoded form data.
+ * Preserves : and ; which are structural separators in DBO syntax
+ * (e.g. "RowID:del123;entity:content"), but encodes everything else.
+ */
+function encodeDboKey(key) {
+  return encodeURIComponent(key).replace(/%3A/gi, ':').replace(/%3B/gi, ';');
+}
+
 async function encodeInputExpression(expr) {
   // Check if value part contains @filepath
   // Format: key=value or key@filepath
@@ -68,15 +77,15 @@ async function encodeInputExpression(expr) {
     const key = expr.substring(0, atIdx);
     const filePath = expr.substring(atIdx + 1);
     const content = await readFile(filePath, 'utf8');
-    return `${encodeURIComponent(key)}=${encodeURIComponent(content)}`;
+    return `${encodeDboKey(key)}=${encodeURIComponent(content)}`;
   } else if (eqIdx !== -1) {
     // =value syntax: direct value
     const key = expr.substring(0, eqIdx);
     const value = expr.substring(eqIdx + 1);
-    return `${encodeURIComponent(key)}=${encodeURIComponent(value)}`;
+    return `${encodeDboKey(key)}=${encodeURIComponent(value)}`;
   } else {
-    // No value separator, encode the whole thing
-    return encodeURIComponent(expr);
+    // No value separator, encode the whole thing (preserve DBO separators)
+    return encodeDboKey(expr);
   }
 }