@tenonhq/dovetail-core 0.0.114 → 0.0.115

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.115",
   "description": "Next-gen file syncer",
   "license": "GPL-3.0",
   "main": "./dist/index.js",