@dboio/cli 0.11.4 → 0.15.0

package/src/lib/filenames.js

@@ -1,9 +1,10 @@
 /**
- * Filename convention helpers for the UID tilde convention.
- * All entity files use <basename>~<uid>.<ext> as the local filename.
+ * Filename convention helpers for the metadata~uid convention.
+ * Metadata files: name.metadata~uid.json
+ * Companion files: natural names, no UID embedded.
  */
 
-import { rename, writeFile } from 'fs/promises';
+import { rename, unlink, writeFile, readFile, readdir } from 'fs/promises';
 import { join, dirname, basename, extname } from 'path';
 
 /**
@@ -20,6 +21,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 +118,117 @@ export function detectLegacyDotUid(filename) {
   return match ? { name: match[1], uid: match[2] } : null;
 }
 
+/**
+ * Build the new-convention metadata filename.
+ * Format: <naturalBase>.metadata~<uid>.json
+ *
+ * For content records: naturalBase = "colors" → "colors.metadata~abc123.json"
+ * For media records:   naturalBase = "logo.png" → "logo.png.metadata~abc123.json"
+ * For output records:  naturalBase = "Sales" → "Sales.metadata~abc123.json"
+ *
+ * @param {string} naturalBase - Name without any ~uid (may include media extension)
+ * @param {string} uid         - Server-assigned UID
+ * @returns {string}
+ */
+export function buildMetaFilename(naturalBase, uid) {
+  return `${naturalBase}.metadata~${uid}.json`;
+}
+
+/**
+ * Test whether a filename is a metadata file (new or legacy format).
+ *
+ * New format:    name.metadata~uid.json
+ * Legacy format: name~uid.metadata.json  (also accepted during migration)
+ *
+ * @param {string} filename
+ * @returns {boolean}
+ */
+export function isMetadataFile(filename) {
+  return /\.metadata~[a-z0-9]+\.json$/i.test(filename)   // new: name.metadata~uid.json
+    || filename.endsWith('.metadata.json')                 // legacy + pre-UID temp files
+    || /\.[a-z0-9]{10,}\.metadata\.json$/i.test(filename); // legacy dot-separated: name.uid.metadata.json
+}
+
+/**
+ * Parse a new-format metadata filename into its components.
+ * Returns null for legacy-format filenames (use detectLegacyTildeMetadata for those).
+ *
+ * @param {string} filename - e.g. "colors.metadata~abc123.json"
+ * @returns {{ naturalBase: string, uid: string } | null}
+ */
+export function parseMetaFilename(filename) {
+  const m = filename.match(/^(.+)\.metadata~([a-z0-9]+)\.json$/i);
+  return m ? { naturalBase: m[1], uid: m[2] } : null;
+}
+
+/**
+ * Detect whether a filename uses the legacy tilde convention:
+ *   <name>~<uid>.metadata.json  OR  <name>~<uid>.<ext>.metadata.json
+ * where uid is ≥10 lowercase alphanumeric characters.
+ *
+ * Returns { naturalBase, uid } or null.
+ */
+export function detectLegacyTildeMetadata(filename) {
+  // Case 1: name~uid.metadata.json (content/entity metadata)
+  const m1 = filename.match(/^(.+)~([a-z0-9]{10,})\.metadata\.json$/);
+  if (m1) return { naturalBase: m1[1], uid: m1[2] };
+
+  // Case 2: name~uid.ext.metadata.json (media metadata)
+  const m2 = filename.match(/^(.+)~([a-z0-9]{10,})\.([a-z0-9]+)\.metadata\.json$/);
+  if (m2) return { naturalBase: `${m2[1]}.${m2[3]}`, uid: m2[2] };
+
+  return 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);
+
+  let entries;
+  try { entries = await readdir(dir); } catch { return null; }
+
+  // 1. Fast path: match naturalBase of new-format metadata files
+  for (const entry of entries) {
+    const parsed = parseMetaFilename(entry);
+    if (parsed && (parsed.naturalBase === base || parsed.naturalBase === companionName)) {
+      return join(dir, entry);
+    }
+  }
+
+  // 2. Scan all metadata files (new + legacy) for @reference match
+  for (const entry of entries) {
+    if (!isMetadataFile(entry)) 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);
+        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.
@@ -72,71 +243,45 @@ export function detectLegacyDotUid(filename) {
  */
 export async function renameToUidConvention(meta, metaPath, uid, lastUpdated, serverTz) {
   const metaDir = dirname(metaPath);
-  const metaBase = basename(metaPath, '.metadata.json'); // e.g. "colors" or "logo.png"
+  const metaFilename = basename(metaPath);
 
-  if (hasUidInFilename(metaBase, uid)) {
-    return { newMetaPath: metaPath, newFilePath: null }; // already renamed
+  // Already in new format — nothing to do
+  if (parseMetaFilename(metaFilename)?.uid === uid) {
+    return { newMetaPath: metaPath, newFilePath: null, updatedMeta: meta };
   }
 
-  // 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}`;
+  // Determine naturalBase from the temp/old metadata filename
+  // Temp format from add.js: "colors.metadata.json" → naturalBase = "colors"
+  // Old tilde format: "colors~uid.metadata.json" → naturalBase = "colors"
+  let naturalBase;
+  const legacyParsed = detectLegacyTildeMetadata(metaFilename);
+  if (legacyParsed) {
+    naturalBase = legacyParsed.naturalBase;
+  } else if (metaFilename.endsWith('.metadata.json')) {
+    naturalBase = metaFilename.slice(0, -'.metadata.json'.length);
   } else {
-    // Content/entity-dir: "colors" → "colors~uid"
-    newMetaBase = buildUidFilename(metaBase, uid);
+    naturalBase = basename(metaFilename, '.json');
   }
 
-  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;
+  const newMetaPath = join(metaDir, buildMetaFilename(naturalBase, uid));
 
-  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 +289,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);
   }
 }
 

package/src/lib/scaffold.js

@@ -2,7 +2,7 @@ import { mkdir, stat, readFile, writeFile, access } from 'fs/promises';
 import { join } from 'path';
 import { SCAFFOLD_DIRS } from './structure.js';
 import { log } from './logger.js';
-import { applyTrashIcon } from './folder-icon.js';
+import { applyTrashIcon } from './tagging.js';
 
 /**
  * Scaffold the standard DBO project directory structure in cwd.

package/src/lib/scripts.js

@@ -0,0 +1,232 @@
+// src/lib/scripts.js
+import { spawn } from 'child_process';
+
+const HOOK_NAMES = ['prebuild', 'build', 'postbuild', 'prepush', 'push', 'postpush'];
+
+/**
+ * Merge scripts.json with scripts.local.json.
+ * scripts.local.json keys take precedence over scripts.json at each scope level.
+ *
+ * @param {object|null} base   - Parsed scripts.json (or null)
+ * @param {object|null} local  - Parsed scripts.local.json (or null)
+ * @returns {object} - Merged config with { scripts, targets, entities } keys
+ */
+export function mergeScriptsConfig(base, local) {
+  const merged = {
+    scripts: Object.assign({}, base?.scripts, local?.scripts),
+    targets: {},
+    entities: {},
+  };
+  // Merge target entries: normalize path separators, local overrides base per-hook
+  const allTargetKeys = new Set([
+    ...Object.keys(base?.targets || {}),
+    ...Object.keys(local?.targets || {}),
+  ]);
+  for (const key of allTargetKeys) {
+    const normalKey = key.replace(/\\/g, '/');
+    merged.targets[normalKey] = Object.assign(
+      {},
+      base?.targets?.[key],
+      local?.targets?.[key]
+    );
+  }
+  // Merge entity entries: local overrides base per-hook
+  const allEntityKeys = new Set([
+    ...Object.keys(base?.entities || {}),
+    ...Object.keys(local?.entities || {}),
+  ]);
+  for (const key of allEntityKeys) {
+    merged.entities[key] = Object.assign(
+      {},
+      base?.entities?.[key],
+      local?.entities?.[key]
+    );
+  }
+  return merged;
+}
+
+/**
+ * Resolve hooks for a given file path and entity type.
+ * Resolution order (highest priority first): target → entity → global scripts.
+ * Resolution is per-hook — a target can override 'build' while global 'prepush' still applies.
+ *
+ * @param {string} filePath     - Relative file path from project root (forward slashes)
+ * @param {string} entityType   - Entity type string (e.g., 'content', 'extension.control')
+ * @param {object} config       - Merged scripts config from mergeScriptsConfig()
+ * @returns {object} - Resolved hook map: { prebuild, build, postbuild, prepush, push, postpush }
+ *                     Each value is the resolved hook (string|string[]|false|true|undefined)
+ */
+export function resolveHooks(filePath, entityType, config) {
+  const normalPath = filePath.replace(/\\/g, '/');
+  const resolved = {};
+
+  for (const hook of HOOK_NAMES) {
+    let value;
+
+    // 1. Global scripts (lowest priority)
+    if (config.scripts && hook in config.scripts) {
+      value = config.scripts[hook];
+    }
+
+    // 2. Entity-level: check both 'extension' (base) and 'extension.control' (specific)
+    // More-specific descriptor match overrides base entity match
+    const [baseEntity] = entityType.split('.');
+    if (baseEntity !== entityType && config.entities[baseEntity] && hook in config.entities[baseEntity]) {
+      value = config.entities[baseEntity][hook];
+    }
+    if (config.entities[entityType] && hook in config.entities[entityType]) {
+      value = config.entities[entityType][hook];
+    }
+
+    // 3. Target-level (highest priority): exact path match OR directory prefix match
+    for (const [targetKey, targetHooks] of Object.entries(config.targets)) {
+      const isDir = targetKey.endsWith('/');
+      const matches = isDir
+        ? normalPath.startsWith(targetKey) || normalPath.startsWith(targetKey.slice(0, -1) + '/')
+        : normalPath === targetKey;
+      if (matches && targetHooks && hook in targetHooks) {
+        value = targetHooks[hook];
+      }
+    }
+
+    if (value !== undefined) resolved[hook] = value;
+  }
+
+  return resolved;
+}
+
+/**
+ * Execute a single hook value.
+ * - string: run as shell command
+ * - string[]: run sequentially, fail-fast on first non-zero exit
+ * - false: no-op (returns { skipped: false })
+ * - true/undefined: no-op (use default behavior)
+ *
+ * @param {string|string[]|boolean|undefined} hookValue
+ * @param {object} env  - Environment variables to inject (merged with process.env)
+ * @param {object} [opts]
+ * @param {string} [opts.cwd]  - Working directory (default: process.cwd())
+ * @returns {Promise<{ skipped: boolean, exitCode: number|null }>}
+ */
+export async function runHook(hookValue, env, { cwd = process.cwd() } = {}) {
+  if (hookValue === false) return { skipped: false, exitCode: null };
+  if (hookValue === true || hookValue === undefined) return { skipped: true, exitCode: null };
+
+  const commands = Array.isArray(hookValue) ? hookValue : [hookValue];
+  const mergedEnv = { ...process.env, ...env };
+
+  for (const cmd of commands) {
+    const exitCode = await spawnShell(cmd, mergedEnv, cwd);
+    if (exitCode !== 0) {
+      return { skipped: false, exitCode };
+    }
+  }
+  return { skipped: false, exitCode: 0 };
+}
+
+/**
+ * Spawn a shell command and wait for it to exit.
+ * Uses /bin/sh -c on Unix, cmd.exe /c on Windows.
+ * Inherits stdio so output streams directly to terminal.
+ *
+ * @param {string} cmd
+ * @param {object} env
+ * @param {string} cwd
+ * @returns {Promise<number>} exit code
+ */
+function spawnShell(cmd, env, cwd) {
+  return new Promise((resolve) => {
+    const isWin = process.platform === 'win32';
+    const shell = isWin ? 'cmd.exe' : '/bin/sh';
+    const args = isWin ? ['/c', cmd] : ['-c', cmd];
+    const proc = spawn(shell, args, { env, cwd, stdio: 'inherit' });
+    proc.on('close', (code) => resolve(code ?? 1));
+    proc.on('error', () => resolve(1));
+  });
+}
+
+/**
+ * Build env vars to inject into hook processes for a given target file.
+ *
+ * @param {string} filePath   - Relative file path from project root
+ * @param {string} entityType - Entity type string
+ * @param {object} appConfig  - From loadAppConfig(): { domain, AppShortName, AppUID }
+ * @returns {object} env vars
+ */
+export function buildHookEnv(filePath, entityType, appConfig) {
+  return {
+    DBO_TARGET: filePath,
+    DBO_ENTITY: entityType,
+    DBO_DOMAIN: appConfig?.domain || '',
+    DBO_APP: appConfig?.AppShortName || '',
+    DBO_APP_UID: appConfig?.AppUID || '',
+  };
+}
+
+/**
+ * Run the full build lifecycle for a target: prebuild → build → postbuild.
+ * Returns false if any hook fails (non-zero exit), true if all succeed or are skipped.
+ *
+ * @param {object} hooks      - Resolved hooks from resolveHooks()
+ * @param {object} env        - Env vars from buildHookEnv()
+ * @param {string} [cwd]      - Working directory
+ * @returns {Promise<boolean>} true = success/skipped, false = failure
+ */
+export async function runBuildLifecycle(hooks, env, cwd) {
+  for (const name of ['prebuild', 'build', 'postbuild']) {
+    if (!(name in hooks)) continue;
+    const result = await runHook(hooks[name], env, { cwd });
+    if (!result.skipped && result.exitCode !== 0 && result.exitCode !== null) {
+      return false;
+    }
+  }
+  return true;
+}
+
+/**
+ * Run the push lifecycle for a target: prepush → (push or default) → postpush.
+ * Returns:
+ *   { runDefault: true }  — caller should run the default push
+ *   { runDefault: false } — push was handled by custom hook or push: false
+ *   { failed: true }      — a hook failed; abort
+ *
+ * @param {object} hooks      - Resolved hooks
+ * @param {object} env        - Env vars
+ * @param {string} [cwd]      - Working directory
+ */
+export async function runPushLifecycle(hooks, env, cwd) {
+  // prepush
+  if ('prepush' in hooks) {
+    const result = await runHook(hooks['prepush'], env, { cwd });
+    if (!result.skipped && result.exitCode !== 0 && result.exitCode !== null) {
+      return { failed: true };
+    }
+  }
+
+  // push
+  let runDefault = true;
+  if ('push' in hooks) {
+    const pushVal = hooks['push'];
+    if (pushVal === false) {
+      runDefault = false;
+    } else if (pushVal !== true && pushVal !== undefined) {
+      // Custom push command overrides default HTTP submit
+      const result = await runHook(pushVal, env, { cwd });
+      if (!result.skipped && result.exitCode !== 0 && result.exitCode !== null) {
+        return { failed: true };
+      }
+      runDefault = false;
+    }
+    // push: true or undefined → keep runDefault = true
+  }
+
+  // postpush (runs regardless of whether push was default or custom)
+  if ('postpush' in hooks) {
+    const result = await runHook(hooks['postpush'], env, { cwd });
+    if (!result.skipped && result.exitCode !== 0 && result.exitCode !== null) {
+      return { failed: true };
+    }
+  }
+
+  return { runDefault, failed: false };
+}