@tenonhq/dovetail-core 0.0.113 → 0.0.115

package/dist/allScopesCommands.js

@@ -106,8 +106,17 @@ async function processManifestForScope(manifest, sourceDirectory, forceWrite = f
                 await fsp.mkdir(recordPath, { recursive: true });
                 // Process each file in the record
                 for (const file of record.files || []) {
-                    const filePath = path.join(recordPath, `${file.name}.${file.type}`);
-                    const fileContent = file.content || "";
+                    // Normalize metaData.json through the shared stamper before it hits
+                    // disk. Without this the all-scopes path persisted the server's raw
+                    // metadata — an absolute https://<instance>.service-now.com
+                    // _record_link plus every field's live display_value — so a record
+                    // written here churned against the same record written by `refresh`,
+                    // and re-pulling from a different instance rewrote every file.
+                    // stampMetadataContent is a no-op on non-metaData files and idempotent
+                    // on already-normalized content.
+                    const stamped = AppUtils.stampMetadataContent(file);
+                    const filePath = path.join(recordPath, `${stamped.name}.${stamped.type}`);
+                    const fileContent = stamped.content || "";
                     const fileDir = path.dirname(filePath);
                     await fsp.mkdir(fileDir, { recursive: true });
                     try {
@@ -118,15 +127,13 @@ async function processManifestForScope(manifest, sourceDirectory, forceWrite = f
                         throw writeError;
                     }
                 }
-                // If no metadata from server, create a basic one
+                // If no metadata from server, write the deterministic placeholder. The
+                // previous stub stamped `_generatedAt: new Date().toISOString()`, which
+                // rewrote the file on every single run and read as a change downstream.
                 if (!hasMetadataFromServer) {
                     const metadataFilePath = path.join(recordPath, "metaData.json");
-                    const metadataContent = {
-                        _generatedAt: new Date().toISOString(),
-                        _note: "Generated locally - metadata not provided by server"
-                    };
                     try {
-                        await fsp.writeFile(metadataFilePath, JSON.stringify(metadataContent, null, 2), "utf8");
+                        await fsp.writeFile(metadataFilePath, AppUtils.EMPTY_METADATA_CONTENT, "utf8");
                     }
                     catch (metaError) {
                         Logger_1.logger.error("Failed to write metadata: " + metadataFilePath);

package/dist/appUtils.js

@@ -36,7 +36,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.createAndAssignUpdateSet = exports.swapScope = exports.buildFiles = exports.summarizeRecord = exports.pushFiles = exports.getAppFileList = exports.groupAppFiles = exports.processMissingFiles = exports.refreshAllFiles = exports.findMissingFiles = exports.syncManifest = exports.narrowManifestToTables = exports.processManifest = exports.normalizeManifestKeys = exports.toSafeFolderName = exports.stampMetadataContent = void 0;
+exports.createAndAssignUpdateSet = exports.swapScope = exports.buildFiles = exports.summarizeRecord = exports.pushFiles = exports.getAppFileList = exports.groupAppFiles = exports.processMissingFiles = exports.refreshAllFiles = exports.findMissingFiles = exports.syncManifest = exports.narrowManifestToRecord = exports.narrowManifestToTables = exports.processManifest = exports.normalizeManifestKeys = exports.toSafeFolderName = exports.stampMetadataContent = exports.emptyMetadataFile = exports.EMPTY_METADATA_CONTENT = void 0;
 const path_1 = __importDefault(require("path"));
 const progress_1 = __importDefault(require("progress"));
 const fUtils = __importStar(require("./FileUtils"));
@@ -81,24 +81,49 @@ const stripFieldDisplayValues = (metadata) => {
         }
     }
 };
-// Merge _lastUpdatedOn into the server-provided metadata content. Preserves all
-// record fields (sys_id, sys_scope, field value/display_value pairs, etc.) so
-// the local metaData.json is a full snapshot of the record, not just a stub.
+// The deterministic placeholder written when the server returns a record with no
+// metadata at all. Every record directory still gets a metaData.json, but the
+// file carries no generation-time value — the previous stub stamped
+// `new Date().toISOString()`, so every run rewrote it and the record read as
+// changed on a pull that changed nothing.
+exports.EMPTY_METADATA_CONTENT = JSON.stringify({
+    _localOnly: true,
+    _description: "No metadata provided by server",
+}, null, 2);
+const emptyMetadataFile = () => ({
+    name: "metaData",
+    type: "json",
+    content: exports.EMPTY_METADATA_CONTENT,
+});
+exports.emptyMetadataFile = emptyMetadataFile;
+// Finalize a record's metaData.json so its on-disk bytes are a pure function of
+// the record — same record, same file, on any instance, from any machine, on
+// every write path. Three things are normalized:
+//   1. `_record_link` loses its instance host (stripRecordLinkHost).
+//   2. Every field loses its live `display_value` (stripFieldDisplayValues).
+//   3. `_lastUpdatedOn` is DELETED, not rewritten. It duplicated
+//      `sys_updated_on.value` exactly, and its no-sys_updated_on fallback was a
+//      wall-clock stamp that churned on every pull. Its only reader,
+//      extractUpdatedOn (reconcile/recordSource.ts), already prefers
+//      `sys_updated_on` and tolerates its absence.
+// All record fields (sys_id, sys_scope, the value pairs) are preserved, so the
+// file stays a full snapshot of the record rather than a stub.
 const stampMetadataContent = (file) => {
     if (file.name !== "metaData" || file.type !== "json")
         return file;
-    const stamp = new Date().toISOString();
     if (!file.content) {
-        return { ...file, content: JSON.stringify({ _lastUpdatedOn: stamp }, null, 2) };
+        return { ...file, content: exports.EMPTY_METADATA_CONTENT };
     }
     try {
         const metadata = JSON.parse(file.content);
-        if (metadata.sys_updated_on && metadata.sys_updated_on.value) {
-            metadata._lastUpdatedOn = metadata.sys_updated_on.value;
-        }
-        else {
-            metadata._lastUpdatedOn = stamp;
+        // Guard against non-object JSON (a bare string/number/array parses fine but
+        // has no keys to normalize) — writing it back verbatim is the safe default.
+        if (typeof metadata !== "object" || metadata === null || Array.isArray(metadata)) {
+            return file;
         }
+        // Drop the key outright, including from legacy content that already carries
+        // it, so a re-stamp settles the file instead of preserving the stale stamp.
+        delete metadata._lastUpdatedOn;
         if (typeof metadata._record_link === "string") {
             metadata._record_link = stripRecordLinkHost(metadata._record_link);
         }
@@ -115,15 +140,10 @@ const hasServerMetadata = (files) => files.some((f) => f.name === "metaData" &&
 const processFilesInManRec = async (recPath, rec, forceWrite) => {
     FileLogger_1.fileLogger.debug("Processing record: " + rec.name + " (" + rec.files.length + " files)");
     const fileWrite = fUtils.writeSNFileCurry(forceWrite);
-    // If the server did not provide a metadata file, fall back to a timestamp-only
+    // If the server did not provide a metadata file, fall back to a deterministic
     // stub so the record directory always has a metaData.json.
     if (!hasServerMetadata(rec.files)) {
-        const stubMetadata = {
-            name: "metaData",
-            type: "json",
-            content: JSON.stringify({ _lastUpdatedOn: new Date().toISOString() }, null, 2),
-        };
-        await fileWrite(stubMetadata, recPath);
+        await fileWrite((0, exports.emptyMetadataFile)(), recPath);
     }
     const writeResults = await (0, genericUtils_1.allSettledBatched)(rec.files, constants_1.CONCURRENCY_FILES, function (file) { return fileWrite((0, exports.stampMetadataContent)(file), recPath); });
     const writeFailures = writeResults.filter((r) => r.status === "rejected");
@@ -298,6 +318,44 @@ const narrowManifestToTables = (manifest, tables) => {
     return Object.assign({}, manifest, { tables: wantedTables });
 };
 exports.narrowManifestToTables = narrowManifestToTables;
+/**
+ * Narrow a manifest's table map to a SINGLE record (matched by `table` +
+ * `sysId`), for the FILE refresh only.
+ *
+ * Returns a NEW manifest and NEVER mutates its input — same safety contract as
+ * `narrowManifestToTables`: the caller keeps writing the original, full manifest
+ * to disk, so the on-disk `dove.manifest.<scope>.json` never loses its other
+ * tables/records. Only the file download is scoped to this one record.
+ *
+ * If the table or a record with that sys_id is absent from the manifest, the
+ * returned manifest has an empty table map — refreshAllFiles no-ops on it, so no
+ * files are written (the create flow warns and points the user at `dove refresh`).
+ */
+const narrowManifestToRecord = (manifest, table, sysId) => {
+    var empty = Object.assign({}, manifest, { tables: {} });
+    var tables = manifest.tables || {};
+    var tableEntry = tables[table];
+    if (!tableEntry || !tableEntry.records)
+        return empty;
+    var records = tableEntry.records;
+    var recKeys = Object.keys(records);
+    var wantedRecords = {};
+    // sys_id is unique per table, so stop at the first match — the record set for
+    // a large table can be sizable and this is the exact scenario the feature targets.
+    for (var i = 0; i < recKeys.length; i++) {
+        var rec = records[recKeys[i]];
+        if (rec && rec.sys_id === sysId) {
+            wantedRecords[recKeys[i]] = rec;
+            break;
+        }
+    }
+    if (Object.keys(wantedRecords).length === 0)
+        return empty;
+    var narrowedTables = {};
+    narrowedTables[table] = Object.assign({}, tableEntry, { records: wantedRecords });
+    return Object.assign({}, manifest, { tables: narrowedTables });
+};
+exports.narrowManifestToRecord = narrowManifestToRecord;
 const syncManifest = async (scope, options = {}) => {
     // Top-level entry owns the collector lifecycle. Recursive calls (all-scopes
     // → per-scope) inherit the collector via options._benchmarkCollector.
@@ -368,6 +426,23 @@ const syncManifest = async (scope, options = {}) => {
             // so intersecting the manifest is enough. `newManifest` is left intact —
             // see narrowManifestToTables.
             var refreshManifest = (0, exports.narrowManifestToTables)(newManifest, options.tables);
+            // Single-record narrowing (dove create round-trip). Applied after the
+            // --table narrowing so the two compose; the full manifest was already
+            // written above, so only the file download is scoped to the one record.
+            if (options.record) {
+                refreshManifest = (0, exports.narrowManifestToRecord)(refreshManifest, options.record.table, options.record.sysId);
+                if (Object.keys(refreshManifest.tables).length === 0) {
+                    Logger_1.logger.warn("Created record " + options.record.sysId + " (" + options.record.table +
+                        ") not found in the refreshed scope manifest — local files not written. " +
+                        "If '" + options.record.table + "' is missing from this scope's `_tables` " +
+                        "whitelist in dove.config.js, add it there first; otherwise run " +
+                        "'npx dove refresh' to pull it.");
+                }
+                else {
+                    FileLogger_1.fileLogger.debug("syncManifest: narrowed file refresh to single record " +
+                        options.record.sysId + " (" + options.record.table + ")");
+                }
+            }
             if (options.tables && options.tables.length > 0) {
                 var wantedNames = Object.keys(refreshManifest.tables);
                 if (wantedNames.length === 0) {
@@ -385,10 +460,14 @@ const syncManifest = async (scope, options = {}) => {
                 collector.startScope(scope);
             await (0, exports.refreshAllFiles)(refreshManifest, scopeSourcePath, {
                 force: options.force,
+                metadataOnly: options.metadataOnly,
                 benchmarkCollector: collector,
             });
-            // Update the in-memory manifest for this scope
-            if (ConfigManager.isMultiScopeManifest(curManifest)) {
+            // Update the in-memory manifest for this scope. Skipped under
+            // metadataOnly: persisting the manifest would put record adds, drops and
+            // renames into a diff that is supposed to contain metaData.json only. A
+            // normal `dove refresh` is what reconciles the manifest.
+            if (!options.metadataOnly && ConfigManager.isMultiScopeManifest(curManifest)) {
                 curManifest[scope] = newManifest;
                 ConfigManager.updateManifest(curManifest);
             }
@@ -399,6 +478,7 @@ const syncManifest = async (scope, options = {}) => {
             // scopes that leaked in before the whitelist gate existed.
             var childOptions = {
                 force: options.force,
+                metadataOnly: options.metadataOnly,
                 tables: options.tables,
                 _benchmarkCollector: collector,
             };
@@ -547,6 +627,13 @@ const buildAllFilesMap = (manifest) => {
  *
  * @param options.force — when true, always overwrite local files even if their
  * content matches the instance. Use for deliberate "reset local to instance".
+ *
+ * @param options.metadataOnly — when true, rewrite every existing record's
+ * metaData.json and touch nothing else: no field file is written, and a record
+ * with no directory on disk is skipped entirely (writing one would leave an
+ * orphan directory holding a lone metaData.json and no fields). Use to settle a
+ * mirror after a change to the metadata writer, without the source churn
+ * `--force` produces.
  */
 const refreshAllFiles = async (newManifest, sourcePath, options = {}) => {
     try {
@@ -554,7 +641,8 @@ const refreshAllFiles = async (newManifest, sourcePath, options = {}) => {
         const tableNames = Object.keys(allFiles);
         if (tableNames.length === 0)
             return;
-        FileLogger_1.fileLogger.debug("Refreshing file content for " + tableNames.length + " tables (force=" + !!options.force + ")");
+        FileLogger_1.fileLogger.debug("Refreshing file content for " + tableNames.length + " tables (force=" + !!options.force +
+            ", metadataOnly=" + !!options.metadataOnly + ")");
         const { tableOptions = {} } = ConfigManager.getConfig();
         const client = (0, snClient_1.defaultClient)();
         const totalChunks = Math.ceil(tableNames.length / BULK_DOWNLOAD_TABLE_CHUNK_SIZE);
@@ -581,27 +669,55 @@ const refreshAllFiles = async (newManifest, sourcePath, options = {}) => {
         });
         var writtenCount = 0;
         var unchangedCount = 0;
+        var skippedAbsentCount = 0;
+        var metadataWrittenCount = 0;
         const forceWrite = !!options.force;
+        const metadataOnly = !!options.metadataOnly;
         const forceWriter = fUtils.writeSNFileCurry(false);
         const processedTableNames = Object.keys(filesToProcess);
         await (0, genericUtils_1.processBatched)(processedTableNames, constants_1.CONCURRENCY_TABLES, async function (tableName) {
             var tablePath = path_1.default.join(basePath, tableName);
             var recs = filesToProcess[tableName].records;
             var recKeys = Object.keys(recs);
-            await Promise.all(recKeys.map(function (k) {
-                // toSafeFolderName, not raw recs[k].name: the bulkDownload response
-                // carries the unmodified ServiceNow display name, which may be
-                // filesystem-unsafe (e.g. a `<table>.*` ACL). Without this, refresh
-                // recreates Windows-illegal folders that normalizeManifestKeys
-                // already removed from the manifest.
-                return fUtils.createDirRecursively(path_1.default.join(tablePath, (0, exports.toSafeFolderName)(recs[k])));
-            }));
+            // metadataOnly never materializes a record directory — it refreshes the
+            // metadata of records already on disk. Creating dirs here would leave an
+            // orphan folder holding a lone metaData.json with no field files.
+            if (!metadataOnly) {
+                await Promise.all(recKeys.map(function (k) {
+                    // toSafeFolderName, not raw recs[k].name: the bulkDownload response
+                    // carries the unmodified ServiceNow display name, which may be
+                    // filesystem-unsafe (e.g. a `<table>.*` ACL). Without this, refresh
+                    // recreates Windows-illegal folders that normalizeManifestKeys
+                    // already removed from the manifest.
+                    return fUtils.createDirRecursively(path_1.default.join(tablePath, (0, exports.toSafeFolderName)(recs[k])));
+                }));
+            }
             await (0, genericUtils_1.processBatched)(recKeys, constants_1.CONCURRENCY_RECORDS, async function (recKey) {
                 var rec = recs[recKey];
                 var recPath = path_1.default.join(tablePath, (0, exports.toSafeFolderName)(rec));
+                // metadataOnly refreshes what is already checked out. A record the
+                // instance has but this branch does not is left alone — pulling it in
+                // would be a content change, which is exactly what this mode excludes.
+                // pathExists, NOT isDirectory: isDirectory stats unguarded and REJECTS
+                // on ENOENT, and processBatched propagates, so a single absent record
+                // would abort the whole scope — the common case, since "the instance
+                // has records this branch doesn't" is precisely what we're skipping.
+                if (metadataOnly && !(await fUtils.pathExists(recPath))) {
+                    skippedAbsentCount++;
+                    // Drop the downloaded content for skipped records too — filesToProcess
+                    // accumulates across every chunk, so holding it would grow unbounded
+                    // across a large scope.
+                    rec.files = rec.files.map(function (file) {
+                        var copy = Object.assign({}, file);
+                        delete copy.content;
+                        return copy;
+                    });
+                    progress.tick();
+                    return;
+                }
                 // Split server-provided metadata off from the regular files so we can
                 // track whether any regular file actually changed — metaData shouldn't
-                // be the trigger for "this record changed" since we stamp it on every
+                // be the trigger for "this record changed" since we rewrite it on every
                 // touch.
                 var metadataFiles = [];
                 var regularFiles = [];
@@ -614,13 +730,17 @@ const refreshAllFiles = async (newManifest, sourcePath, options = {}) => {
                         regularFiles.push(rf);
                     }
                 }
-                var results = await (0, genericUtils_1.allSettledBatched)(regularFiles, constants_1.CONCURRENCY_FILES, async function (file) {
-                    if (forceWrite) {
-                        await forceWriter(file, recPath);
-                        return true;
-                    }
-                    return fUtils.writeSNFileIfDifferent(file, recPath);
-                });
+                // metadataOnly writes no field file at all, so there is nothing to
+                // diff and the download result is discarded for regular files.
+                var results = metadataOnly
+                    ? []
+                    : await (0, genericUtils_1.allSettledBatched)(regularFiles, constants_1.CONCURRENCY_FILES, async function (file) {
+                        if (forceWrite) {
+                            await forceWriter(file, recPath);
+                            return true;
+                        }
+                        return fUtils.writeSNFileIfDifferent(file, recPath);
+                    });
                 var anyChanged = false;
                 for (var f = 0; f < results.length; f++) {
                     var res = results[f];
@@ -637,23 +757,21 @@ const refreshAllFiles = async (newManifest, sourcePath, options = {}) => {
                     }
                 }
                 // Only touch metaData when at least one regular file in the record
-                // actually changed. Avoids rewriting _lastUpdatedOn for records that
-                // were already in sync with the instance. Prefer the server-provided
+                // actually changed — otherwise a record already in sync with the
+                // instance would be rewritten for nothing. `force` and `metadataOnly`
+                // both mean "rewrite it regardless". Prefer the server-provided
                 // metadata (full field snapshot) over a stub; fall back to a stub only
                 // when the server didn't send metadata at all.
-                if (anyChanged || forceWrite) {
+                if (anyChanged || forceWrite || metadataOnly) {
                     let metadataFile;
                     if (metadataFiles.length > 0 && metadataFiles[0].content) {
                         metadataFile = (0, exports.stampMetadataContent)(metadataFiles[0]);
                     }
                     else {
-                        metadataFile = {
-                            name: "metaData",
-                            type: "json",
-                            content: JSON.stringify({ _lastUpdatedOn: new Date().toISOString() }, null, 2),
-                        };
+                        metadataFile = (0, exports.emptyMetadataFile)();
                     }
                     await forceWriter(metadataFile, recPath);
+                    metadataWrittenCount++;
                 }
                 // Strip content from manifest entries to keep memory bounded.
                 rec.files = rec.files.map(function (file) {
@@ -664,8 +782,17 @@ const refreshAllFiles = async (newManifest, sourcePath, options = {}) => {
                 progress.tick();
             });
         });
-        FileLogger_1.fileLogger.debug("Refresh complete: " + writtenCount + " written, " + unchangedCount + " unchanged");
-        if (writtenCount > 0) {
+        FileLogger_1.fileLogger.debug("Refresh complete: " + writtenCount + " written, " + unchangedCount + " unchanged, " +
+            metadataWrittenCount + " metaData written, " + skippedAbsentCount + " records absent locally");
+        if (metadataOnly) {
+            // writtenCount is always 0 here — no field file is written — so report the
+            // metadata counts instead of the misleading "no changes detected".
+            Logger_1.logger.info("Rewrote metaData.json for " + metadataWrittenCount + " record(s)" +
+                (skippedAbsentCount > 0
+                    ? " (" + skippedAbsentCount + " skipped — not checked out locally)"
+                    : ""));
+        }
+        else if (writtenCount > 0) {
             Logger_1.logger.info("Refreshed " + writtenCount + " file(s) from instance" +
                 (unchangedCount > 0 ? " (" + unchangedCount + " already in sync)" : ""));
         }

package/dist/commander.js

@@ -89,6 +89,13 @@ function configureCli(cli) {
                 default: false,
                 describe: "Overwrite local files even when content matches the instance",
             },
+            "metadata-only": {
+                type: "boolean",
+                default: false,
+                describe: "Rewrite only each record's metaData.json — no field file is written, no " +
+                    "record directory is created, and the manifest is left untouched. Records " +
+                    "not already checked out locally are skipped. Cannot be combined with --force.",
+            },
             scope: {
                 alias: "s",
                 type: "string",
@@ -228,6 +235,11 @@ function configureCli(cli) {
                 default: false,
                 describe: "Skip interactive prompts",
             },
+            refresh: {
+                type: "boolean",
+                default: true,
+                describe: "Pull the created record's files to disk afterward (default: true; --no-refresh skips the local sync)",
+            },
         });
         return cmdArgs;
     }, createRecordCommand_1.createRecordCommand)

package/dist/commands.js

@@ -123,11 +123,20 @@ async function refreshCommand(args, log = true) {
                     "Add " + pronoun + " to includes._tables (or includes._scopes.<scope>._tables) in dove.config.js first.");
             }
         }
+        // --force overwrites field files from the instance; --metadata-only writes
+        // no field file at all. Asking for both is contradictory, so refuse rather
+        // than silently picking one and clobbering the caller's source.
+        if (args.metadataOnly && args.force) {
+            throw new Error("--metadata-only cannot be combined with --force: --force overwrites every " +
+                "field file from the instance, while --metadata-only writes none. Pick one.");
+        }
         FileLogger_1.fileLogger.debug("Syncing manifest from instance (force=" + !!args.force +
+            ", metadataOnly=" + !!args.metadataOnly +
             ", benchmark=" + !!args.benchmark +
             ", tables=" + (tables.length > 0 ? tables.join(",") : "all") + ")");
         await AppUtils.syncManifest(args.scope, {
             force: !!args.force,
+            metadataOnly: !!args.metadataOnly,
             benchmark: !!args.benchmark,
             tables: tables.length > 0 ? tables : undefined,
         });

package/dist/createRecordCommand.js

@@ -281,20 +281,33 @@ async function createRecordCommand(args) {
             " (" +
             newSysId +
             ")");
-        // 7. Full round-trip: pull the record back locally
-        Logger_1.logger.info("Syncing record to local files...");
-        FileLogger_1.fileLogger.debug("Starting manifest sync for scope:", scope);
-        try {
-            await AppUtils.syncManifest(scope);
-            var sourcePath = ConfigManager.getSourcePath();
-            var localPath = path_1.default.join(sourcePath, table, recordName);
-            Logger_1.logger.success(chalk_1.default.green("Local files created at: ") + localPath);
+        // 7. Round-trip: pull ONLY the new record's files back locally. Scoped to
+        // { table, sysId } so creating one record no longer refreshes the entire
+        // scope (the whole-scope-churn footgun). --no-refresh skips it entirely.
+        if (typedArgs.refresh === false) {
+            Logger_1.logger.info("Skipping local sync (--no-refresh). Run 'npx dove refresh' to pull the record locally.");
         }
-        catch (syncErr) {
-            Logger_1.logger.warn("Record created on instance but local sync failed.");
-            Logger_1.logger.warn("Run 'npx dove refresh' to pull the record locally.");
-            if (syncErr instanceof Error) {
-                FileLogger_1.fileLogger.error("Sync error:", syncErr.message);
+        else {
+            Logger_1.logger.info("Syncing record to local files...");
+            FileLogger_1.fileLogger.debug("Starting single-record sync for scope:", scope);
+            try {
+                await AppUtils.syncManifest(scope, {
+                    record: { table: table, sysId: newSysId },
+                });
+                // Resolve the scope's own source directory — syncManifest writes into
+                // getSourcePathForScope(scope), which a scope config can override. Using
+                // the top-level getSourcePath() here would print a wrong path in
+                // multi-scope setups even though the files landed correctly.
+                var sourcePath = ConfigManager.getSourcePathForScope(scope);
+                var localPath = path_1.default.join(sourcePath, table, recordName);
+                Logger_1.logger.success(chalk_1.default.green("Local files created at: ") + localPath);
+            }
+            catch (syncErr) {
+                Logger_1.logger.warn("Record created on instance but local sync failed.");
+                Logger_1.logger.warn("Run 'npx dove refresh' to pull the record locally.");
+                if (syncErr instanceof Error) {
+                    FileLogger_1.fileLogger.error("Sync error:", syncErr.message);
+                }
             }
         }
     }

package/dist/reconcile/baseline.js

@@ -3,9 +3,9 @@
 // records the {sys_id -> sys_updated_on} the instance was known to hold at the
 // last reconcile (or refresh), namespaced by instance host. It MUST live
 // outside the git tree: after a `git checkout`, the on-disk
-// `metaData._lastUpdatedOn` is the *committer's* refresh time, not this
-// developer's instance state, so the branch files cannot answer "did the dev
-// change the instance since we last synced?". The baseline can.
+// `metaData.sys_updated_on` is whatever the *committer's* instance held, not
+// this developer's instance state, so the branch files cannot answer "did the
+// dev change the instance since we last synced?". The baseline can.
 //
 // Phase 1 only READS the baseline (to disambiguate deletes and surface drift).
 // `writeBaseline` / `baselineFromLive` are the apply-phase write path and the

package/dist/reconcile/fields.js

@@ -1,8 +1,8 @@
 "use strict";
 // Field-comparison rules for reconcile. A record's on-disk representation is a
 // directory of per-field files plus a `metaData.json` snapshot. metaData is
-// Dovetail bookkeeping — it carries `_lastUpdatedOn`, a host-stripped
-// `_record_link`, and a full field dump, and it is re-stamped on every touch —
+// Dovetail bookkeeping — it carries a host-stripped `_record_link` and a full
+// field dump including volatile audit columns (sys_updated_on, sys_mod_count) —
 // so including it in a content comparison would make every record read as
 // modified. Excluding it leaves the genuine, content-bearing field files
 // (script.js, etc.), which is exactly what `dove refresh` writes verbatim from

package/dist/reconcile/recordSource.js

@@ -57,9 +57,12 @@ const fields_1 = require("./fields");
 // Mirror the refresh chunk size so a large scope stays under ServiceNow's ~10 MB
 // REST payload cap.
 const BULK_DOWNLOAD_TABLE_CHUNK_SIZE = 5;
-// Pull `sys_updated_on` out of a metaData.json blob. The instance side carries
-// `sys_updated_on: { value }`; the on-disk side carries the stamped
-// `_lastUpdatedOn`. Either resolves the baseline timestamp; missing -> "".
+// Pull `sys_updated_on` out of a metaData.json blob. Both sides carry
+// `sys_updated_on: { value }` — that is the primary source. `_lastUpdatedOn` is
+// a legacy fallback: Dovetail no longer writes it (it duplicated
+// `sys_updated_on.value` and its no-sys_updated_on branch stamped a wall-clock
+// that churned every pull), but a branch checked out before that change still
+// has it on disk, so keep reading it. Neither present -> "".
 function extractUpdatedOn(metaContent) {
     if (!metaContent) {
         return "";