@tenonhq/dovetail-core 0.0.91 → 0.0.93

package/dist/commander.js

@@ -15,6 +15,7 @@ const deleteRecordCommand_1 = require("./deleteRecordCommand");
 const migrateCommand_1 = require("./migrateCommand");
 const clickupCommands_1 = require("./clickupCommands");
 const loginCommand_1 = require("./loginCommand");
+const knowledgeDiffCommand_1 = require("./knowledgeDiffCommand");
 const yargs_1 = __importDefault(require("yargs"));
 async function initCommands() {
     const sharedOptions = {
@@ -461,6 +462,35 @@ async function initCommands() {
             .demandCommand(1, "Please specify a task subcommand (e.g., clear)");
     }, function () {
         /* subcommands handle execution */
+    })
+        .command(["knowledge-diff"], "Report Dovetail releases this repo has not documented yet (stages pending events for /dovetail-features-sync)", function (cmdArgs) {
+        cmdArgs.options({
+            ...sharedOptions,
+            manifest: {
+                type: "string",
+                describe: "Path to the Dovetail release manifest (defaults to the bundled one)",
+            },
+            config: {
+                type: "string",
+                describe: "Path to the consumer knowledge-sync config.json",
+            },
+            ledger: {
+                type: "string",
+                describe: "Path to the documented-state ledger.json",
+            },
+            out: {
+                type: "string",
+                describe: "Directory to write pending release-event files",
+            },
+            json: {
+                type: "boolean",
+                default: false,
+                describe: "Print the diff as JSON instead of writing pending files",
+            },
+        });
+        return cmdArgs;
+    }, async function (args) {
+        await (0, knowledgeDiffCommand_1.knowledgeDiffCommand)(args);
     })
         .help().argv;
 }

package/dist/knowledgeDiff.js

@@ -0,0 +1,64 @@
+"use strict";
+// Pure, deterministic core for `dove knowledge-diff`. No fs, no network — unit-testable.
+// Given a Dovetail release manifest (the publish feed) and a consumer repo's
+// documented-state ledger + watch config, returns the release-events the
+// consumer has not documented yet. knowledgeDiffCommand wraps this with I/O to
+// stage pending events for the in-session /dovetail-features-sync skill.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.semverGt = semverGt;
+exports.eventFilename = eventFilename;
+exports.computeDrift = computeDrift;
+// Numeric semver compare for the x.y.z range Dovetail uses (no prerelease tags).
+function semverGt(a, b) {
+    const pa = String(a)
+        .split(".")
+        .map(function (n) {
+        return parseInt(n, 10) || 0;
+    });
+    const pb = String(b)
+        .split(".")
+        .map(function (n) {
+        return parseInt(n, 10) || 0;
+    });
+    for (let i = 0; i < 3; i++) {
+        const da = pa[i] || 0;
+        const db = pb[i] || 0;
+        if (da > db)
+            return true;
+        if (da < db)
+            return false;
+    }
+    return false;
+}
+// Filesystem-safe pending filename: unscoped package name + version.
+function eventFilename(ev) {
+    const unscoped = String(ev.package || "").replace(/^@[^/]+\//, "");
+    return unscoped + "@" + ev.version + ".json";
+}
+// Events newer than the ledger's documented_version, limited to watch_packages
+// (when set) and excluding ignore_packages. Deterministically sorted so callers
+// and tests get a stable order.
+function computeDrift(manifest, ledger, config) {
+    const events = (manifest && manifest.events) || [];
+    const watch = (config && config.watch_packages) || [];
+    const ignore = (config && config.ignore_packages) || [];
+    const ledgerPackages = (ledger && ledger.packages) || {};
+    const drift = [];
+    for (const ev of events) {
+        if (!ev || !ev.package || !ev.version)
+            continue;
+        if (ignore.indexOf(ev.package) !== -1)
+            continue;
+        if (watch.length > 0 && watch.indexOf(ev.package) === -1)
+            continue;
+        const entry = ledgerPackages[ev.package];
+        const documented = entry && entry.documented_version;
+        if (documented && !semverGt(ev.version, documented))
+            continue;
+        drift.push(ev);
+    }
+    drift.sort(function (a, b) {
+        return (a.package + a.version).localeCompare(b.package + b.version);
+    });
+    return drift;
+}

package/dist/knowledgeDiffCommand.js

@@ -0,0 +1,121 @@
+"use strict";
+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 });
+exports.knowledgeDiffCommand = knowledgeDiffCommand;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const commands_1 = require("./commands");
+const Logger_1 = require("./Logger");
+const knowledgeDiff_1 = require("./knowledgeDiff");
+function readJson(filePath) {
+    return JSON.parse(fs.readFileSync(filePath, "utf8"));
+}
+function resolveManifestPath(explicit) {
+    if (explicit)
+        return path.resolve(explicit);
+    // Bundled inside @tenonhq/dovetail-core at publish time (see publish-on-merge.js).
+    // __dirname is <pkg>/dist at runtime, so ".." is the installed package root.
+    return path.resolve(__dirname, "..", "release-manifest.json");
+}
+// `dove knowledge-diff` — pure, deterministic detector. Compares the Dovetail
+// release manifest against this repo's documented-state ledger and stages the
+// undocumented release-events for the in-session /dovetail-features-sync skill.
+// No network, no LLM — safe to run at install or in CI.
+async function knowledgeDiffCommand(args) {
+    (0, commands_1.setLogLevel)(args);
+    const cwd = process.cwd();
+    const configPath = args.config
+        ? path.resolve(args.config)
+        : path.join(cwd, "context", "dovetail-releases", "config.json");
+    let config = {};
+    if (fs.existsSync(configPath)) {
+        config = readJson(configPath);
+    }
+    else {
+        Logger_1.logger.warn("knowledge-diff: no config at " + configPath + "; watching all packages.");
+    }
+    const manifestPath = resolveManifestPath(args.manifest);
+    if (!fs.existsSync(manifestPath)) {
+        Logger_1.logger.warn("knowledge-diff: no release manifest at " +
+            manifestPath +
+            " — nothing to diff (Dovetail publish writes it).");
+        return;
+    }
+    const manifest = readJson(manifestPath);
+    let ledgerPath;
+    if (args.ledger) {
+        ledgerPath = path.resolve(args.ledger);
+    }
+    else if (config.ledger) {
+        ledgerPath = path.resolve(cwd, config.ledger);
+    }
+    else {
+        ledgerPath = path.join(cwd, "context", "dovetail-releases", "ledger.json");
+    }
+    const ledger = fs.existsSync(ledgerPath)
+        ? readJson(ledgerPath)
+        : { packages: {} };
+    const drift = (0, knowledgeDiff_1.computeDrift)(manifest, ledger, config);
+    if (args.json) {
+        process.stdout.write(JSON.stringify({ count: drift.length, events: drift }, null, 2) + "\n");
+        return;
+    }
+    if (drift.length === 0) {
+        Logger_1.logger.info("knowledge-diff: no new Dovetail releases to document.");
+        return;
+    }
+    let outDir;
+    if (args.out) {
+        outDir = path.resolve(args.out);
+    }
+    else if (config.pending_dir) {
+        outDir = path.resolve(cwd, config.pending_dir);
+    }
+    else {
+        outDir = path.join(cwd, "context", "dovetail-releases", "pending");
+    }
+    if (!fs.existsSync(outDir)) {
+        fs.mkdirSync(outDir, { recursive: true });
+    }
+    for (const ev of drift) {
+        const dest = path.join(outDir, (0, knowledgeDiff_1.eventFilename)(ev));
+        fs.writeFileSync(dest, JSON.stringify(ev, null, 2) + "\n");
+    }
+    Logger_1.logger.info("knowledge-diff: wrote " +
+        drift.length +
+        " pending release-event(s) to " +
+        path.relative(cwd, outDir) +
+        ". Run /dovetail-features-sync to document them.");
+}

package/dist/snClient.js

@@ -75,9 +75,46 @@ function _resetDovetailApiFallback() {
 function _isUsingLegacyClaudePath() {
     return _dovetailApiUseLegacyClaudePath;
 }
+// SN returns 400 with this body when a Scripted REST endpoint does not exist
+// at the requested URI. The /dovetail -> /claude fallback above only fires on
+// 404, so the same "endpoint missing" condition presents as an opaque 400 to
+// callers. Detect it and surface a clear hint.
+var _SN_MISSING_ENDPOINT_BODY = "Requested URI does not represent any resource";
+function _summarizeResponseBody(data) {
+    if (data === undefined || data === null)
+        return "";
+    try {
+        var asJson = typeof data === "string" ? data : JSON.stringify(data);
+        return asJson.length > 500 ? asJson.slice(0, 500) + "…" : asJson;
+    }
+    catch (_) {
+        return String(data);
+    }
+}
+// Augment an axios error in place with a human-readable message describing
+// the attempted Dovetail REST call. Preserves .response/.code/.config so
+// existing callers and tests that inspect those fields keep working.
+function _enrichDovetailApiError(e, attemptedEndpoint) {
+    if (!axios_1.default.isAxiosError(e))
+        return e;
+    var status = e.response ? e.response.status : undefined;
+    var body = e.response ? _summarizeResponseBody(e.response.data) : "";
+    var missingEndpoint = status === 400 && body.indexOf(_SN_MISSING_ENDPOINT_BODY) !== -1;
+    var hint = missingEndpoint
+        ? " — Scripted REST endpoint not found on this instance. Re-import the Dovetail Scripted REST API XML (see Dovetail/docs/dovetail-servicenow-migration.md)."
+        : "";
+    e.message =
+        "Dovetail REST call failed: " +
+            (status ? "HTTP " + status : "no response") +
+            " " + attemptedEndpoint +
+            (body ? " — " + body : "") +
+            hint;
+    return e;
+}
 async function _callDovetailApi(op, call) {
+    var endpoint = _dovetailEndpoint(op);
     try {
-        return await call(_dovetailEndpoint(op));
+        return await call(endpoint);
     }
     catch (e) {
         if (!_dovetailApiUseLegacyClaudePath && _getHttpStatus(e) === 404) {
@@ -85,9 +122,15 @@ async function _callDovetailApi(op, call) {
                 " returned 404. Falling back to legacy /api/cadso/claude/" + op +
                 ". Re-import the Dovetail Scripted REST API XML on your ServiceNow instance to silence this warning.");
             _dovetailApiUseLegacyClaudePath = true;
-            return await call(_dovetailEndpoint(op));
+            var legacyEndpoint = _dovetailEndpoint(op);
+            try {
+                return await call(legacyEndpoint);
+            }
+            catch (e2) {
+                throw _enrichDovetailApiError(e2, legacyEndpoint);
+            }
         }
-        throw e;
+        throw _enrichDovetailApiError(e, endpoint);
     }
 }
 function _getRetryAfterMs(e) {

package/dist/tests/knowledgeDiff.test.js

@@ -0,0 +1,83 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const knowledgeDiff_1 = require("../knowledgeDiff");
+describe("semverGt", function () {
+    it("compares x.y.z numerically (not lexically)", function () {
+        expect((0, knowledgeDiff_1.semverGt)("0.0.13", "0.0.12")).toBe(true);
+        expect((0, knowledgeDiff_1.semverGt)("0.0.12", "0.0.12")).toBe(false);
+        expect((0, knowledgeDiff_1.semverGt)("0.1.0", "0.0.99")).toBe(true);
+        expect((0, knowledgeDiff_1.semverGt)("1.0.0", "0.9.9")).toBe(true);
+        expect((0, knowledgeDiff_1.semverGt)("0.0.2", "0.0.10")).toBe(false);
+    });
+});
+describe("eventFilename", function () {
+    it("strips the npm scope and appends the version", function () {
+        expect((0, knowledgeDiff_1.eventFilename)({
+            event_id: "x",
+            package: "@tenonhq/dovetail-clickup",
+            version: "0.0.13",
+            prev_version: "0.0.12",
+        })).toBe("dovetail-clickup@0.0.13.json");
+    });
+});
+describe("computeDrift", function () {
+    const manifest = {
+        events: [
+            {
+                event_id: "dovetail-clickup@0.0.13",
+                package: "@tenonhq/dovetail-clickup",
+                version: "0.0.13",
+                prev_version: "0.0.12",
+            },
+            {
+                event_id: "dovetail-core@0.0.93",
+                package: "@tenonhq/dovetail-core",
+                version: "0.0.93",
+                prev_version: "0.0.92",
+            },
+            {
+                event_id: "dovetail-gmail@0.0.11",
+                package: "@tenonhq/dovetail-gmail",
+                version: "0.0.11",
+                prev_version: "0.0.10",
+            },
+        ],
+    };
+    const ledger = {
+        packages: {
+            "@tenonhq/dovetail-clickup": { documented_version: "0.0.12" },
+            "@tenonhq/dovetail-core": { documented_version: "0.0.93" },
+        },
+    };
+    it("returns events newer than the ledger; undocumented packages count as drift", function () {
+        const ids = (0, knowledgeDiff_1.computeDrift)(manifest, ledger, { watch_packages: [] }).map(function (e) {
+            return e.event_id;
+        });
+        expect(ids).toContain("dovetail-clickup@0.0.13"); // 0.0.13 > 0.0.12
+        expect(ids).toContain("dovetail-gmail@0.0.11"); // not in ledger yet
+        expect(ids).not.toContain("dovetail-core@0.0.93"); // equal to documented
+    });
+    it("limits to watch_packages when the set is non-empty", function () {
+        const drift = (0, knowledgeDiff_1.computeDrift)(manifest, ledger, {
+            watch_packages: ["@tenonhq/dovetail-clickup"],
+        });
+        expect(drift.length).toBe(1);
+        expect(drift[0].package).toBe("@tenonhq/dovetail-clickup");
+    });
+    it("excludes ignore_packages", function () {
+        const ids = (0, knowledgeDiff_1.computeDrift)(manifest, ledger, {
+            watch_packages: [],
+            ignore_packages: ["@tenonhq/dovetail-gmail"],
+        }).map(function (e) {
+            return e.event_id;
+        });
+        expect(ids).not.toContain("dovetail-gmail@0.0.11");
+        expect(ids).toContain("dovetail-clickup@0.0.13");
+    });
+    it("is deterministically sorted by package+version", function () {
+        const ids = (0, knowledgeDiff_1.computeDrift)(manifest, ledger, {}).map(function (e) {
+            return e.event_id;
+        });
+        expect(ids).toEqual(["dovetail-clickup@0.0.13", "dovetail-gmail@0.0.11"]);
+    });
+});

package/dist/tests/snClient.fallback.test.js

@@ -21,10 +21,10 @@ jest.mock("../genericUtils", function () {
     return { wait: jest.fn().mockResolvedValue(undefined) };
 });
 const snClient_1 = require("../snClient");
-function makeAxiosError(status) {
+function makeAxiosError(status, data) {
     var error = new Error("Request failed with status " + status);
     error.isAxiosError = true;
-    error.response = { status: status, headers: {}, data: {} };
+    error.response = { status: status, headers: {}, data: data === undefined ? {} : data };
     return error;
 }
 function makeAxiosResponse(data) {
@@ -117,4 +117,84 @@ describe("_callDovetailApi 404 fallback", function () {
         expect((0, snClient_1._isUsingLegacyClaudePath)()).toBe(false);
         expect(mockLogger.warn).not.toHaveBeenCalled();
     });
+    describe("descriptive error enrichment", function () {
+        it("includes status, endpoint, and response body on a 401", async function () {
+            var call = jest.fn(async function (_endpoint) {
+                throw makeAxiosError(401, { error: { message: "User Not Authenticated" } });
+            });
+            try {
+                await (0, snClient_1._callDovetailApi)("changeScope", call);
+                throw new Error("expected rejection");
+            }
+            catch (e) {
+                expect(e.response.status).toBe(401);
+                expect(e.message).toContain("HTTP 401");
+                expect(e.message).toContain("api/cadso/dovetail/changeScope");
+                expect(e.message).toContain("User Not Authenticated");
+            }
+        });
+        it("adds the missing-endpoint hint when SN returns its 400 'Requested URI does not represent any resource'", async function () {
+            var snBody = {
+                error: { message: "Requested URI does not represent any resource", detail: null },
+                status: "failure",
+            };
+            var call = jest.fn(async function (_endpoint) {
+                throw makeAxiosError(400, snBody);
+            });
+            try {
+                await (0, snClient_1._callDovetailApi)("changeScope", call);
+                throw new Error("expected rejection");
+            }
+            catch (e) {
+                expect(e.response.status).toBe(400);
+                expect(e.message).toContain("HTTP 400");
+                expect(e.message).toContain("api/cadso/dovetail/changeScope");
+                expect(e.message).toContain("Re-import the Dovetail Scripted REST API XML");
+            }
+        });
+        it("does NOT add the missing-endpoint hint for unrelated 400s", async function () {
+            var call = jest.fn(async function (_endpoint) {
+                throw makeAxiosError(400, { error: { message: "Invalid scope name" } });
+            });
+            try {
+                await (0, snClient_1._callDovetailApi)("changeScope", call);
+                throw new Error("expected rejection");
+            }
+            catch (e) {
+                expect(e.message).toContain("HTTP 400");
+                expect(e.message).toContain("Invalid scope name");
+                expect(e.message).not.toContain("Re-import the Dovetail Scripted REST API XML");
+            }
+        });
+        it("after fallback latches, errors from the legacy path are also enriched", async function () {
+            var calls = [];
+            var call = jest.fn(async function (endpoint) {
+                calls.push(endpoint);
+                if (endpoint.indexOf("api/cadso/dovetail/") === 0) {
+                    throw makeAxiosError(404, {});
+                }
+                throw makeAxiosError(500, { error: { message: "boom" } });
+            });
+            try {
+                await (0, snClient_1._callDovetailApi)("changeScope", call);
+                throw new Error("expected rejection");
+            }
+            catch (e) {
+                expect(calls).toEqual([
+                    "api/cadso/dovetail/changeScope",
+                    "api/cadso/claude/changeScope",
+                ]);
+                expect(e.response.status).toBe(500);
+                expect(e.message).toContain("HTTP 500");
+                expect(e.message).toContain("api/cadso/claude/changeScope");
+                expect(e.message).toContain("boom");
+            }
+        });
+        it("leaves non-axios errors untouched", async function () {
+            var call = jest.fn(async function (_endpoint) {
+                throw new Error("ECONNREFUSED");
+            });
+            await expect((0, snClient_1._callDovetailApi)("changeScope", call)).rejects.toThrow("ECONNREFUSED");
+        });
+    });
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tenonhq/dovetail-core",
-  "version": "0.0.91",
+  "version": "0.0.93",
   "description": "Next-gen file syncer",
   "license": "GPL-3.0",
   "main": "./dist/index.js",
@@ -61,7 +61,8 @@
   "files": [
     "dist/**/*",
     "skills/**/*",
-    "README.md"
+    "README.md",
+    "release-manifest.json"
   ],
   "publishConfig": {
     "access": "public"

package/release-manifest.json

@@ -0,0 +1,5 @@
+{
+  "$schema": "dovetail-manifest/v1",
+  "generated_at": "2026-05-28T00:00:00Z",
+  "events": []
+}