@dboio/cli 0.15.3 → 0.17.0

package/src/lib/logger.js

@@ -1,5 +1,7 @@
 import chalk from 'chalk';
 
+const SPINNER_FRAMES = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+
 export const log = {
   info(msg) { console.log(chalk.blue('ℹ'), msg); },
   success(msg) { console.log(chalk.green('✓'), msg); },
@@ -9,4 +11,37 @@ export const log = {
   plain(msg) { console.log(msg); },
   verbose(msg) { console.log(chalk.dim('  →'), chalk.dim(msg)); },
   label(label, value) { console.log(chalk.dim(`  ${label}:`), value); },
+
+  /**
+   * Start a spinner with a message. Returns { stop(finalMsg) }.
+   * The spinner writes to stderr so it doesn't pollute piped output.
+   */
+  spinner(msg) {
+    let i = 0;
+    const stream = process.stderr;
+    const isTTY = stream.isTTY;
+    if (!isTTY) {
+      // Non-TTY: just print the message once, return a no-op stop
+      console.log(chalk.dim(msg));
+      return { update() {}, stop(final) { if (final) console.log(final); } };
+    }
+    const render = () => {
+      const frame = chalk.cyan(SPINNER_FRAMES[i % SPINNER_FRAMES.length]);
+      stream.clearLine(0);
+      stream.cursorTo(0);
+      stream.write(`${frame} ${chalk.dim(msg)}`);
+      i++;
+    };
+    render();
+    const timer = setInterval(render, 80);
+    return {
+      update(newMsg) { msg = newMsg; },
+      stop(final) {
+        clearInterval(timer);
+        stream.clearLine(0);
+        stream.cursorTo(0);
+        if (final) console.log(final);
+      },
+    };
+  },
 };

package/src/lib/metadata-schema.js

@@ -0,0 +1,492 @@
+import { readFile, writeFile, readdir, access } from 'fs/promises';
+import { join, relative, basename, extname } from 'path';
+import { EXTENSION_DESCRIPTORS_DIR, ENTITY_DIR_NAMES } from './structure.js';
+import inquirer from 'inquirer';
+
+export const METADATA_SCHEMA_FILE = '.dbo/metadata_schema.json';
+
+const STATIC_DIRECTIVE_MAP = {
+  docs: { entity: 'extension', descriptor: 'documentation' },
+};
+
+/**
+ * Convert a name to snake_case.
+ */
+export function toSnakeCase(name) {
+  return name
+    .toLowerCase()
+    .replace(/[\s-]+/g, '_')
+    .replace(/[^a-z0-9_]/g, '');
+}
+
+/**
+ * Resolve entity/descriptor directive from a file path.
+ * Returns { entity, descriptor } or null.
+ */
+export function resolveDirective(filePath) {
+  const rel = relative(process.cwd(), filePath).replace(/\\/g, '/');
+  const parts = rel.split('/');
+  const topDir = parts[0];
+
+  // docs/ prefix at project root → static mapping (docs/ stays at root)
+  if (topDir === 'docs') {
+    return { ...STATIC_DIRECTIVE_MAP.docs };
+  }
+
+  // lib/<subDir>/... — all server-managed dirs are now under lib/
+  if (topDir === 'lib') {
+    const subDir = parts[1];
+    if (!subDir) return null;
+
+    // lib/extension/<descriptor>/<file> — need at least 4 parts
+    if (subDir === 'extension') {
+      if (parts.length < 4) return null;
+      const descriptorDir = parts[2];
+      if (descriptorDir.startsWith('.')) return null;
+      return { entity: 'extension', descriptor: descriptorDir };
+    }
+
+    // lib/<entityType>/<file> — other entity dirs
+    if (ENTITY_DIR_NAMES.has(subDir)) {
+      return { entity: subDir, descriptor: null };
+    }
+  }
+
+  // Legacy fallback: bare entity-dir paths (pre-migration projects)
+  if (topDir === 'extension') {
+    if (parts.length < 3) return null;
+    const secondDir = parts[1];
+    if (secondDir.startsWith('.')) return null;
+    return { entity: 'extension', descriptor: secondDir };
+  }
+  if (ENTITY_DIR_NAMES.has(topDir)) {
+    return { entity: topDir, descriptor: null };
+  }
+
+  return null;
+}
+
+/**
+ * Load metadata schema from .dbo/metadata_schema.json.
+ */
+export async function loadMetadataSchema() {
+  try {
+    const raw = await readFile(METADATA_SCHEMA_FILE, 'utf8');
+    try {
+      return JSON.parse(raw);
+    } catch {
+      console.warn('Warning: .dbo/metadata_schema.json is malformed JSON — falling back to generic wizard');
+      return null;
+    }
+  } catch (err) {
+    if (err.code === 'ENOENT') return {};
+    return {};
+  }
+}
+
+/**
+ * Save metadata schema to .dbo/metadata_schema.json.
+ */
+export async function saveMetadataSchema(templates) {
+  await writeFile(METADATA_SCHEMA_FILE, JSON.stringify(templates, null, 2) + '\n');
+}
+
+/**
+ * Merge extension descriptor definitions from dependency metadata_schema.json files.
+ * For each dependency in .dbo/dependencies/<name>/, reads its .dbo/metadata_schema.json
+ * and copies any extension descriptor entries that don't already exist locally.
+ *
+ * @param {Object} localSchema - The current project's metadata_schema object (mutated in place)
+ * @returns {Promise<boolean>} - true if any entries were merged
+ */
+export async function mergeDescriptorSchemaFromDependencies(localSchema) {
+  if (!localSchema) return false;
+
+  const depsRoot = join('.dbo', 'dependencies');
+  let depNames;
+  try {
+    depNames = await readdir(depsRoot);
+  } catch {
+    return false; // no dependencies directory
+  }
+
+  let merged = false;
+
+  for (const depName of depNames) {
+    const depSchemaPath = join(depsRoot, depName, '.dbo', 'metadata_schema.json');
+    let depSchema;
+    try {
+      depSchema = JSON.parse(await readFile(depSchemaPath, 'utf8'));
+    } catch {
+      continue; // no schema or unreadable
+    }
+
+    // Only merge extension descriptor entries (the dict values under "extension")
+    const depExtension = depSchema.extension;
+    if (!depExtension || typeof depExtension !== 'object' || Array.isArray(depExtension)) continue;
+
+    for (const [descriptor, cols] of Object.entries(depExtension)) {
+      // Skip if local already has this descriptor
+      const existing = getTemplateCols(localSchema, 'extension', descriptor);
+      if (existing) continue;
+
+      setTemplateCols(localSchema, 'extension', descriptor, cols);
+      merged = true;
+    }
+  }
+
+  return merged;
+}
+
+/**
+ * Get template cols for a given entity and optional descriptor.
+ * Returns string[] or null.
+ */
+export function getTemplateCols(templates, entity, descriptor) {
+  if (!templates || !templates[entity]) return null;
+  const entry = templates[entity];
+
+  if (descriptor) {
+    // entry must be an object (not array)
+    if (Array.isArray(entry)) return null;
+    return entry[descriptor] ?? null;
+  }
+
+  // no descriptor — entry must be an array
+  if (!Array.isArray(entry)) return null;
+  return entry;
+}
+
+/**
+ * Set template cols for a given entity and optional descriptor.
+ * Mutates templates in place.
+ */
+export function setTemplateCols(templates, entity, descriptor, cols) {
+  if (descriptor) {
+    if (!templates[entity] || Array.isArray(templates[entity])) {
+      templates[entity] = {};
+    }
+    templates[entity][descriptor] = cols;
+  } else {
+    templates[entity] = cols;
+  }
+}
+
+/**
+ * Build cols from a record's keys, excluding _ prefixed and array values.
+ */
+function buildColsFromRecord(record) {
+  return Object.keys(record).filter(key => {
+    if (key.startsWith('_')) return false;
+    if (Array.isArray(record[key])) return false;
+    return true;
+  });
+}
+
+/**
+ * Build baseline minimum viable cols for an entity type.
+ */
+function buildBaselineCols(entity, descriptor) {
+  const cols = ['AppID', 'Name'];
+  if (entity === 'extension') {
+    cols.push('ShortName');
+    if (descriptor) cols.push(`Descriptor=${descriptor}`);
+    cols.push('Active');
+  }
+  return cols;
+}
+
+/**
+ * Resolve template cols via three-level lookup:
+ * 1. metadata_schema.json
+ * 2. appJson sample record
+ * 3. baseline defaults
+ */
+export async function resolveTemplateCols(entity, descriptor, appConfig, appJson) {
+  const templates = await loadMetadataSchema();
+  if (templates === null) return null;
+
+  // Level 1: existing template
+  const existing = getTemplateCols(templates, entity, descriptor);
+  if (existing) return { cols: existing, templates, isNew: false };
+
+  // Level 2: derive from appJson
+  if (appJson) {
+    let records = null;
+
+    if (entity === 'extension' && descriptor) {
+      // appJson[entity] might be an object keyed by descriptor
+      const entityData = appJson[entity];
+      if (entityData) {
+        if (Array.isArray(entityData)) {
+          records = entityData;
+        } else if (typeof entityData === 'object' && entityData[descriptor]) {
+          const descData = entityData[descriptor];
+          if (Array.isArray(descData)) records = descData;
+        }
+      }
+    } else {
+      const entityData = appJson[entity];
+      if (Array.isArray(entityData)) records = entityData;
+    }
+
+    if (records && records.length > 0) {
+      const cols = buildColsFromRecord(records[0]);
+      setTemplateCols(templates, entity, descriptor, cols);
+      await saveMetadataSchema(templates);
+      return { cols, templates, isNew: true };
+    }
+  }
+
+  // Level 3: baseline defaults
+  const cols = buildBaselineCols(entity, descriptor);
+  setTemplateCols(templates, entity, descriptor, cols);
+  await saveMetadataSchema(templates);
+  return { cols, templates, isNew: true };
+}
+
+/**
+ * Assemble metadata object from cols and file info.
+ */
+export function assembleMetadata(cols, filePath, entity, descriptor, appConfig) {
+  const rel = relative(process.cwd(), filePath).replace(/\\/g, '/');
+  const base = basename(filePath, extname(filePath));
+  const fileName = basename(filePath);
+  const isDocsFile = rel.startsWith('docs/');
+  const meta = { _entity: entity };
+  const contentColumns = [];
+
+  for (const col of cols) {
+    if (col.includes('=')) {
+      const eqIdx = col.indexOf('=');
+      const key = col.substring(0, eqIdx);
+      const val = col.substring(eqIdx + 1);
+
+      if (val === '@reference') {
+        const refPath = isDocsFile ? '@/' + rel : '@' + fileName;
+        meta[key] = refPath;
+        contentColumns.push(key);
+      } else {
+        meta[key] = val;
+      }
+    } else if (col === 'AppID') {
+      meta.AppID = appConfig?.AppID ?? '';
+    } else if (col === 'Name') {
+      meta.Name = base;
+    } else if (col === 'ShortName') {
+      meta.ShortName = toSnakeCase(base);
+    } else {
+      meta[col] = '';
+    }
+  }
+
+  let refColMissing = false;
+  if (contentColumns.length === 0) {
+    refColMissing = true;
+  } else {
+    meta._companionReferenceColumns = contentColumns;
+  }
+
+  return { meta, contentColumns, refColMissing };
+}
+
+/**
+ * Prompt user to select a reference column from available string cols.
+ */
+export async function promptReferenceColumn(cols, entity, descriptor) {
+  const stringCols = cols.filter(c => !c.includes('=') && c !== 'AppID' && c !== 'Name' && c !== 'ShortName');
+  if (stringCols.length === 0) return null;
+
+  const { selected } = await inquirer.prompt([{
+    type: 'list',
+    name: 'selected',
+    message: `Select the content/reference column for ${entity}${descriptor ? '/' + descriptor : ''}:`,
+    choices: stringCols,
+  }]);
+
+  return selected;
+}
+
+/**
+ * Build a template cols array from a clone record.
+ */
+export function buildTemplateFromCloneRecord(record, contentColsExtracted = []) {
+  const cols = [];
+  for (const key of Object.keys(record)) {
+    if (key.startsWith('_')) continue;
+    if (Array.isArray(record[key])) continue;
+
+    if (contentColsExtracted.includes(key)) {
+      cols.push(key + '=@reference');
+    } else if (key === 'Descriptor' && record[key]) {
+      cols.push('Descriptor=' + record[key]);
+    } else {
+      cols.push(key);
+    }
+  }
+  return cols;
+}
+
+/**
+ * Parse a column entry with extended @reference syntax.
+ * Examples:
+ *   "Content=@reference:@Name[@Extension]"
+ *   "CustomSQL=@reference[sql]"
+ *   "String20=@reference:SQLFileName[SQL]"
+ *   "Column=@reference:@Name[@Ext||html]"
+ *   "Column=@reference:@Name||fallback[html]"
+ * Returns: { column, filenameCol, filenameFallback, extensionCol, extensionFallback }
+ *   - filenameCol: null | '@ColName' | 'LiteralSuffix'
+ *   - extensionCol: null | '@ColName' | 'fixedExt'
+ *   - *Fallback: fallback value after || within name/ext part
+ * Returns null if colExpr doesn't contain '=@reference'.
+ */
+export function parseReferenceExpression(colExpr) {
+  if (!colExpr || !colExpr.includes('=@reference')) return null;
+  const eqIdx = colExpr.indexOf('=@reference');
+  const column = colExpr.slice(0, eqIdx);
+  const rest = colExpr.slice(eqIdx + '=@reference'.length); // ':...' or '[...]' or ''
+
+  let filenameCol = null, filenameFallback = null;
+  let extensionCol = null, extensionFallback = null;
+
+  let extSource = rest;
+
+  if (rest.startsWith(':')) {
+    const afterColon = rest.slice(1);
+    const bracketIdx = afterColon.indexOf('[');
+    const namePart = bracketIdx === -1 ? afterColon : afterColon.slice(0, bracketIdx);
+
+    if (namePart.includes('||')) {
+      const [nameExpr, nameFall] = namePart.split('||');
+      filenameCol = nameExpr || null;
+      filenameFallback = nameFall || null;
+    } else {
+      filenameCol = namePart || null;
+    }
+
+    extSource = bracketIdx === -1 ? '' : afterColon.slice(bracketIdx);
+  }
+
+  // Parse [extPart] from extSource, then {title} from remainder
+  let titleSource = extSource;
+  if (extSource.startsWith('[') && extSource.includes(']')) {
+    const closeBracket = extSource.lastIndexOf(']');
+    const extPart = extSource.slice(1, closeBracket);
+    if (extPart.includes('||')) {
+      const [extExpr, extFall] = extPart.split('||');
+      extensionCol = extExpr || null;
+      extensionFallback = extFall || null;
+    } else {
+      extensionCol = extPart || null;
+    }
+    titleSource = extSource.slice(closeBracket + 1);
+  }
+
+  // Parse {title} — human-readable alias used as the companion filename segment
+  let title = null;
+  if (titleSource.startsWith('{') && titleSource.includes('}')) {
+    title = titleSource.slice(1, titleSource.lastIndexOf('}')) || null;
+  }
+
+  return { column, filenameCol, filenameFallback, extensionCol, extensionFallback, title };
+}
+
+/**
+ * Sanitize a string for use as a filename component.
+ * @param {string} s
+ * @returns {string}
+ */
+function sanitizeFilenameComponent(s) {
+  return s.replace(/[/\\:*?"<>|]/g, '_').trim();
+}
+
+/**
+ * Resolve the companion filename for a @reference expression.
+ * @param {object} parsed — result of parseReferenceExpression()
+ * @param {object} record — the server record (column values)
+ * @param {string} recordName — slugified record name (base for default naming)
+ * @returns {string|null} resolved filename (with extension) or null if extension unresolvable
+ */
+export function resolveCompanionFilename(parsed, record, recordName) {
+  const { column, filenameCol, filenameFallback, extensionCol, extensionFallback } = parsed;
+
+  // --- Resolve filename stem ---
+  let stem;
+  if (!filenameCol) {
+    // No :namePart → "<recordName>.<columnName>"
+    stem = `${recordName}.${column}`;
+  } else if (filenameCol.startsWith('@')) {
+    const val = record?.[filenameCol.slice(1)];
+    const resolved = val != null && String(val).trim() ? sanitizeFilenameComponent(String(val)) : null;
+    stem = resolved || filenameFallback || recordName;
+  } else {
+    // Static suffix → "<recordName>.<staticSuffix>"
+    stem = `${recordName}.${filenameCol}`;
+  }
+
+  // --- Resolve extension ---
+  if (!extensionCol) return stem; // bare @reference — no extension
+
+  let ext;
+  if (extensionCol.startsWith('@')) {
+    const val = record?.[extensionCol.slice(1)];
+    ext = val != null && String(val).trim() ? String(val).trim().toLowerCase() : extensionFallback;
+  } else {
+    ext = extensionCol.toLowerCase();
+  }
+
+  if (!ext) return null; // unresolvable — caller must prompt
+  return `${stem}.${ext}`;
+}
+
+// Built-in @reference rules for well-known entities.
+const BUILT_IN_REFERENCE_RULES = {
+  content: ['Content=@reference:@Name[@Extension]'],
+  output:  ['CustomSQL=@reference[sql]'],
+};
+
+/**
+ * Generate metadata_schema.json entries from schema.json.
+ * Preserves existing entries (never overwrites).
+ * Returns merged result.
+ * @param {object} schema — parsed schema.json
+ * @param {object} existing — existing metadata_schema.json contents
+ */
+export function generateMetadataFromSchema(schema, existing = {}) {
+  const entities = schema?.children?.entity ?? [];
+  const result = { ...existing };
+
+  for (const entity of entities) {
+    const entityKey = entity.UID;
+    if (!entityKey || result[entityKey] !== undefined) continue; // skip known/existing
+
+    const cols = (entity.children?.entity_column ?? [])
+      .filter(col => !col.PhysicalName.startsWith('_') && col.ReadOnly !== 1)
+      .map(col => {
+        if (col.DefaultValue === "b'0'") return `${col.PhysicalName}=0`;
+        if (col.DefaultValue === "b'1'") return `${col.PhysicalName}=1`;
+        return col.PhysicalName;
+      });
+
+    // Apply built-in @reference rules
+    const builtIn = BUILT_IN_REFERENCE_RULES[entityKey] ?? [];
+    const merged = [...cols];
+    for (const rule of builtIn) {
+      const parsed = parseReferenceExpression(rule);
+      if (!parsed) continue;
+      const idx = merged.indexOf(parsed.column);
+      if (idx !== -1) merged[idx] = rule; // replace plain column with @reference version
+      else merged.push(rule); // add if column not in list
+    }
+
+    result[entityKey] = merged;
+  }
+
+  return result;
+}
+
+// Backward-compat re-exports
+export const loadMetadataTemplates = loadMetadataSchema;
+export const saveMetadataTemplates = saveMetadataSchema;
+export const METADATA_TEMPLATES_FILE = METADATA_SCHEMA_FILE;

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

@@ -314,7 +314,7 @@ export async function saveToDisk(rows, columns, options = {}) {
     }
 
     if (contentColumnsList.length > 0) {
-      meta._contentColumns = contentColumnsList;
+      meta._companionReferenceColumns = contentColumnsList;
     }
 
     // ── Save metadata ───────────────────────────────────────────────────

package/src/lib/schema.js

@@ -0,0 +1,53 @@
+import { readFile, writeFile } from 'fs/promises';
+import { DboClient } from './client.js';
+
+export const SCHEMA_FILE = 'schema.json';
+const SCHEMA_API_PATH = '/api/app/object/_system';
+
+/** Fetch schema from /api/app/object/_system. Returns parsed JSON or throws. */
+export async function fetchSchema(options = {}) {
+  const client = new DboClient({ domain: options.domain, verbose: options.verbose });
+  const result = await client.get(SCHEMA_API_PATH);
+  if (!result.ok || !result.data) throw new Error(`Schema fetch failed: HTTP ${result.status}`);
+  return result.data;
+}
+
+/**
+ * Fetch only the _LastUpdated timestamp from the schema endpoint.
+ * Uses the column-filter syntax: /api/app/object/_system[_LastUpdated]
+ * Returns ISO date string or null on failure.
+ */
+export async function fetchSchemaLastUpdated(options = {}) {
+  const client = new DboClient({ domain: options.domain, verbose: options.verbose });
+  const result = await client.get(`${SCHEMA_API_PATH}[_LastUpdated]`);
+  if (!result.ok || !result.data) return null;
+  return result.data._LastUpdated || null;
+}
+
+/**
+ * Check whether the server schema is newer than the local schema.json.
+ * Returns true if the server _LastUpdated is more recent (or local is missing).
+ */
+export async function isSchemaStale(options = {}) {
+  const local = await loadSchema();
+  if (!local || !local._LastUpdated) return true;
+
+  const serverTs = await fetchSchemaLastUpdated(options);
+  if (!serverTs) return false; // can't determine — assume not stale
+
+  return new Date(serverTs) > new Date(local._LastUpdated);
+}
+
+/** Load schema.json from project root. Returns parsed object or null if missing. */
+export async function loadSchema() {
+  try {
+    return JSON.parse(await readFile(SCHEMA_FILE, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+/** Write schema.json to project root. */
+export async function saveSchema(data) {
+  await writeFile(SCHEMA_FILE, JSON.stringify(data, null, 2) + '\n');
+}

package/src/lib/structure.js

@@ -326,7 +326,7 @@ export function findChildBins(binId, structure) {
 /** Root for all extension descriptor-grouped sub-directories */
 export const EXTENSION_DESCRIPTORS_DIR = 'lib/extension';
 
-/** Extensions that cannot be mapped go here */
+/** @deprecated Used only by migration 011 to relocate existing files. */
 export const EXTENSION_UNSUPPORTED_DIR = 'lib/extension/_unsupported';
 
 /** Root-level documentation directory (remains at project root) */
@@ -380,7 +380,7 @@ export function buildDescriptorMapping(extensionRecords) {
  * 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) {
+export 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');
@@ -430,7 +430,7 @@ export async function loadDescriptorMapping() {
 export function resolveExtensionSubDir(record, mapping) {
   const descriptor = record.Descriptor;
   if (!descriptor || !mapping[descriptor]) {
-    return EXTENSION_UNSUPPORTED_DIR;
+    return EXTENSION_DESCRIPTORS_DIR;
   }
   return `${EXTENSION_DESCRIPTORS_DIR}/${mapping[descriptor]}`;
 }

package/src/lib/tagging.js

@@ -117,7 +117,7 @@ async function _getCompanionPaths(metaPath) {
     const meta = JSON.parse(await readFile(metaPath, 'utf8'));
     const dir = dirname(metaPath);
     const paths = [];
-    for (const col of (meta._contentColumns || [])) {
+    for (const col of (meta._companionReferenceColumns || meta._contentColumns || [])) {
       const ref = meta[col];
       if (ref && String(ref).startsWith('@')) {
         const candidate = join(dir, String(ref).substring(1));

package/src/lib/toe-stepping.js

@@ -443,7 +443,7 @@ export async function checkToeStepping(records, client, baseline, options, appSh
  */
 async function showPushDiff(serverEntry, localMeta, metaPath) {
   const metaDir = dirname(metaPath);
-  const contentCols = localMeta._contentColumns || [];
+  const contentCols = localMeta._companionReferenceColumns || localMeta._contentColumns || [];
 
   // Compare content file columns
   for (const col of contentCols) {
@@ -475,7 +475,7 @@ async function showPushDiff(serverEntry, localMeta, metaPath) {
   }
 
   // Compare metadata fields
-  const skipFields = new Set(['_entity', '_contentColumns', '_mediaFile', 'children', '_pathConfirmed']);
+  const skipFields = new Set(['_entity', '_contentColumns', '_companionReferenceColumns', '_mediaFile', 'children', '_pathConfirmed']);
   for (const col of Object.keys(serverEntry)) {
     if (skipFields.has(col)) continue;
     if (contentCols.includes(col)) continue;

package/src/migrations/007-natural-entity-companion-filenames.js

@@ -1,4 +1,4 @@
-import { readdir, readFile, writeFile, rename, access, mkdir } from 'fs/promises';
+import { readdir, readFile, writeFile, rename, access, mkdir, stat, utimes } from 'fs/promises';
 import { join, basename, dirname } from 'path';
 import { log } from '../lib/logger.js';
 import { stripUidFromFilename, hasUidInFilename, isMetadataFile } from '../lib/filenames.js';
@@ -102,10 +102,13 @@ export default async function run(_options) {
         claimedNaturals.add(naturalPath);
       }
 
-      // Rewrite metadata if @references were updated
+      // Rewrite metadata if @references were updated (preserve timestamps
+      // so the write doesn't cause false "local changes" during clone/pull)
       if (metaChanged) {
         try {
+          const before = await stat(metaPath);
           await writeFile(metaPath, JSON.stringify(meta, null, 2) + '\n');
+          await utimes(metaPath, before.atime, before.mtime);
           totalRefsUpdated++;
         } catch { /* non-critical */ }
       }