@tenonhq/dovetail-core 0.0.114 → 0.0.116

package/dist/tests/metadataOnlyManifestGate.test.js

@@ -0,0 +1,196 @@
+"use strict";
+/**
+ * Regression: `dove refresh --metadata-only` must not write the scope manifest.
+ *
+ * The mode's contract — stated in its CLI help and in CLAUDE.md — is that the
+ * resulting git diff is `metaData.json` and nothing else. The first
+ * implementation gated `ConfigManager.updateManifest` (the in-MEMORY manifest
+ * update) but not `fUtils.writeScopeManifest` (the actual FILE write), so a real
+ * run against tenonworkstudio rewrote all 8 `dove.manifest.x_cadso_*.json`
+ * files with unrelated record-name disambiguation drift.
+ *
+ * The companion tests in syncManifestRefresh.test.ts could not catch this: that
+ * suite mocks `writeScopeManifest` to a no-op, so nothing there ever observes
+ * the write. That mock is why the bug shipped.
+ *
+ * So this file deliberately leaves FileUtils REAL and asserts against the
+ * filesystem — the manifest file on disk must be byte-identical after a
+ * metadata-only run, and must still be updated by a plain refresh (proving the
+ * gate is scoped, not a blanket disable).
+ */
+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"));
+// ---------- mocks (must come before importing the module under test) ----------
+var mockLogger = {
+    info: jest.fn(),
+    debug: jest.fn(),
+    warn: jest.fn(),
+    error: jest.fn(),
+    success: jest.fn(),
+    getLogLevel: function () { return "warn"; },
+};
+var mockFileLogger = {
+    debug: jest.fn(),
+    info: jest.fn(),
+    warn: jest.fn(),
+    error: jest.fn(),
+};
+var mockClient = {
+    getManifest: jest.fn(),
+    getMissingFiles: jest.fn(),
+};
+jest.mock("../Logger", function () { return { logger: mockLogger }; });
+jest.mock("../FileLogger", function () { return { fileLogger: mockFileLogger }; });
+jest.mock("../snClient", function () {
+    return {
+        defaultClient: function () { return mockClient; },
+        unwrapSNResponse: function (p) { return Promise.resolve(p); },
+        processPushResponse: jest.fn(),
+        retryOnErr: jest.fn(),
+        retryOnHttpErr: jest.fn(),
+        unwrapTableAPIFirstItem: jest.fn(),
+    };
+});
+var manifestPath = "";
+var mockConfig = {
+    getConfig: jest.fn().mockReturnValue({
+        scopes: { x_cadso_core: {} },
+        tableOptions: {},
+    }),
+    getManifest: jest.fn().mockResolvedValue({
+        x_cadso_core: { scope: "x_cadso_core", tables: {} },
+    }),
+    getSourcePathForScope: jest.fn(),
+    getSourcePath: jest.fn(),
+    getManifestPath: jest.fn(function () { return manifestPath; }),
+    // The real writeScopeManifest resolves its target through this.
+    getScopeManifestPath: jest.fn(function () { return manifestPath; }),
+    resolveConfigForScope: jest.fn().mockReturnValue({
+        tables: ["sys_script_include"],
+        fieldOverrides: {},
+        apiIncludes: {},
+        apiExcludes: {},
+    }),
+    isMultiScopeManifest: jest.fn().mockReturnValue(true),
+    updateManifest: jest.fn(),
+};
+jest.mock("../config", function () { return mockConfig; });
+jest.mock("progress", function () {
+    return jest.fn().mockImplementation(function () {
+        return { tick: jest.fn() };
+    });
+});
+// NOTE: FileUtils is deliberately NOT mocked. Stubbing writeScopeManifest is
+// exactly what hid this bug.
+const AppUtils = __importStar(require("../appUtils"));
+// ---------- scaffolding ----------
+var tmpRoot;
+var SENTINEL = JSON.stringify({ tables: { sentinel: "untouched" } }, null, 2);
+function writeLocalRecord(record, content) {
+    var recDir = path.join(tmpRoot, "sys_script_include", record);
+    fs.mkdirSync(recDir, { recursive: true });
+    fs.writeFileSync(path.join(recDir, "script.js"), content);
+}
+function serverResponse(record, scriptContent) {
+    var records = {};
+    records[record] = {
+        name: record,
+        sys_id: "sysid_" + record,
+        files: [
+            { name: "script", type: "js", content: scriptContent },
+            {
+                name: "metaData",
+                type: "json",
+                content: JSON.stringify({
+                    sys_updated_on: { value: "2026-04-29 14:38:51" },
+                    _record_link: "https://tenonworkstudio.service-now.com/x.do?sys_id=1",
+                }),
+            },
+        ],
+    };
+    return { sys_script_include: { records: records } };
+}
+describe("--metadata-only does not write the scope manifest (real FileUtils)", function () {
+    beforeEach(function () {
+        jest.clearAllMocks();
+        tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), "dove-manifest-gate-"));
+        manifestPath = path.join(tmpRoot, "dove.manifest.x_cadso_core.json");
+        fs.writeFileSync(manifestPath, SENTINEL);
+        mockConfig.getSourcePathForScope.mockReturnValue(tmpRoot);
+        mockConfig.getSourcePath.mockReturnValue(tmpRoot);
+        // The manifest the "instance" returns differs from the sentinel on disk, so
+        // any write at all is detectable.
+        mockClient.getManifest.mockResolvedValue({
+            scope: "x_cadso_core",
+            tables: {
+                sys_script_include: {
+                    records: {
+                        Rec: { name: "Rec", sys_id: "sysid_Rec", files: [{ name: "script", type: "js" }] },
+                    },
+                },
+            },
+        });
+        mockClient.getMissingFiles.mockResolvedValue(serverResponse("Rec", "var x = 1;"));
+    });
+    afterEach(function () {
+        try {
+            fs.rmSync(tmpRoot, { recursive: true, force: true });
+        }
+        catch (e) { }
+    });
+    test("leaves the manifest file byte-identical", async function () {
+        writeLocalRecord("Rec", "var x = 1;");
+        await AppUtils.syncManifest("x_cadso_core", { metadataOnly: true });
+        expect(mockLogger.error).not.toHaveBeenCalled();
+        expect(fs.readFileSync(manifestPath, "utf8")).toBe(SENTINEL);
+    });
+    test("still rewrites the record's metaData.json (the gate is narrow)", async function () {
+        writeLocalRecord("Rec", "var x = 1;");
+        await AppUtils.syncManifest("x_cadso_core", { metadataOnly: true });
+        var meta = fs.readFileSync(path.join(tmpRoot, "sys_script_include", "Rec", "metaData.json"), "utf8");
+        expect(JSON.parse(meta)._record_link).toBe("/x.do?sys_id=1");
+    });
+    test("a plain refresh DOES write the manifest", async function () {
+        // Proves the gate is conditional, not a blanket disable — without this a
+        // hard-coded skip would pass the test above.
+        writeLocalRecord("Rec", "var x = 1;");
+        await AppUtils.syncManifest("x_cadso_core");
+        expect(fs.readFileSync(manifestPath, "utf8")).not.toBe(SENTINEL);
+        expect(JSON.parse(fs.readFileSync(manifestPath, "utf8")).tables).toHaveProperty("sys_script_include");
+    });
+});

package/dist/tests/stampMetadataContent.test.js

@@ -2,16 +2,23 @@
 // Tests for stampMetadataContent — the writer that finalizes each record's
 // metaData.json before it lands on disk.
 //
-// Two on-disk-stability concerns are covered:
-//   1. _lastUpdatedOn is sourced from the record's sys_updated_on (stable across
-//      re-pulls) rather than a fresh wall-clock stamp.
+// The contract is determinism: the same record must produce the same bytes on
+// any instance, from any machine, on every pull. Three on-disk-stability
+// concerns are covered:
+//   1. No generation-time value survives. `_lastUpdatedOn` is deleted outright —
+//      it duplicated sys_updated_on.value exactly, and its no-sys_updated_on
+//      branch stamped a wall-clock that rewrote the file on every pull.
 //   2. _record_link is rewritten to an instance-relative path. The CADSO metadata
 //      endpoint returns an absolute URL (https://<instance>.service-now.com/...);
 //      persisting the host makes the artifact instance-bound and dirties every
 //      file on a re-pull from a different instance. Stripping any *.service-now.com
 //      host keeps the diff to genuine schema changes.
+//   3. display_value is stripped — it is resolved live server-side, so renaming
+//      a referenced record re-churns every file pointing at it.
 Object.defineProperty(exports, "__esModule", { value: true });
 const appUtils_1 = require("../appUtils");
+// Matches an ISO-8601 wall-clock stamp (what `new Date().toISOString()` emits).
+const ISO_STAMP = /\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}/;
 const metaFile = (content) => ({
     name: "metaData",
     type: "json",
@@ -46,13 +53,13 @@ describe("stampMetadataContent — _record_link host stripping", () => {
         const out = (0, appUtils_1.stampMetadataContent)(metaFile({ _record_link: null }));
         expect(parse(out)._record_link).toBeNull();
     });
-    it("still sources _lastUpdatedOn from sys_updated_on while stripping the host", () => {
+    it("strips the host while leaving the record's own sys_updated_on intact", () => {
         const out = (0, appUtils_1.stampMetadataContent)(metaFile({
             sys_updated_on: { value: "2025-08-21 17:09:02" },
             _record_link: "https://tenonworkstudio.service-now.com/incident.do?sys_id=1",
         }));
         const parsed = parse(out);
-        expect(parsed._lastUpdatedOn).toBe("2025-08-21 17:09:02");
+        expect(parsed.sys_updated_on).toEqual({ value: "2025-08-21 17:09:02" });
         expect(parsed._record_link).toBe("/incident.do?sys_id=1");
     });
     it("passes through non-metaData files verbatim", () => {
@@ -60,6 +67,57 @@ describe("stampMetadataContent — _record_link host stripping", () => {
         expect((0, appUtils_1.stampMetadataContent)(script)).toEqual(script);
     });
 });
+describe("stampMetadataContent — no generation-time values", () => {
+    it("never writes _lastUpdatedOn, even when sys_updated_on is present", () => {
+        const out = (0, appUtils_1.stampMetadataContent)(metaFile({ sys_updated_on: { value: "2025-08-21 17:09:02" } }));
+        expect(parse(out)._lastUpdatedOn).toBeUndefined();
+    });
+    it("deletes a pre-existing _lastUpdatedOn so a re-stamp settles legacy content", () => {
+        // A branch pulled before this change carries the key on disk. Re-stamping
+        // has to remove it, otherwise the stale value persists forever and the
+        // mirror never converges.
+        const out = (0, appUtils_1.stampMetadataContent)(metaFile({
+            sys_updated_on: { value: "2025-08-21 17:09:02" },
+            _lastUpdatedOn: "2025-08-21 17:09:02",
+            _record_link: "/incident.do?sys_id=1",
+        }));
+        const parsed = parse(out);
+        expect(parsed._lastUpdatedOn).toBeUndefined();
+        expect(parsed._record_link).toBe("/incident.do?sys_id=1");
+    });
+    it("emits no wall-clock stamp when sys_updated_on is absent", () => {
+        // The old fallback stamped new Date().toISOString() here, which is what
+        // made every pull dirty the record.
+        const out = (0, appUtils_1.stampMetadataContent)(metaFile({ name: { value: "no audit columns" } }));
+        expect(out.content).not.toMatch(ISO_STAMP);
+        expect(parse(out)._lastUpdatedOn).toBeUndefined();
+    });
+    it("writes the deterministic placeholder for empty content", () => {
+        const out = (0, appUtils_1.stampMetadataContent)({ name: "metaData", type: "json", content: "" });
+        expect(out.content).toBe(appUtils_1.EMPTY_METADATA_CONTENT);
+        expect(out.content).not.toMatch(ISO_STAMP);
+    });
+    it("produces identical bytes across repeated runs (the whole point)", () => {
+        const server = {
+            sys_updated_on: { value: "2025-08-21 17:09:02", display_value: "2025-08-21 10:09:02" },
+            action: { value: "abc", display_value: "Some Record Name" },
+            _record_link: "https://tenonworkstudio.service-now.com/incident.do?sys_id=1",
+            _lastUpdatedOn: "2025-08-21 17:09:02",
+        };
+        // Two independent pulls of an unchanged record, one re-stamp of the result.
+        const first = (0, appUtils_1.stampMetadataContent)(metaFile(server));
+        const second = (0, appUtils_1.stampMetadataContent)(metaFile(server));
+        const restamped = (0, appUtils_1.stampMetadataContent)(first);
+        expect(second.content).toBe(first.content);
+        expect(restamped.content).toBe(first.content);
+    });
+    it("leaves non-object JSON alone rather than throwing", () => {
+        const bare = { name: "metaData", type: "json", content: '"just a string"' };
+        expect((0, appUtils_1.stampMetadataContent)(bare)).toEqual(bare);
+        const arr = { name: "metaData", type: "json", content: "[1,2,3]" };
+        expect((0, appUtils_1.stampMetadataContent)(arr)).toEqual(arr);
+    });
+});
 describe("stampMetadataContent — display_value stripping", () => {
     it("drops display_value from field pairs, keeping value", () => {
         const out = (0, appUtils_1.stampMetadataContent)(metaFile({

package/dist/tests/syncManifestRefresh.test.js

@@ -285,3 +285,162 @@ describe("syncManifest — refresh pulls instance edits down", function () {
         expect(Object.keys(missingArg.sys_script_include).sort()).toEqual(["sysid_RecA", "sysid_RecB"]);
     });
 });
+/**
+ * `--metadata-only` exists so a mirror can be settled after a change to the
+ * metadata writer without the source churn `--force` produces. The guarantee it
+ * has to make is narrow and total: the resulting diff is metaData.json and
+ * nothing else — no field file, no manifest, no new record directory.
+ */
+describe("syncManifest — --metadata-only rewrites metadata and nothing else", function () {
+    beforeEach(function () {
+        jest.clearAllMocks();
+        tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), "sinc-metaonly-test-"));
+        mockConfig.getSourcePathForScope.mockReturnValue(tmpRoot);
+        mockConfig.getSourcePath.mockReturnValue(tmpRoot);
+    });
+    afterEach(function () {
+        try {
+            fs.rmSync(tmpRoot, { recursive: true, force: true });
+        }
+        catch (e) { }
+    });
+    function respondWith(record, files) {
+        var records = {};
+        records[record] = { name: record, sys_id: "sysid_" + record, files: files };
+        mockClient.getMissingFiles.mockResolvedValue({
+            sys_script_include: { records: records },
+        });
+    }
+    test("rewrites metaData.json even though no field file changed", async function () {
+        var identical = "var same = true;";
+        writeLocal("Rec", "script", "js", identical);
+        mockClient.getManifest.mockResolvedValue(setupScope([{ record: "Rec", name: "script", type: "js", content: "" }]));
+        respondWith("Rec", [
+            { name: "script", type: "js", content: identical },
+            {
+                name: "metaData",
+                type: "json",
+                content: JSON.stringify({
+                    sys_updated_on: { value: "2026-04-29 14:38:51", display_value: "2026-04-29 07:38:51" },
+                    _record_link: "https://tenonworkstudio.service-now.com/sys_script_include.do?sys_id=1",
+                    _lastUpdatedOn: "2026-04-29 14:38:51",
+                }),
+            },
+        ]);
+        await AppUtils.syncManifest("x_cadso_core", { metadataOnly: true });
+        var meta = readLocal("Rec", "metaData", "json");
+        expect(meta).not.toBeNull();
+        var parsed = JSON.parse(meta);
+        // Normalized on the way in — the whole reason to regenerate.
+        expect(parsed._record_link).toBe("/sys_script_include.do?sys_id=1");
+        expect(parsed._lastUpdatedOn).toBeUndefined();
+        expect(meta).not.toContain("display_value");
+    });
+    test("does not touch field files, even when the instance content differs", async function () {
+        writeLocal("Rec", "script", "js", "var local = 1;");
+        var beforeMtime = statMtime("Rec", "script", "js");
+        mockClient.getManifest.mockResolvedValue(setupScope([{ record: "Rec", name: "script", type: "js", content: "" }]));
+        respondWith("Rec", [
+            { name: "script", type: "js", content: "var fromInstance = 2;" },
+            { name: "metaData", type: "json", content: JSON.stringify({ sys_id: { value: "1" } }) },
+        ]);
+        await new Promise(function (r) { setTimeout(r, 10); });
+        await AppUtils.syncManifest("x_cadso_core", { metadataOnly: true });
+        // Unchanged on disk AND untouched — a rewrite with identical bytes would
+        // still be a write, and this mode promises none.
+        expect(readLocal("Rec", "script", "js")).toBe("var local = 1;");
+        expect(statMtime("Rec", "script", "js")).toBe(beforeMtime);
+    });
+    test("skips records that are not checked out locally (no orphan directories)", async function () {
+        // Writing metaData for a record with no directory would leave a folder
+        // holding a lone metaData.json and zero field files.
+        //
+        // The absent-record check MUST NOT throw. syncManifest swallows errors into
+        // logger.error, so an exception here would abort the whole scope while this
+        // test's file assertions still passed — "no directory, no metaData" is
+        // trivially true when nothing ran. The logger.error assertion is what makes
+        // this test real: it caught fUtils.isDirectory rejecting on ENOENT.
+        mockClient.getManifest.mockResolvedValue(setupScope([{ record: "NotOnDisk", name: "script", type: "js", content: "" }]));
+        respondWith("NotOnDisk", [
+            { name: "script", type: "js", content: "// new on the instance" },
+            { name: "metaData", type: "json", content: JSON.stringify({ sys_id: { value: "1" } }) },
+        ]);
+        await AppUtils.syncManifest("x_cadso_core", { metadataOnly: true });
+        expect(mockLogger.error).not.toHaveBeenCalled();
+        expect(fs.existsSync(path.join(tmpRoot, "sys_script_include", "NotOnDisk"))).toBe(false);
+        expect(readLocal("NotOnDisk", "metaData", "json")).toBeNull();
+    });
+    test("an absent record does not stop the records that ARE checked out", async function () {
+        // The real shape of a metadata-only run: the instance holds records this
+        // branch never pulled, interleaved with ones it did. An abort on the first
+        // absent record would silently settle only part of the mirror.
+        writeLocal("OnDisk", "script", "js", "var x = 1;");
+        mockClient.getManifest.mockResolvedValue(setupScope([
+            { record: "Absent", name: "script", type: "js", content: "" },
+            { record: "OnDisk", name: "script", type: "js", content: "" },
+        ]));
+        mockClient.getMissingFiles.mockResolvedValue({
+            sys_script_include: {
+                records: {
+                    Absent: {
+                        name: "Absent",
+                        sys_id: "sysid_Absent",
+                        files: [
+                            { name: "script", type: "js", content: "// only on the instance" },
+                            { name: "metaData", type: "json", content: JSON.stringify({ sys_id: { value: "a" } }) },
+                        ],
+                    },
+                    OnDisk: {
+                        name: "OnDisk",
+                        sys_id: "sysid_OnDisk",
+                        files: [
+                            { name: "script", type: "js", content: "var x = 1;" },
+                            {
+                                name: "metaData",
+                                type: "json",
+                                content: JSON.stringify({
+                                    sys_id: { value: "b" },
+                                    _record_link: "https://tenonworkstudio.service-now.com/x.do?sys_id=b",
+                                }),
+                            },
+                        ],
+                    },
+                },
+            },
+        });
+        await AppUtils.syncManifest("x_cadso_core", { metadataOnly: true });
+        expect(mockLogger.error).not.toHaveBeenCalled();
+        // The absent one stayed absent...
+        expect(fs.existsSync(path.join(tmpRoot, "sys_script_include", "Absent"))).toBe(false);
+        // ...and the present one was still settled.
+        var meta = readLocal("OnDisk", "metaData", "json");
+        expect(meta).not.toBeNull();
+        expect(JSON.parse(meta)._record_link).toBe("/x.do?sys_id=b");
+    });
+    test("does not persist the manifest", async function () {
+        writeLocal("Rec", "script", "js", "var x = 1;");
+        mockClient.getManifest.mockResolvedValue(setupScope([{ record: "Rec", name: "script", type: "js", content: "" }]));
+        respondWith("Rec", [
+            { name: "script", type: "js", content: "var x = 1;" },
+            { name: "metaData", type: "json", content: JSON.stringify({ sys_id: { value: "1" } }) },
+        ]);
+        await AppUtils.syncManifest("x_cadso_core", { metadataOnly: true });
+        // A manifest write would put record adds/drops/renames into a diff that is
+        // supposed to be metaData.json only.
+        expect(mockConfig.updateManifest).not.toHaveBeenCalled();
+    });
+    test("a plain refresh still persists the manifest (the gate is scoped)", async function () {
+        writeLocal("Rec", "script", "js", "var x = 1;");
+        mockClient.getManifest.mockResolvedValue(setupScope([{ record: "Rec", name: "script", type: "js", content: "" }]));
+        respondWith("Rec", [{ name: "script", type: "js", content: "var x = 1;" }]);
+        await AppUtils.syncManifest("x_cadso_core");
+        expect(mockConfig.updateManifest).toHaveBeenCalled();
+    });
+    test("writes the deterministic placeholder when the server sends no metadata", async function () {
+        writeLocal("Rec", "script", "js", "var x = 1;");
+        mockClient.getManifest.mockResolvedValue(setupScope([{ record: "Rec", name: "script", type: "js", content: "" }]));
+        respondWith("Rec", [{ name: "script", type: "js", content: "var x = 1;" }]);
+        await AppUtils.syncManifest("x_cadso_core", { metadataOnly: true });
+        expect(readLocal("Rec", "metaData", "json")).toBe(AppUtils.EMPTY_METADATA_CONTENT);
+    });
+});

package/package.json

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