@dboio/cli 0.7.2 → 0.8.2

package/src/lib/ignore.js

@@ -0,0 +1,145 @@
+import { readFile, writeFile, access } from 'fs/promises';
+import { join } from 'path';
+import ignore from 'ignore';
+
+const DBOIGNORE_FILE = '.dboignore';
+
+/**
+ * Default .dboignore file content — shipped with `dbo init`.
+ * Gitignore-style syntax. Users can edit after creation.
+ */
+const DEFAULT_FILE_CONTENT = `# DBO CLI ignore patterns
+# (gitignore-style syntax — works like .gitignore)
+
+# DBO internal
+.dbo/
+.dboignore
+*.dboio.json
+app.json
+.app.json
+dbo.deploy.json
+
+# Editor / IDE
+.idea/
+.vscode/
+*.codekit3
+
+# Version control
+.git/
+.svn/
+.hg/
+.gitignore
+
+# AI / tooling
+.claude/
+.mcp.json
+
+# Node
+node_modules/
+package.json
+package-lock.json
+
+# Documentation (repo scaffolding)
+SETUP.md
+README.md
+`;
+
+// Session-level cache (one process = one command invocation)
+let _cachedIg = null;
+let _cachedRoot = null;
+
+/**
+ * Return the full default .dboignore file content (with comments).
+ */
+export function getDefaultFileContent() {
+  return DEFAULT_FILE_CONTENT;
+}
+
+/**
+ * Extract just the active pattern lines from DEFAULT_FILE_CONTENT.
+ */
+function getDefaultPatternLines() {
+  return DEFAULT_FILE_CONTENT
+    .split('\n')
+    .filter(l => l && !l.startsWith('#'));
+}
+
+/**
+ * Load and return a cached `ignore` instance for the current project.
+ * Reads .dboignore if it exists; falls back to built-in defaults.
+ *
+ * @param {string} [cwd=process.cwd()] - Project root
+ * @returns {Promise<import('ignore').Ignore>}
+ */
+export async function loadIgnore(cwd = process.cwd()) {
+  if (_cachedIg && _cachedRoot === cwd) return _cachedIg;
+
+  const ig = ignore();
+  const filePath = join(cwd, DBOIGNORE_FILE);
+
+  try {
+    const content = await readFile(filePath, 'utf8');
+    ig.add(content);
+  } catch {
+    // No .dboignore — use built-in defaults
+    ig.add(getDefaultPatternLines());
+  }
+
+  _cachedIg = ig;
+  _cachedRoot = cwd;
+  return ig;
+}
+
+/**
+ * Check whether a relative path should be ignored.
+ *
+ * @param {string} relativePath - Path relative to project root (forward slashes)
+ * @param {string} [cwd=process.cwd()]
+ * @returns {Promise<boolean>}
+ */
+export async function isIgnored(relativePath, cwd = process.cwd()) {
+  const ig = await loadIgnore(cwd);
+  return ig.ignores(relativePath);
+}
+
+/**
+ * Filter an array of relative paths, returning only those NOT ignored.
+ *
+ * @param {string[]} paths - Relative paths
+ * @param {string} [cwd=process.cwd()]
+ * @returns {Promise<string[]>}
+ */
+export async function filterIgnored(paths, cwd = process.cwd()) {
+  const ig = await loadIgnore(cwd);
+  return ig.filter(paths);
+}
+
+/**
+ * Create a .dboignore file with default patterns.
+ * Does nothing if the file already exists (unless force=true).
+ *
+ * @param {string} [cwd=process.cwd()]
+ * @param {{ force?: boolean }} [opts]
+ * @returns {Promise<boolean>} true if file was created/overwritten
+ */
+export async function createDboignore(cwd = process.cwd(), { force = false } = {}) {
+  const filePath = join(cwd, DBOIGNORE_FILE);
+  if (!force) {
+    try {
+      await access(filePath);
+      return false; // already exists
+    } catch { /* doesn't exist — create it */ }
+  }
+  await writeFile(filePath, DEFAULT_FILE_CONTENT);
+  _cachedIg = null;
+  _cachedRoot = null;
+  return true;
+}
+
+/**
+ * Reset the session cache. Call between tests that change cwd or .dboignore.
+ */
+export function resetCache() {
+  _cachedIg = null;
+  _cachedRoot = null;
+}

package/src/lib/structure.js

@@ -179,3 +179,117 @@ export function findBinByPath(dirPath, structure) {
 export function findChildBins(binId, structure) {
   return Object.values(structure).filter(e => e.parentBinID === binId);
 }
+
+// ─── Extension Descriptor Sub-directory Support ───────────────────────────
+
+/** Root for all extension descriptor-grouped sub-directories */
+export const EXTENSION_DESCRIPTORS_DIR = 'Extensions';
+
+/** Extensions that cannot be mapped go here (always created, even if empty) */
+export const EXTENSION_UNSUPPORTED_DIR = 'Extensions/Unsupported';
+
+/** Root-level documentation directory for alternate placement */
+export const DOCUMENTATION_DIR = 'Documentation';
+
+/**
+ * Build a descriptor→dirName mapping from a flat array of extension records.
+ * Scans records where Descriptor === "descriptor_definition".
+ * Maps String1 (key) → Name (directory name).
+ *
+ * Rules:
+ *   - Null/empty String1: skip, push to warnings[]
+ *   - Null/empty Name: use String1 as the directory name
+ *   - Duplicate String1: last one wins, push to warnings[]
+ *
+ * @param {Object[]} extensionRecords
+ * @returns {{ mapping: Object<string,string>, warnings: string[] }}
+ */
+export function buildDescriptorMapping(extensionRecords) {
+  const mapping = {};
+  const warnings = [];
+
+  for (const rec of extensionRecords) {
+    if (rec.Descriptor !== 'descriptor_definition') continue;
+
+    const rawKey = rec.String1;
+    // String1 may be a base64-encoded object from the server API
+    const key = resolveFieldValue(rawKey);
+    if (!key || String(key).trim() === '') {
+      warnings.push(`descriptor_definition UID=${rec.UID} has null/empty String1 — skipped`);
+      continue;
+    }
+    const keyStr = String(key).trim();
+
+    const rawName = rec.Name;
+    const nameStr = resolveFieldValue(rawName);
+    const dirName = (nameStr && String(nameStr).trim())
+      ? String(nameStr).trim()
+      : keyStr;
+
+    if (keyStr in mapping) {
+      warnings.push(`Duplicate descriptor_definition key "${keyStr}" — overwriting with UID=${rec.UID}`);
+    }
+    mapping[keyStr] = dirName;
+  }
+
+  return { mapping, warnings };
+}
+
+/**
+ * Resolve a field value that may be a base64-encoded object from the server API.
+ * Server returns large text as: { bytes: N, value: "base64string", encoding: "base64" }
+ */
+function resolveFieldValue(value) {
+  if (value && typeof value === 'object' && !Array.isArray(value)
+      && value.encoding === 'base64' && typeof value.value === 'string') {
+    return Buffer.from(value.value, 'base64').toString('utf8');
+  }
+  return value;
+}
+
+/**
+ * Persist descriptorMapping and extensionDescriptorDirs into .dbo/structure.json.
+ * Extends the existing structure object (already contains bin entries).
+ *
+ * @param {Object} structure  - Current structure from loadStructureFile()
+ * @param {Object} mapping    - descriptor key → dir name
+ */
+export async function saveDescriptorMapping(structure, mapping) {
+  const descriptorDirs = [
+    EXTENSION_UNSUPPORTED_DIR,
+    ...Object.values(mapping).map(name => `${EXTENSION_DESCRIPTORS_DIR}/${name}`),
+  ];
+  const uniqueDirs = [...new Set(descriptorDirs)];
+
+  const extended = {
+    ...structure,
+    descriptorMapping: mapping,
+    extensionDescriptorDirs: uniqueDirs,
+  };
+  await saveStructureFile(extended);
+}
+
+/**
+ * Load descriptorMapping from .dbo/structure.json.
+ * Returns {} if not yet persisted.
+ */
+export async function loadDescriptorMapping() {
+  const structure = await loadStructureFile();
+  return structure.descriptorMapping || {};
+}
+
+/**
+ * Resolve the sub-directory path for a single extension record.
+ * Returns "Extensions/<MappedName>" or "Extensions/Unsupported".
+ *
+ * @param {Object} record   - Extension record with a .Descriptor field
+ * @param {Object} mapping  - descriptor key → dir name (from buildDescriptorMapping)
+ * @returns {string}
+ */
+export function resolveExtensionSubDir(record, mapping) {
+  const descriptor = record.Descriptor;
+  if (!descriptor || !mapping[descriptor]) {
+    return EXTENSION_UNSUPPORTED_DIR;
+  }
+  return `${EXTENSION_DESCRIPTORS_DIR}/${mapping[descriptor]}`;
+}

package/src/lib/ticketing.js

@@ -145,7 +145,7 @@ export function buildTicketExpression(entity, rowId, ticketId) {
  *
  * @param {Object} options - Command options (checks options.ticket for flag override)
  */
-export async function checkStoredTicket(options) {
+export async function checkStoredTicket(options, context = '') {
   // --ticket flag takes precedence; skip stored-ticket prompt
   if (options.ticket) {
     return { useTicket: false, clearTicket: false, cancel: false };
@@ -162,11 +162,12 @@ export async function checkStoredTicket(options) {
     return { useTicket: true, clearTicket: false, cancel: false };
   }
 
+  const suffix = context ? ` (${context})` : '';
   const inquirer = (await import('inquirer')).default;
   const { action } = await inquirer.prompt([{
     type: 'list',
     name: 'action',
-    message: `Use stored Ticket ID "${data.ticket_id}" for this submission?`,
+    message: `Use stored Ticket ID "${data.ticket_id}" for this submission?${suffix}`,
     choices: [
       { name: `Yes, use "${data.ticket_id}"`, value: 'use' },
       { name: 'Use a different ticket for this submission only', value: 'alt_once' },
@@ -213,7 +214,7 @@ export async function checkStoredTicket(options) {
  * @param {string|null} [sessionOverride] - One-time ticket override from pre-flight prompt
  */
 export async function applyStoredTicketToSubmission(dataExprs, entity, rowId, uid, options, sessionOverride = null) {
-  if (options.ticket) return; // --ticket flag takes precedence
+  if (options.ticket) return null; // --ticket flag takes precedence
 
   const recordTicket = await getRecordTicket(uid);
   const globalTicket = await getGlobalTicket();
@@ -223,5 +224,7 @@ export async function applyStoredTicketToSubmission(dataExprs, entity, rowId, ui
     const ticketExpr = buildTicketExpression(entity, rowId, ticketToUse);
     dataExprs.push(ticketExpr);
     log.dim(`  Applying ticket: ${ticketToUse}`);
+    return ticketToUse;
   }
+  return null;
 }

package/src/lib/timestamps.js

@@ -20,20 +20,42 @@ export function parseServerDate(dateStr, serverTz) {
   if (!serverTz || serverTz === 'UTC') return asUtc;
 
   // Find offset: format this UTC instant in the server timezone,
-  // then compute the difference to determine the actual UTC time
-  const parts = new Intl.DateTimeFormat('en-US', {
+  // then compute the difference to determine the actual UTC time.
+  // Use hourCycle:'h23' (range 0-23) to avoid the hour12:false quirk where
+  // midnight is returned as "24" instead of "00" on some V8 versions.
+  const fmt = new Intl.DateTimeFormat('en-US', {
     timeZone: serverTz,
     year: 'numeric', month: '2-digit', day: '2-digit',
     hour: '2-digit', minute: '2-digit', second: '2-digit',
-    hour12: false,
-  }).formatToParts(asUtc);
+    hourCycle: 'h23',
+  });
 
-  const p = {};
-  for (const { type, value } of parts) p[type] = value;
-  const tzLocal = new Date(`${p.year}-${p.month}-${p.day}T${p.hour}:${p.minute}:${p.second}Z`);
-  const offset = tzLocal - asUtc;
+  // Helper: compute the UTC offset (ms) for a given UTC instant in serverTz.
+  // Returns the offset such that: localTime (as UTC) = utcInstant + offset.
+  const getOffset = (utcInstant) => {
+    const parts = fmt.formatToParts(utcInstant);
+    const p = {};
+    for (const { type, value } of parts) p[type] = value;
+    const tzLocal = new Date(`${p.year}-${p.month}-${p.day}T${p.hour}:${p.minute}:${p.second}Z`);
+    if (isNaN(tzLocal.getTime())) return null;
+    return tzLocal - utcInstant;
+  };
 
-  return new Date(asUtc.getTime() - offset);
+  // Step 1: estimate the UTC equivalent by computing the offset at asUtc.
+  // asUtc is the server's local time naively parsed as UTC, so it may sit in
+  // a different DST regime than the true UTC. This gives a rough approximation.
+  const offset1 = getOffset(asUtc);
+  if (offset1 === null) return asUtc; // fallback: treat as UTC
+
+  const approx = new Date(asUtc.getTime() - offset1);
+
+  // Step 2: recompute the offset at the approximated true UTC.
+  // This corrects for DST boundary crossings where step 1 used the wrong
+  // summer/winter offset — one iteration is sufficient since DST shifts by 1h.
+  const offset2 = getOffset(approx);
+  if (offset2 === null) return approx;
+
+  return new Date(asUtc.getTime() - offset2);
 }
 
 /**