@tenonhq/dovetail-core 0.0.117 → 0.0.119

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/MultiScopeWatcher.js

@@ -560,17 +560,10 @@ class MultiScopeWatcherManager {
         try {
             const { defaultClient } = await Promise.resolve().then(() => __importStar(require("./snClient")));
             const client = defaultClient();
-            // Create axios client directly to get update set details
-            const axios = (await Promise.resolve().then(() => __importStar(require("axios")))).default;
-            const { SN_USER = "", SN_PASSWORD = "", SN_INSTANCE = "" } = process.env;
-            const axiosClient = axios.create({
-                auth: {
-                    username: SN_USER,
-                    password: SN_PASSWORD
-                },
-                baseURL: SN_INSTANCE
-            });
-            const response = await axiosClient.get(`/api/now/table/sys_update_set/${updateSetId}`, {
+            // Reuse the shared client's axios instance — it carries the resolved
+            // auth mode (inbound API key or basic) so this read never drifts from
+            // the rest of the tool's transport.
+            const response = await client.client.get(`/api/now/table/sys_update_set/${updateSetId}`, {
                 params: {
                     sysparm_fields: "name,state,sys_id"
                 }

package/dist/allScopesCommands.js

@@ -301,10 +301,12 @@ async function initScopesCommand(args) {
         Logger_1.logger.info(`Using ${apiDelay}ms delay between API calls to prevent server overload`);
     }
     try {
-        // First check if we have environment variables set
+        // First check if we have environment variables set. SN_USER stays
+        // required even in API-key mode (acting-user resolution); the password
+        // is optional once an inbound SN_API_KEY is set.
         if (!process.env.SN_USER ||
-            !process.env.SN_PASSWORD ||
-            !process.env.SN_INSTANCE) {
+            !process.env.SN_INSTANCE ||
+            (!process.env.SN_PASSWORD && !process.env.SN_API_KEY)) {
             try {
                 let loginAnswers = await (0, wizard_1.getLoginInfo)();
                 await (0, wizard_1.setupDotEnv)(loginAnswers);
@@ -314,9 +316,9 @@ async function initScopesCommand(args) {
                 throw error;
             }
             if (!process.env.SN_USER ||
-                !process.env.SN_PASSWORD ||
-                !process.env.SN_INSTANCE) {
-                Logger_1.logger.error("Missing ServiceNow credentials. Please ensure SN_USER, SN_PASSWORD, and SN_INSTANCE are set in your .env file");
+                !process.env.SN_INSTANCE ||
+                (!process.env.SN_PASSWORD && !process.env.SN_API_KEY)) {
+                Logger_1.logger.error("Missing ServiceNow credentials. Please ensure SN_USER, SN_INSTANCE, and SN_PASSWORD (or SN_API_KEY) are set in your .env file");
                 throw new Error("ServiceNow credentials not configured");
             }
         }
@@ -371,12 +373,14 @@ async function watchAllScopesCommand(args) {
     (0, commands_1.setLogLevel)(args);
     var dashboardProcess = null;
     try {
-        // First check if we have environment variables set
+        // First check if we have environment variables set. SN_USER stays
+        // required even in API-key mode; the password is optional once an
+        // inbound SN_API_KEY is set.
         if (!process.env.SN_USER ||
-            !process.env.SN_PASSWORD ||
-            !process.env.SN_INSTANCE) {
+            !process.env.SN_INSTANCE ||
+            (!process.env.SN_PASSWORD && !process.env.SN_API_KEY)) {
             let loginAnswers = await (0, wizard_1.getLoginInfo)();
-            Logger_1.logger.error("Missing ServiceNow credentials. Please ensure SN_USER, SN_PASSWORD, and SN_INSTANCE are set in your .env file");
+            Logger_1.logger.error("Missing ServiceNow credentials. Please ensure SN_USER, SN_INSTANCE, and SN_PASSWORD (or SN_API_KEY) are set in your .env file");
             throw new Error("ServiceNow credentials not configured");
         }
         // Start dashboard unless --no-dashboard flag is set

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/initSystem/corePlugin.js

@@ -98,6 +98,15 @@ exports.corePlugin = {
             },
             required: true,
         },
+        {
+            envKey: "SN_API_KEY",
+            prompt: {
+                type: "password",
+                message: "Inbound API key (optional, Enter to skip — becomes the default auth when set):",
+                mask: "*",
+            },
+            required: false,
+        },
     ],
     configure: [
         {
@@ -105,7 +114,7 @@ exports.corePlugin = {
             label: "Selecting ServiceNow applications",
             run: async (context) => {
                 var baseUrl = instanceBaseUrl(context.env.SN_INSTANCE);
-                var client = (0, snClient_1.snClient)(baseUrl, context.env.SN_USER, context.env.SN_PASSWORD);
+                var client = (0, snClient_1.snClient)(baseUrl, context.env.SN_USER, context.env.SN_PASSWORD, context.env.SN_API_KEY);
                 Logger_1.logger.info("Fetching application list...");
                 var apps = await (0, snClient_1.unwrapSNResponse)(client.getAppList());
                 if (apps.length === 0) {
@@ -303,13 +312,16 @@ async function validateCoreLogin(context) {
     const instance = context.env.SN_INSTANCE;
     const user = context.env.SN_USER;
     const password = context.env.SN_PASSWORD;
-    if (!instance || !user || !password) {
+    const apiKey = context.env.SN_API_KEY;
+    // SN_USER stays required even in API-key mode — the client's user-preference
+    // logic (current app / update set pinning) resolves the acting user from it.
+    if (!instance || !user || (!password && !apiKey)) {
         return "Missing required credentials";
     }
     const instanceUrl = normalizeInstance(instance);
     const baseUrl = instanceBaseUrl(instance);
     try {
-        const client = (0, snClient_1.snClient)(baseUrl, user, password);
+        const client = (0, snClient_1.snClient)(baseUrl, user, password, apiKey);
         await (0, snClient_1.unwrapSNResponse)(client.getAppList());
         context.env.SN_INSTANCE = instanceUrl;
         return true;
@@ -321,7 +333,7 @@ async function validateCoreLogin(context) {
             return "Instance not found — check the URL (got: " + instanceUrl + ")";
         }
         if (status === 401 || msg.includes("401")) {
-            return "Invalid username or password.";
+            return "Invalid credentials — check the username/password (or the API key and its REST API access policies).";
         }
         if (status === 403 || msg.includes("403")) {
             return "Access denied — user may lack required roles.";

package/dist/reconcileCommand.js

@@ -95,11 +95,13 @@ function getUpdateSetConfig() {
 }
 const execFileAsync = (0, util_1.promisify)(child_process_1.execFile);
 function requireCreds() {
-    const { SN_USER = "", SN_PASSWORD = "", SN_INSTANCE = "" } = process.env;
-    if (!SN_USER || !SN_PASSWORD || !SN_INSTANCE) {
-        throw new Error("Missing ServiceNow credentials. Ensure SN_INSTANCE, SN_USER, and SN_PASSWORD are set in your .env file or environment.");
+    const { SN_USER = "", SN_PASSWORD = "", SN_INSTANCE = "", SN_API_KEY = "", } = process.env;
+    // SN_USER stays required even in API-key mode (acting-user resolution);
+    // the password becomes optional once an inbound API key is set.
+    if (!SN_USER || !SN_INSTANCE || (!SN_PASSWORD && !SN_API_KEY)) {
+        throw new Error("Missing ServiceNow credentials. Ensure SN_INSTANCE, SN_USER, and SN_PASSWORD (or SN_API_KEY) are set in your .env file or environment.");
     }
-    return { SN_USER, SN_PASSWORD, SN_INSTANCE };
+    return { SN_USER, SN_PASSWORD, SN_INSTANCE, SN_API_KEY };
 }
 function normalizeInstance(instance) {
     return instance.replace(/^https?:\/\//, "").replace(/\/$/, "");
@@ -158,6 +160,7 @@ async function buildSchemaDiffs(options) {
             instance: creds.SN_INSTANCE,
             username: creds.SN_USER,
             password: creds.SN_PASSWORD,
+            apiKey: creds.SN_API_KEY,
             outputDir: tmpDir,
             scopes,
         });

package/dist/schemaCommand.js

@@ -46,11 +46,13 @@ const path_1 = __importDefault(require("path"));
 const os_1 = __importDefault(require("os"));
 const fs_1 = require("fs");
 function requireCreds() {
-    const { SN_USER = "", SN_PASSWORD = "", SN_INSTANCE = "" } = process.env;
-    if (!SN_USER || !SN_PASSWORD || !SN_INSTANCE) {
-        throw new Error("Missing ServiceNow credentials. Ensure SN_INSTANCE, SN_USER, and SN_PASSWORD are set in your .env file or environment.");
+    const { SN_USER = "", SN_PASSWORD = "", SN_INSTANCE = "", SN_API_KEY = "", } = process.env;
+    // SN_USER stays required even in API-key mode (acting-user resolution);
+    // the password becomes optional once an inbound API key is set.
+    if (!SN_USER || !SN_INSTANCE || (!SN_PASSWORD && !SN_API_KEY)) {
+        throw new Error("Missing ServiceNow credentials. Ensure SN_INSTANCE, SN_USER, and SN_PASSWORD (or SN_API_KEY) are set in your .env file or environment.");
     }
-    return { SN_USER, SN_PASSWORD, SN_INSTANCE };
+    return { SN_USER, SN_PASSWORD, SN_INSTANCE, SN_API_KEY };
 }
 function normalizeInstance(instance) {
     return instance.replace(/^https?:\/\//, "").replace(/\/$/, "");
@@ -74,7 +76,7 @@ function outputDirFor(args) {
     return args.output ? path_1.default.resolve(args.output) : path_1.default.join(rootDir, "schema");
 }
 async function schemaPullCommand(args) {
-    const { SN_USER, SN_PASSWORD, SN_INSTANCE } = requireCreds();
+    const { SN_USER, SN_PASSWORD, SN_INSTANCE, SN_API_KEY } = requireCreds();
     const scopes = resolveScopes(args);
     const outputDir = outputDirFor(args);
     try {
@@ -82,6 +84,7 @@ async function schemaPullCommand(args) {
             instance: SN_INSTANCE,
             username: SN_USER,
             password: SN_PASSWORD,
+            apiKey: SN_API_KEY,
             outputDir,
             scopes,
         });
@@ -119,6 +122,7 @@ async function resolveRefDir(options) {
             instance: creds.SN_INSTANCE,
             username: creds.SN_USER,
             password: creds.SN_PASSWORD,
+            apiKey: creds.SN_API_KEY,
             outputDir: tmpDir,
             scopes,
         });

package/dist/snClient.js

@@ -243,17 +243,26 @@ const processPushResponse = (response, recSummary) => {
     };
 };
 exports.processPushResponse = processPushResponse;
-const snClient = (baseURL, username, password) => {
+const snClient = (baseURL, username, password, apiKey) => {
     const jar = new tough_cookie_1.CookieJar();
+    // When an inbound API key is supplied it is the default auth mode: the
+    // x-sn-apikey header replaces basic auth entirely. Requires key-enabled
+    // REST API access policies on the instance.
+    const baseHeaders = {
+        "Content-Type": "application/json",
+    };
+    if (apiKey) {
+        baseHeaders["x-sn-apikey"] = apiKey;
+    }
     const rawAxios = (0, axios_cookiejar_support_1.wrapper)(axios_1.default.create({
         withCredentials: true,
-        auth: {
-            username,
-            password,
-        },
-        headers: {
-            "Content-Type": "application/json",
-        },
+        auth: apiKey
+            ? undefined
+            : {
+                username,
+                password,
+            },
+        headers: baseHeaders,
         baseURL,
         jar,
     }));
@@ -540,8 +549,8 @@ const defaultClient = () => {
     if (internalClient) {
         return internalClient;
     }
-    const { SN_USER = "", SN_PASSWORD = "", SN_INSTANCE = "" } = process.env;
-    internalClient = (0, exports.snClient)(`https://${SN_INSTANCE}/`, SN_USER, SN_PASSWORD);
+    const { SN_USER = "", SN_PASSWORD = "", SN_INSTANCE = "", SN_API_KEY = "", } = process.env;
+    internalClient = (0, exports.snClient)(`https://${SN_INSTANCE}/`, SN_USER, SN_PASSWORD, SN_API_KEY);
     return internalClient;
 };
 exports.defaultClient = defaultClient;

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/snClient.apiKey.test.js

@@ -0,0 +1,40 @@
+"use strict";
+// Auth-mode tests for snClient: an inbound API key (4th param) becomes the
+// x-sn-apikey header on the real axios instance and basic auth is NOT set;
+// without a key the existing basic-auth behavior is unchanged. Also covers
+// defaultClient() picking SN_API_KEY out of the environment.
+Object.defineProperty(exports, "__esModule", { value: true });
+var mockLogger = {
+    info: jest.fn(),
+    debug: jest.fn(),
+    warn: jest.fn(),
+    error: jest.fn(),
+    getLogLevel: function () { return "debug"; },
+};
+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("../genericUtils", function () {
+    return { wait: jest.fn().mockResolvedValue(undefined) };
+});
+const snClient_1 = require("../snClient");
+describe("snClient — auth mode", function () {
+    it("key mode: sets x-sn-apikey header and no basic auth", function () {
+        var c = (0, snClient_1.snClient)("https://x.service-now.com/", "user", "pass", "key-123");
+        expect(c.client.defaults.headers["x-sn-apikey"]).toBe("key-123");
+        expect(c.client.defaults.auth).toBeUndefined();
+    });
+    it("basic mode: sets basic auth and no x-sn-apikey header", function () {
+        var c = (0, snClient_1.snClient)("https://x.service-now.com/", "user", "pass");
+        expect(c.client.defaults.auth).toEqual({ username: "user", password: "pass" });
+        expect(c.client.defaults.headers["x-sn-apikey"]).toBeUndefined();
+    });
+    it("empty-string key falls back to basic auth", function () {
+        var c = (0, snClient_1.snClient)("https://x.service-now.com/", "user", "pass", "");
+        expect(c.client.defaults.auth).toEqual({ username: "user", password: "pass" });
+        expect(c.client.defaults.headers["x-sn-apikey"]).toBeUndefined();
+    });
+});

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/dist/wizard.js

@@ -24,17 +24,25 @@ async function getLoginInfo() {
             name: "password",
             message: "What is your password on that instance?",
         },
+        {
+            type: "password",
+            name: "apiKey",
+            message: "Inbound API key (optional, Enter to skip — becomes the default auth when set)?",
+        },
     ]);
 }
 async function setupDotEnv(answers) {
     process.env.SN_USER = answers.username;
     process.env.SN_PASSWORD = answers.password;
     process.env.SN_INSTANCE = answers.instance;
-    (0, FileUtils_1.writeEnvVars)({
-        vars: [
-            { key: "SN_USER", value: answers.username },
-            { key: "SN_PASSWORD", value: answers.password },
-            { key: "SN_INSTANCE", value: answers.instance },
-        ],
-    });
+    var vars = [
+        { key: "SN_USER", value: answers.username },
+        { key: "SN_PASSWORD", value: answers.password },
+        { key: "SN_INSTANCE", value: answers.instance },
+    ];
+    if (answers.apiKey) {
+        process.env.SN_API_KEY = answers.apiKey;
+        vars.push({ key: "SN_API_KEY", value: answers.apiKey });
+    }
+    (0, FileUtils_1.writeEnvVars)({ vars: vars });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tenonhq/dovetail-core",
-  "version": "0.0.117",
+  "version": "0.0.119",
   "description": "Next-gen file syncer",
   "license": "GPL-3.0",
   "main": "./dist/index.js",
@@ -22,7 +22,7 @@
     "node": ">=22"
   },
   "devDependencies": {
-    "@tenonhq/dovetail-types": "~0.0.20",
+    "@tenonhq/dovetail-types": "~0.0.21",
     "@types/dotenv": "^6.1.1",
     "@types/inquirer": "^8.2.10",
     "@types/jest": "^29.5.5",
@@ -39,7 +39,7 @@
   },
   "dependencies": {
     "@tenonhq/dovetail-clickup": "~0.0.13",
-    "@tenonhq/dovetail-schema": "~0.0.12",
+    "@tenonhq/dovetail-schema": "~0.0.13",
     "axios": "^1.5.1",
     "axios-cookiejar-support": "^4.0.7",
     "axios-rate-limit": "^1.3.0",

package/release-manifest.json

@@ -1,7 +1,111 @@
 {
   "$schema": "dovetail-manifest/v1",
-  "generated_at": "2026-07-28T06:17:01.139Z",
+  "generated_at": "2026-07-28T22:07:08.748Z",
   "events": [
+    {
+      "$schema": "dovetail-release-event/v1",
+      "event_id": "dovetail-servicenow@0.0.35",
+      "package": "@tenonhq/dovetail-servicenow",
+      "version": "0.0.35",
+      "prev_version": "0.0.34",
+      "published_at": "2026-07-28T22:07:08.734Z",
+      "git": {
+        "sha": "44c5d85d6b3232119e47397da43344b4185f94ff",
+        "tag": "dovetail-servicenow@0.0.35"
+      },
+      "semver_bump": "patch",
+      "commits": [
+        {
+          "sha": "44c5d85d6",
+          "subject": "feat(servicenow): remove-choices verb — soft-delete choice values (DEV-511) (#237)",
+          "pr": 237
+        },
+        {
+          "sha": "c80d5cc24",
+          "subject": "feat(servicenow): S1 execution-context gate + WRITE_DESTRUCTIVE tier (DEV-507) (#239)",
+          "pr": 239
+        },
+        {
+          "sha": "1749ba4f0",
+          "subject": "chore(release): publish 2 packages [skip ci]"
+        }
+      ],
+      "exports_delta": null,
+      "narrative": null
+    },
+    {
+      "$schema": "dovetail-release-event/v1",
+      "event_id": "dovetail-mcp@0.0.32",
+      "package": "@tenonhq/dovetail-mcp",
+      "version": "0.0.32",
+      "prev_version": "0.0.31",
+      "published_at": "2026-07-28T22:07:08.734Z",
+      "git": {
+        "sha": "44c5d85d6b3232119e47397da43344b4185f94ff",
+        "tag": "dovetail-mcp@0.0.32"
+      },
+      "semver_bump": "patch",
+      "commits": [
+        {
+          "sha": "1749ba4f0",
+          "subject": "chore(release): publish 2 packages [skip ci]"
+        }
+      ],
+      "exports_delta": null,
+      "narrative": null
+    },
+    {
+      "$schema": "dovetail-release-event/v1",
+      "event_id": "dovetail-core@0.0.118",
+      "package": "@tenonhq/dovetail-core",
+      "version": "0.0.118",
+      "prev_version": "0.0.117",
+      "published_at": "2026-07-28T07:09:33.080Z",
+      "git": {
+        "sha": "e4193968a18d54df70f599a15e2b7b940fa491b9",
+        "tag": "dovetail-core@0.0.118"
+      },
+      "semver_bump": "patch",
+      "commits": [
+        {
+          "sha": "e4193968a",
+          "subject": "fix(core): close review findings from the metaData work (#251)",
+          "pr": 251
+        },
+        {
+          "sha": "f245dd850",
+          "subject": "chore(release): @tenonhq/dovetail-core@0.0.117 [skip ci]"
+        }
+      ],
+      "exports_delta": null,
+      "narrative": null
+    },
+    {
+      "$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",
@@ -1150,110 +1254,6 @@
       ],
       "exports_delta": null,
       "narrative": null
-    },
-    {
-      "$schema": "dovetail-release-event/v1",
-      "event_id": "dovetail-babel-plugin@0.0.11",
-      "package": "@tenonhq/dovetail-babel-plugin",
-      "version": "0.0.11",
-      "prev_version": "0.0.10",
-      "published_at": "2026-06-16T01:18:07.728Z",
-      "git": {
-        "sha": "edabc263bd89f08b5c7a075f270c2172e82da4da",
-        "tag": "dovetail-babel-plugin@0.0.11"
-      },
-      "semver_bump": "patch",
-      "commits": [
-        {
-          "sha": "edabc263b",
-          "subject": "chore(deps): bump @babel/core from 7.29.0 to 7.29.6 (#181)",
-          "pr": 181
-        },
-        {
-          "sha": "de9d77971",
-          "subject": "chore(release): publish 14 packages [skip ci]"
-        }
-      ],
-      "exports_delta": null,
-      "narrative": null
-    },
-    {
-      "$schema": "dovetail-release-event/v1",
-      "event_id": "dovetail-babel-plugin-remove-modules@0.0.11",
-      "package": "@tenonhq/dovetail-babel-plugin-remove-modules",
-      "version": "0.0.11",
-      "prev_version": "0.0.10",
-      "published_at": "2026-06-16T01:18:07.728Z",
-      "git": {
-        "sha": "edabc263bd89f08b5c7a075f270c2172e82da4da",
-        "tag": "dovetail-babel-plugin-remove-modules@0.0.11"
-      },
-      "semver_bump": "patch",
-      "commits": [
-        {
-          "sha": "edabc263b",
-          "subject": "chore(deps): bump @babel/core from 7.29.0 to 7.29.6 (#181)",
-          "pr": 181
-        },
-        {
-          "sha": "de9d77971",
-          "subject": "chore(release): publish 14 packages [skip ci]"
-        }
-      ],
-      "exports_delta": null,
-      "narrative": null
-    },
-    {
-      "$schema": "dovetail-release-event/v1",
-      "event_id": "dovetail-babel-preset-servicenow@0.0.11",
-      "package": "@tenonhq/dovetail-babel-preset-servicenow",
-      "version": "0.0.11",
-      "prev_version": "0.0.10",
-      "published_at": "2026-06-16T01:18:07.728Z",
-      "git": {
-        "sha": "edabc263bd89f08b5c7a075f270c2172e82da4da",
-        "tag": "dovetail-babel-preset-servicenow@0.0.11"
-      },
-      "semver_bump": "patch",
-      "commits": [
-        {
-          "sha": "edabc263b",
-          "subject": "chore(deps): bump @babel/core from 7.29.0 to 7.29.6 (#181)",
-          "pr": 181
-        },
-        {
-          "sha": "de9d77971",
-          "subject": "chore(release): publish 14 packages [skip ci]"
-        }
-      ],
-      "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
     }
   ]
 }