@tenonhq/dovetail-core 0.0.107 → 0.0.109

package/dist/FileLogger.js

@@ -37,6 +37,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.fileLogger = void 0;
+exports.shouldEnableFileLogging = shouldEnableFileLogging;
 exports.enableFileLogging = enableFileLogging;
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
@@ -45,14 +46,58 @@ const chalk_1 = __importDefault(require("chalk"));
 // Long-running sessions (e.g. `dove watch`) would otherwise grow a single
 // debug log unbounded; capping at 200 writes per file keeps each one small.
 const ROTATION_WRITE_LIMIT = 200;
+// Truthy spellings accepted for the DOVETAIL_DEBUG env var.
+const TRUTHY = /^(1|true|yes|on)$/i;
+/**
+ * @description Decide whether the file logger should write `dovetail-debug-*.log`
+ * files to disk. File logging is OFF by default and only turns on when the user
+ * explicitly opts in — either the `--debug` CLI flag (`--debug` or
+ * `--debug=<truthy>`) or the `DOVETAIL_DEBUG` env var set to a truthy value.
+ * Pure and side-effect free so it can be unit-tested with injected inputs.
+ * @param {string[]} argv - CLI args after the node + script entries (process.argv.slice(2)).
+ * @param {NodeJS.ProcessEnv} env - Environment map (defaults to an empty object).
+ * @returns {boolean} true when file logging should be enabled.
+ */
+function shouldEnableFileLogging(argv = [], env = {}) {
+    const raw = typeof env.DOVETAIL_DEBUG === "string" ? env.DOVETAIL_DEBUG.trim() : "";
+    if (TRUTHY.test(raw))
+        return true;
+    const args = Array.isArray(argv) ? argv : [];
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === "--debug")
+            return true;
+        const eq = typeof arg === "string" ? arg.match(/^--debug=(.*)$/) : null;
+        if (eq)
+            return TRUTHY.test(eq[1].trim());
+    }
+    return false;
+}
 class FileLogger {
     logFilePath;
     logStream = null;
     initialized = false;
     writeCount = 0;
+    // File logging is opt-in — nothing touches disk unless this is true. Seeded
+    // from `--debug` / DOVETAIL_DEBUG so a stray log file is never created just by
+    // running a command; can also be flipped on at runtime via enable().
+    enabled;
     constructor() {
         // Initialize on first use
         this.logFilePath = "";
+        this.enabled = shouldEnableFileLogging(Array.isArray(process.argv) ? process.argv.slice(2) : [], process.env);
+    }
+    /**
+     * Turn file logging on for this process (programmatic opt-in). Idempotent.
+     */
+    enable() {
+        this.enabled = true;
+    }
+    /**
+     * Whether file logging is currently active.
+     */
+    isEnabled() {
+        return this.enabled;
     }
     /**
      * Initialize the file logger in the current working directory
@@ -109,6 +154,11 @@ class FileLogger {
      * Write a message to the log file
      */
     writeToFile(message) {
+        // Opt-in gate: without --debug / DOVETAIL_DEBUG we never create or write a
+        // log file. Console output (info/warn/error/success) still happens because
+        // those methods log to the console before calling writeToFile.
+        if (!this.enabled)
+            return;
         if (!this.initialized) {
             this.initialize();
         }
@@ -215,6 +265,8 @@ const fileLogger = new FileLogger();
 exports.fileLogger = fileLogger;
 // Also export a function to replace console.log globally
 function enableFileLogging() {
+    // Opt in to file logging even if neither --debug nor DOVETAIL_DEBUG was set.
+    fileLogger.enable();
     // Store original console.log
     const originalConsoleLog = console.log;
     // Override console.log to also write to file

package/dist/appUtils.js

@@ -60,6 +60,27 @@ const getUpdateSetConfig = () => (0, updateSetConfig_1.readUpdateSetConfig)();
 // (/<table>.do?sys_id=...) resolves against whatever instance the reader is on.
 // Matches any *.service-now.com host so the output is portable across instances.
 const stripRecordLinkHost = (link) => link.replace(/^https?:\/\/[^/]+\.service-now\.com/i, "");
+// Strip the derived `display_value` from every field pair, keeping only `value`.
+// A ServiceNow field is serialized as a { value, display_value } pair. The
+// display_value is the *current* display name of the field's value — for a
+// reference field, the referenced record's name, resolved live on the server at
+// pull time. That makes it non-deterministic on disk: rename a referenced record
+// on the instance and every metaData.json pointing at it re-churns its
+// display_value on the next pull, even though the pointing record is unchanged.
+// `value` (the sys_id / raw value) is the stable identity; display_value is a
+// convenience the mirror does not need. Reconcile already ignores metaData.json
+// content and pushes key off `value` / the manifest, so no consumer depends on
+// the persisted display_value. Dropping it keeps re-pulls byte-identical.
+const stripFieldDisplayValues = (metadata) => {
+    for (const key of Object.keys(metadata)) {
+        const field = metadata[key];
+        if (field !== null &&
+            typeof field === "object" &&
+            "display_value" in field) {
+            delete field.display_value;
+        }
+    }
+};
 // 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.
@@ -81,6 +102,7 @@ const stampMetadataContent = (file) => {
         if (typeof metadata._record_link === "string") {
             metadata._record_link = stripRecordLinkHost(metadata._record_link);
         }
+        stripFieldDisplayValues(metadata);
         return { ...file, content: JSON.stringify(metadata, null, 2) };
     }
     catch (e) {

package/dist/commander.js

@@ -31,6 +31,12 @@ async function initCommands() {
         describe: "Path to a .env file to load for this command (default: .env in the project root). Lets one checkout target multiple instances.",
     })
         .global("env")
+        .option("debug", {
+        type: "boolean",
+        default: false,
+        describe: "Write a dovetail-debug-*.log file for this command (off by default; also enabled by DOVETAIL_DEBUG=1).",
+    })
+        .global("debug")
         .command(["watch", "w", "watchAllScopes"], "Watch all scopes for file changes and sync to ServiceNow", (cmdArgs) => {
         cmdArgs.options({
             ...sharedOptions,

package/dist/tests/fileLoggerEnableGate.test.js

@@ -0,0 +1,140 @@
+"use strict";
+/**
+ * Regression: `dove` used to drop a `dovetail-debug-*.log` file into the cwd on
+ * EVERY invocation, because the file logger lazily created its file on the first
+ * write and `index.ts` logs "Starting Dovetail..." (plus scattered debug traces)
+ * on every command. The file logger is now opt-in — it only touches disk when
+ * the user asks for it via `--debug` or `DOVETAIL_DEBUG`.
+ *
+ * These tests cover:
+ *  - the pure decision helper (`shouldEnableFileLogging`), and
+ *  - the singleton's disk behavior: writes no file by default, writes once
+ *    enabled, while console output is unaffected in both states.
+ */
+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"));
+const FileLogger_1 = require("../FileLogger");
+function countDebugLogs(dir) {
+    return fs.readdirSync(dir).filter((f) => /^dovetail-debug-.*\.log$/.test(f))
+        .length;
+}
+// The file logger opens its stream asynchronously; poll until a predicate holds.
+async function waitFor(predicate, timeoutMs = 2000) {
+    const start = Date.now();
+    while (!predicate()) {
+        if (Date.now() - start > timeoutMs) {
+            throw new Error("waitFor: condition not met before timeout");
+        }
+        await new Promise((resolve) => setTimeout(resolve, 10));
+    }
+}
+describe("shouldEnableFileLogging (pure)", () => {
+    it("is OFF by default — no flag, no env", () => {
+        expect((0, FileLogger_1.shouldEnableFileLogging)([], {})).toBe(false);
+        expect((0, FileLogger_1.shouldEnableFileLogging)(["push", "--diff", "main"], {})).toBe(false);
+    });
+    it("turns ON with the --debug flag", () => {
+        expect((0, FileLogger_1.shouldEnableFileLogging)(["push", "--debug"], {})).toBe(true);
+        expect((0, FileLogger_1.shouldEnableFileLogging)(["--debug", "status"], {})).toBe(true);
+    });
+    it("honors --debug=<value>", () => {
+        expect((0, FileLogger_1.shouldEnableFileLogging)(["--debug=true"], {})).toBe(true);
+        expect((0, FileLogger_1.shouldEnableFileLogging)(["--debug=1"], {})).toBe(true);
+        expect((0, FileLogger_1.shouldEnableFileLogging)(["--debug=false"], {})).toBe(false);
+        expect((0, FileLogger_1.shouldEnableFileLogging)(["--debug=0"], {})).toBe(false);
+    });
+    it("turns ON with a truthy DOVETAIL_DEBUG env var", () => {
+        for (const v of ["1", "true", "TRUE", "yes", "on", " on "]) {
+            expect((0, FileLogger_1.shouldEnableFileLogging)([], { DOVETAIL_DEBUG: v })).toBe(true);
+        }
+    });
+    it("stays OFF for a falsy/empty DOVETAIL_DEBUG env var", () => {
+        for (const v of ["", "0", "false", "no", "off"]) {
+            expect((0, FileLogger_1.shouldEnableFileLogging)([], { DOVETAIL_DEBUG: v })).toBe(false);
+        }
+    });
+    it("tolerates non-array argv defensively", () => {
+        expect((0, FileLogger_1.shouldEnableFileLogging)(undefined, {})).toBe(false);
+    });
+});
+describe("fileLogger disk gate", () => {
+    let tmpDir;
+    let cwdSpy;
+    let logSpy;
+    let errSpy;
+    beforeEach(() => {
+        tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "dovetail-log-gate-"));
+        cwdSpy = jest.spyOn(process, "cwd").mockReturnValue(tmpDir);
+        logSpy = jest.spyOn(console, "log").mockImplementation(() => undefined);
+        errSpy = jest.spyOn(console, "error").mockImplementation(() => undefined);
+    });
+    afterEach(async () => {
+        FileLogger_1.fileLogger.close();
+        // Let any in-flight stream close settle before removing the directory.
+        await new Promise((resolve) => setTimeout(resolve, 20));
+        cwdSpy.mockRestore();
+        logSpy.mockRestore();
+        errSpy.mockRestore();
+        fs.rmSync(tmpDir, { recursive: true, force: true });
+    });
+    it("writes NO log file when disabled (jest runs with no --debug / env)", () => {
+        expect(FileLogger_1.fileLogger.isEnabled()).toBe(false);
+        FileLogger_1.fileLogger.debug("should not create a file");
+        FileLogger_1.fileLogger.info("informational");
+        FileLogger_1.fileLogger.warn("warning");
+        FileLogger_1.fileLogger.error("boom");
+        expect(countDebugLogs(tmpDir)).toBe(0);
+        expect(FileLogger_1.fileLogger.getLogFilePath()).toBe("");
+    });
+    it("still prints info to the console when disabled", () => {
+        FileLogger_1.fileLogger.info("visible to the user");
+        expect(logSpy).toHaveBeenCalled();
+    });
+    it("creates and writes a log file once enabled", async () => {
+        FileLogger_1.fileLogger.enable();
+        expect(FileLogger_1.fileLogger.isEnabled()).toBe(true);
+        FileLogger_1.fileLogger.debug("now this lands on disk");
+        // Path is assigned synchronously in initialize(); the stream opens async.
+        const logPath = FileLogger_1.fileLogger.getLogFilePath();
+        expect(logPath.startsWith(tmpDir)).toBe(true);
+        expect(/dovetail-debug-.*\.log$/.test(path.basename(logPath))).toBe(true);
+        await waitFor(() => fs.existsSync(logPath) &&
+            fs.readFileSync(logPath, "utf8").includes("now this lands on disk"));
+        expect(countDebugLogs(tmpDir)).toBe(1);
+    });
+});

package/dist/tests/stampMetadataContent.test.js

@@ -60,3 +60,49 @@ describe("stampMetadataContent — _record_link host stripping", () => {
         expect((0, appUtils_1.stampMetadataContent)(script)).toEqual(script);
     });
 });
+describe("stampMetadataContent — display_value stripping", () => {
+    it("drops display_value from field pairs, keeping value", () => {
+        const out = (0, appUtils_1.stampMetadataContent)(metaFile({
+            sys_updated_on: { value: "2025-08-21 17:09:02" },
+            action: {
+                value: "85de623c33ef2a107b18bc534d5c7b92",
+                display_value: "Parse hashes for to_addresses",
+            },
+        }));
+        const parsed = parse(out);
+        expect(parsed.action).toEqual({
+            value: "85de623c33ef2a107b18bc534d5c7b92",
+        });
+        expect(parsed.action.display_value).toBeUndefined();
+    });
+    it("strips every field's display_value in one pass", () => {
+        const out = (0, appUtils_1.stampMetadataContent)(metaFile({
+            a: { value: "1", display_value: "One" },
+            b: { value: "2", display_value: "Two" },
+        }));
+        const parsed = parse(out);
+        expect(parsed.a).toEqual({ value: "1" });
+        expect(parsed.b).toEqual({ value: "2" });
+    });
+    it("leaves value-only fields and string keys untouched", () => {
+        const out = (0, appUtils_1.stampMetadataContent)(metaFile({
+            sys_updated_on: { value: "2025-08-21 17:09:02" },
+            _record_link: "/incident.do?sys_id=1",
+            name: { value: "plain" },
+        }));
+        const parsed = parse(out);
+        expect(parsed.sys_updated_on).toEqual({ value: "2025-08-21 17:09:02" });
+        expect(parsed.name).toEqual({ value: "plain" });
+        expect(parsed._record_link).toBe("/incident.do?sys_id=1");
+    });
+    it("is idempotent — a display-value-free record stays byte-identical", () => {
+        const clean = {
+            sys_updated_on: { value: "2025-08-21 17:09:02" },
+            action: { value: "abc" },
+            _record_link: "/incident.do?sys_id=1",
+        };
+        const first = (0, appUtils_1.stampMetadataContent)(metaFile(clean));
+        const second = (0, appUtils_1.stampMetadataContent)(first);
+        expect(second.content).toBe(first.content);
+    });
+});

package/package.json

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