@tenonhq/dovetail-core 0.0.117 → 0.0.118

package/dist/FileUtils.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.writeFileForce = exports.writeSNFileForce = exports.writeSNFileIfNotExists = exports.writeBuildFile = exports.summarizeFile = exports.encodedPathsToFilePaths = exports.isValidPath = exports.splitEncodedPaths = exports.getPathsInPath = exports.isDirectory = exports.toAbsolutePath = exports.getFileContextFromPath = exports.getFileContextWithSkipReason = exports.getBuildExt = exports.isUnderPath = exports.appendToPath = exports.pathExists = exports.createDirRecursively = exports.writeSNFileIfDifferent = exports.writeSNFileCurry = exports.writeScopeManifest = exports.writeManifestFile = exports.SNFileExists = void 0;
+exports.writeFileForce = exports.writeSNFileForce = exports.writeSNFileIfNotExists = exports.writeBuildFile = exports.summarizeFile = exports.encodedPathsToFilePaths = exports.isValidPath = exports.splitEncodedPaths = exports.getPathsInPath = exports.isExistingDirectory = exports.isDirectory = exports.toAbsolutePath = exports.getFileContextFromPath = exports.getFileContextWithSkipReason = exports.getBuildExt = exports.isUnderPath = exports.appendToPath = exports.pathExists = exports.createDirRecursively = exports.writeSNFileIfDifferent = exports.writeSNFileCurry = exports.writeScopeManifest = exports.writeManifestFile = exports.SNFileExists = void 0;
 exports.writeEnvVar = writeEnvVar;
 exports.writeEnvVars = writeEnvVars;
 const constants_1 = require("./constants");
@@ -263,11 +263,41 @@ const getFileContextFromPath = (filePath) => {
 exports.getFileContextFromPath = getFileContextFromPath;
 const toAbsolutePath = (p) => path_1.default.isAbsolute(p) ? p : path_1.default.join(process.cwd(), p);
 exports.toAbsolutePath = toAbsolutePath;
+/**
+ * True when `p` is a directory. THROWS if `p` does not exist — `fsp.stat`
+ * rejects with ENOENT and that rejection is deliberately not swallowed, because
+ * `getPathsInPath` relies on a missing path being an error rather than being
+ * silently treated as a file.
+ *
+ * If you are asking "is there a directory here?" about a path that may legally
+ * be absent, you want `isExistingDirectory` instead. Using this one for that
+ * shipped a real bug: the `--metadata-only` refresh aborted an entire scope on
+ * the first record present on the instance but absent from the branch, which is
+ * the common case, not an edge one.
+ */
 const isDirectory = async (p) => {
     const stats = await fs_1.promises.stat(p);
     return stats.isDirectory();
 };
 exports.isDirectory = isDirectory;
+/**
+ * True when `p` exists AND is a directory; false for a missing path, a regular
+ * file, or an unreadable one. Never throws.
+ *
+ * Prefer this over `pathExists` when the caller is about to write *into* `p` —
+ * `pathExists` also returns true for a regular file, so a stray file sitting at
+ * a record path would pass the check and fail confusingly at write time.
+ */
+const isExistingDirectory = async (p) => {
+    try {
+        const stats = await fs_1.promises.stat(p);
+        return stats.isDirectory();
+    }
+    catch (e) {
+        return false;
+    }
+};
+exports.isExistingDirectory = isExistingDirectory;
 const getPathsInPath = async (p) => {
     if (!(0, exports.isUnderPath)(ConfigManager.getSourcePath(), p) &&
         !(0, exports.isUnderPath)(ConfigManager.getBuildPath(), p)) {

package/dist/appUtils.js

@@ -95,16 +95,32 @@ const stripRecordLinkHost = (link) => link.replace(/^https?:\/\/[^/]+\.service-n
 // entirely and push keys off `value` / the manifest.
 const SYS_DATETIME_RE = /^\d{4}-\d{2}-\d{2}( \d{2}:\d{2}:\d{2})?$/;
 // References carried by nearly every record — one rename churns the whole tree.
-const WHOLE_TREE_REFERENCE_KEYS = ["sys_scope", "sys_package"];
-// Normalize for comparison: the server uses null and "" interchangeably across
-// the two halves of a pair, and String(null) would otherwise read as "null".
-const displayNorm = (v) => v === null || v === undefined ? "" : String(v);
+const WHOLE_TREE_REFERENCE_KEYS = new Set(["sys_scope", "sys_package"]);
+// Normalize a half of the pair for comparison. Returns null for anything that
+// is not a primitive: String({}) collapses every object to "[object Object]",
+// so two structurally different values would compare equal and silently lose a
+// display_value. A non-primitive is treated as "not comparable" instead.
+// null and "" are deliberately folded together — the server uses them
+// interchangeably across the two halves, and String(null) would read as "null".
+const displayNorm = (v) => {
+    if (v === null || v === undefined)
+        return "";
+    const t = typeof v;
+    if (t === "string" || t === "number" || t === "boolean")
+        return String(v);
+    return null;
+};
 const shouldDropDisplayValue = (key, value, displayValue) => {
-    if (displayNorm(value) === displayNorm(displayValue))
+    const normValue = displayNorm(value);
+    const normDisplay = displayNorm(displayValue);
+    // Identical -> the display_value carries no information, at any size.
+    if (normValue !== null && normValue === normDisplay)
         return true;
-    if (SYS_DATETIME_RE.test(displayNorm(value)))
+    // Datetime -> display_value is rendered in the PULLER's timezone.
+    if (normValue !== null && SYS_DATETIME_RE.test(normValue))
         return true;
-    if (WHOLE_TREE_REFERENCE_KEYS.indexOf(key) !== -1)
+    // Present in ~every record -> one rename rewrites the whole mirror.
+    if (WHOLE_TREE_REFERENCE_KEYS.has(key))
         return true;
     return false;
 };
@@ -745,11 +761,11 @@ const refreshAllFiles = async (newManifest, sourcePath, options = {}) => {
                 // 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))) {
+                // isExistingDirectory, not isDirectory (which REJECTS on ENOENT, and
+                // processBatched propagates, so one absent record aborted the whole
+                // scope) and not pathExists (which is true for a regular file too, so a
+                // stray file at a record path would pass and fail at write time).
+                if (metadataOnly && !(await fUtils.isExistingDirectory(recPath))) {
                     skippedAbsentCount++;
                     // Drop the downloaded content for skipped records too — filesToProcess
                     // accumulates across every chunk, so holding it would grow unbounded
@@ -847,7 +863,10 @@ const refreshAllFiles = async (newManifest, sourcePath, options = {}) => {
             Logger_1.logger.debug("No file changes detected from instance (" + unchangedCount + " checked)");
         }
         if (options.benchmarkCollector) {
-            options.benchmarkCollector.endScope(writtenCount, unchangedCount);
+            // metadataOnly writes no field file, so writtenCount is always 0 — report
+            // the metaData writes instead, or `--benchmark --metadata-only` would show
+            // a scope that did thousands of writes as having done nothing.
+            options.benchmarkCollector.endScope(metadataOnly ? metadataWrittenCount : writtenCount, metadataOnly ? skippedAbsentCount : unchangedCount);
         }
     }
     catch (e) {

package/dist/tests/refreshFlagGuards.test.js

@@ -0,0 +1,170 @@
+"use strict";
+/**
+ * Coverage for the `dove refresh` flag guards and the filesystem predicate the
+ * `--metadata-only` skip depends on.
+ *
+ * Both were gaps found reviewing the metaData work after it shipped:
+ *
+ *   1. `--metadata-only` + `--force` is contradictory (one writes no field file,
+ *      the other overwrites every field file). refreshCommand refuses the
+ *      combination, but that refusal was user-facing behaviour with zero tests.
+ *
+ *   2. `isDirectory` REJECTS on a missing path rather than returning false, and
+ *      `processBatched` propagates — which aborted an entire scope on the first
+ *      record present on the instance but absent from the branch. That is the
+ *      common case for `--metadata-only`, not an edge one. `isExistingDirectory`
+ *      is the guarded predicate; these tests pin the contract of all three so
+ *      the next caller picks the right one deliberately.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+const fs = __importStar(require("fs"));
+const os = __importStar(require("os"));
+const path = __importStar(require("path"));
+var mockLogger = {
+    info: jest.fn(),
+    debug: jest.fn(),
+    warn: jest.fn(),
+    error: jest.fn(),
+    success: jest.fn(),
+    setLogLevel: jest.fn(),
+    getLogLevel: function () { return "warn"; },
+};
+jest.mock("../Logger", function () { return { logger: mockLogger }; });
+jest.mock("../FileLogger", function () {
+    return { fileLogger: { debug: jest.fn(), info: jest.fn(), warn: jest.fn(), error: jest.fn() } };
+});
+jest.mock("../snClient", function () {
+    return {
+        defaultClient: function () { return { getManifest: jest.fn(), getMissingFiles: jest.fn() }; },
+        unwrapSNResponse: function (p) { return Promise.resolve(p); },
+        processPushResponse: jest.fn(),
+        retryOnErr: jest.fn(),
+        retryOnHttpErr: jest.fn(),
+        unwrapTableAPIFirstItem: jest.fn(),
+    };
+});
+jest.mock("../config", function () {
+    return {
+        getConfig: jest.fn().mockReturnValue({ scopes: { x_cadso_core: {} }, tableOptions: {} }),
+        getManifest: jest.fn().mockResolvedValue({}),
+        getSourcePath: jest.fn(),
+        getSourcePathForScope: jest.fn(),
+        getManifestPath: jest.fn().mockReturnValue("/tmp/dove.manifest.json"),
+        getScopeManifestPath: jest.fn().mockReturnValue("/tmp/dove.manifest.json"),
+        resolveConfigForScope: jest.fn().mockReturnValue({
+            tables: ["sys_script_include"],
+            fieldOverrides: {},
+            apiIncludes: {},
+            apiExcludes: {},
+        }),
+        isMultiScopeManifest: jest.fn().mockReturnValue(true),
+        updateManifest: jest.fn(),
+    };
+});
+jest.mock("progress", function () {
+    return jest.fn().mockImplementation(function () { return { tick: jest.fn() }; });
+});
+const AppUtils = __importStar(require("../appUtils"));
+const fUtils = __importStar(require("../FileUtils"));
+const commands_1 = require("../commands");
+describe("refresh — --metadata-only and --force are mutually exclusive", function () {
+    beforeEach(function () {
+        jest.clearAllMocks();
+        jest.spyOn(AppUtils, "syncManifest").mockResolvedValue(undefined);
+    });
+    afterEach(function () {
+        jest.restoreAllMocks();
+    });
+    test("rejects the combination instead of silently picking one", async function () {
+        // Silently honouring --force here would overwrite every field file from the
+        // instance for someone who explicitly asked to touch nothing but metaData.
+        await expect((0, commands_1.refreshCommand)({ metadataOnly: true, force: true })).rejects.toThrow(/--metadata-only cannot be combined with --force/);
+    });
+    test("does not reach syncManifest when the combination is refused", async function () {
+        await expect((0, commands_1.refreshCommand)({ metadataOnly: true, force: true })).rejects.toThrow();
+        expect(AppUtils.syncManifest).not.toHaveBeenCalled();
+    });
+    test("each flag on its own is accepted", async function () {
+        await (0, commands_1.refreshCommand)({ metadataOnly: true });
+        await (0, commands_1.refreshCommand)({ force: true });
+        expect(AppUtils.syncManifest).toHaveBeenCalledTimes(2);
+        expect(AppUtils.syncManifest.mock.calls[0][1]).toMatchObject({
+            metadataOnly: true,
+            force: false,
+        });
+        expect(AppUtils.syncManifest.mock.calls[1][1]).toMatchObject({
+            metadataOnly: false,
+            force: true,
+        });
+    });
+});
+describe("FileUtils directory predicates — pick the right one deliberately", function () {
+    var tmpRoot;
+    var dir;
+    var file;
+    var missing;
+    beforeEach(function () {
+        tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), "dove-dirpred-"));
+        dir = path.join(tmpRoot, "a-directory");
+        file = path.join(tmpRoot, "a-file");
+        missing = path.join(tmpRoot, "does-not-exist");
+        fs.mkdirSync(dir);
+        fs.writeFileSync(file, "x");
+    });
+    afterEach(function () {
+        try {
+            fs.rmSync(tmpRoot, { recursive: true, force: true });
+        }
+        catch (e) { }
+    });
+    test("isExistingDirectory: true only for a real directory, never throws", async function () {
+        expect(await fUtils.isExistingDirectory(dir)).toBe(true);
+        expect(await fUtils.isExistingDirectory(file)).toBe(false);
+        expect(await fUtils.isExistingDirectory(missing)).toBe(false);
+    });
+    test("isDirectory still REJECTS on a missing path (documented, relied on)", async function () {
+        // getPathsInPath treats a missing path as an error rather than a file, so
+        // this rejection is deliberate. Pinning it stops a well-meaning "fix" from
+        // changing that behaviour silently.
+        expect(await fUtils.isDirectory(dir)).toBe(true);
+        expect(await fUtils.isDirectory(file)).toBe(false);
+        await expect(fUtils.isDirectory(missing)).rejects.toThrow();
+    });
+    test("pathExists is true for a plain file — why it is the wrong write-target check", async function () {
+        expect(await fUtils.pathExists(file)).toBe(true);
+        expect(await fUtils.isExistingDirectory(file)).toBe(false);
+    });
+});

package/dist/tests/stampMetadataContent.test.js

@@ -172,6 +172,15 @@ describe("stampMetadataContent — display_value DROPPED where it is churn", ()
         const out = (0, appUtils_1.stampMetadataContent)(metaFile({ controlled_by_refs: { value: null, display_value: "" } }));
         expect(parse(out).controlled_by_refs).toEqual({ value: null });
     });
+    it("does not treat two different objects as identical", () => {
+        // String({}) collapses every object to "[object Object]", so a naive
+        // stringify-and-compare would call these equal and drop a display_value
+        // that carries real information. Non-primitives are simply not comparable.
+        const out = (0, appUtils_1.stampMetadataContent)(metaFile({
+            weird: { value: { a: 1 }, display_value: { b: 2 } },
+        }));
+        expect(parse(out).weird.display_value).toEqual({ b: 2 });
+    });
 });
 describe("stampMetadataContent — display_value KEPT where it is information", () => {
     it("keeps a reference's human name (the sys_id -> name mapping)", () => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tenonhq/dovetail-core",
-  "version": "0.0.117",
+  "version": "0.0.118",
   "description": "Next-gen file syncer",
   "license": "GPL-3.0",
   "main": "./dist/index.js",

package/release-manifest.json

@@ -1,7 +1,33 @@
 {
   "$schema": "dovetail-manifest/v1",
-  "generated_at": "2026-07-28T06:17:01.139Z",
+  "generated_at": "2026-07-28T06:44:03.536Z",
   "events": [
+    {
+      "$schema": "dovetail-release-event/v1",
+      "event_id": "dovetail-core@0.0.117",
+      "package": "@tenonhq/dovetail-core",
+      "version": "0.0.117",
+      "prev_version": "0.0.116",
+      "published_at": "2026-07-28T06:44:03.528Z",
+      "git": {
+        "sha": "47199bcf436db3be5b8fd6728265444e72a96bc0",
+        "tag": "dovetail-core@0.0.117"
+      },
+      "semver_bump": "patch",
+      "commits": [
+        {
+          "sha": "47199bcf4",
+          "subject": "fix(core): keep informative display_value, drop only the churning kinds (#250)",
+          "pr": 250
+        },
+        {
+          "sha": "afd387889",
+          "subject": "chore(release): @tenonhq/dovetail-core@0.0.116 [skip ci]"
+        }
+      ],
+      "exports_delta": null,
+      "narrative": null
+    },
     {
       "$schema": "dovetail-release-event/v1",
       "event_id": "dovetail-core@0.0.116",
@@ -1228,32 +1254,6 @@
       ],
       "exports_delta": null,
       "narrative": null
-    },
-    {
-      "$schema": "dovetail-release-event/v1",
-      "event_id": "dovetail-servicenow@0.0.21",
-      "package": "@tenonhq/dovetail-servicenow",
-      "version": "0.0.21",
-      "prev_version": "0.0.20",
-      "published_at": "2026-06-15T17:59:30.698Z",
-      "git": {
-        "sha": "51e4e4592d491cd337f5bc1aa93d04f582f555a1",
-        "tag": "dovetail-servicenow@0.0.21"
-      },
-      "semver_bump": "patch",
-      "commits": [
-        {
-          "sha": "51e4e4592",
-          "subject": "feat(mcp): per-call instance retarget for servicenow_query_table (#180)",
-          "pr": 180
-        },
-        {
-          "sha": "c5d9106c4",
-          "subject": "chore(release): publish 2 packages [skip ci]"
-        }
-      ],
-      "exports_delta": null,
-      "narrative": null
     }
   ]
 }