@nookplot/runtime 0.5.100 → 0.5.106

package/dist/__tests__/querySegmentation.test.js

@@ -0,0 +1,187 @@
+/**
+ * Tests for query segmentation — multi-granularity query expansion for
+ * WakeUpStack L2 retrieval (Change 2 of latent-briefing spec).
+ *
+ * segmentQuery is a pure string function — no I/O, no mocks needed. Each test
+ * asserts a specific invariant of the segmentation contract that the gateway's
+ * multi-query search path depends on.
+ */
+import { describe, it, expect } from "vitest";
+import { segmentQuery, queriesFromSegmented, segmentTaskForQuery, } from "../querySegmentation.js";
+describe("segmentQuery", () => {
+    it("preserves the full trimmed task as .full", () => {
+        const s = segmentQuery("  review the audit findings  ");
+        expect(s.full).toBe("review the audit findings");
+    });
+    it("emits no sliding-window segments for short tasks (< 10 words)", () => {
+        const s = segmentQuery("review this code for security issues please");
+        expect(s.segments).toEqual([]);
+    });
+    it("emits sliding-window segments for long tasks (≥ 10 words)", () => {
+        // 15 words — produces at least one window of 15 words
+        const task = "one two three four five six seven eight nine ten eleven twelve thirteen fourteen fifteen";
+        const s = segmentQuery(task);
+        expect(s.segments.length).toBeGreaterThanOrEqual(1);
+        // First segment should contain the first 15 words
+        expect(s.segments[0]).toBe(task);
+    });
+    it("caps sliding-window segments at maxSegments", () => {
+        // 40 words with stride 8 + window 15 → up to 4 windows, capped at 3 by default
+        const words = Array.from({ length: 40 }, (_, i) => `word${i}`).join(" ");
+        const s = segmentQuery(words);
+        expect(s.segments.length).toBeLessThanOrEqual(3);
+    });
+    it("caps at custom maxSegments", () => {
+        const words = Array.from({ length: 40 }, (_, i) => `word${i}`).join(" ");
+        const s = segmentQuery(words, 2);
+        expect(s.segments.length).toBeLessThanOrEqual(2);
+    });
+    it("extracts hashtags as entities", () => {
+        const s = segmentQuery("discussing #latentspace and #mining topics");
+        expect(s.entities).toContain("#latentspace");
+        expect(s.entities).toContain("#mining");
+    });
+    it("extracts @mentions as entities", () => {
+        const s = segmentQuery("responding to @basedmd about the spec");
+        expect(s.entities).toContain("@basedmd");
+    });
+    it("extracts capitalized multi-word phrases as entities", () => {
+        const s = segmentQuery("Latent Briefing cites MemPalace in the comparison");
+        expect(s.entities).toContain("Latent Briefing");
+        expect(s.entities).not.toContain("MemPalace"); // single word — not captured
+    });
+    it("caps entities at 2", () => {
+        const s = segmentQuery("#a #b #c #d Latent Space Embedding Exchange");
+        expect(s.entities.length).toBeLessThanOrEqual(2);
+    });
+    it("extracts 'what is X' question spans", () => {
+        const s = segmentQuery("what is a knowledge bundle in Nookplot");
+        expect(s.questions.length).toBeGreaterThanOrEqual(1);
+        // The extracted phrase drops the "what is" prefix
+        expect(s.questions[0]).toContain("knowledge bundle");
+    });
+    it("extracts 'how to X' question spans", () => {
+        const s = segmentQuery("how to claim a mining reward safely");
+        expect(s.questions.length).toBeGreaterThanOrEqual(1);
+    });
+    it("emits no questions for non-question queries", () => {
+        const s = segmentQuery("refactor the authentication middleware");
+        expect(s.questions).toEqual([]);
+    });
+    it("handles empty input without throwing", () => {
+        const s = segmentQuery("");
+        expect(s.full).toBe("");
+        expect(s.segments).toEqual([]);
+        expect(s.entities).toEqual([]);
+        expect(s.questions).toEqual([]);
+    });
+    it("handles whitespace-only input without throwing", () => {
+        const s = segmentQuery("   \n\t  ");
+        expect(s.full).toBe("");
+        expect(s.segments).toEqual([]);
+    });
+});
+describe("queriesFromSegmented", () => {
+    it("always places full query first (preserves single-query baseline)", () => {
+        const s = segmentQuery("Latent Briefing explains attention");
+        const q = queriesFromSegmented(s);
+        expect(q[0]).toBe("Latent Briefing explains attention");
+    });
+    it("deduplicates repeated strings", () => {
+        const s = {
+            full: "same query",
+            segments: ["same query"],
+            entities: ["same query"],
+            questions: [],
+        };
+        const q = queriesFromSegmented(s);
+        expect(q.length).toBe(1);
+        expect(q[0]).toBe("same query");
+    });
+    it("drops strings shorter than 2 chars", () => {
+        const s = {
+            full: "real query",
+            segments: [],
+            entities: ["a", "x"],
+            questions: [],
+        };
+        const q = queriesFromSegmented(s);
+        expect(q).toEqual(["real query"]);
+    });
+    it("enforces hard cap at max (default 4)", () => {
+        const s = {
+            full: "full",
+            segments: ["seg1", "seg2", "seg3"],
+            entities: ["#one", "#two"],
+            questions: ["q1"],
+        };
+        const q = queriesFromSegmented(s);
+        expect(q.length).toBeLessThanOrEqual(4);
+        expect(q[0]).toBe("full");
+    });
+    it("respects custom max", () => {
+        const s = {
+            full: "full",
+            segments: ["seg1", "seg2"],
+            entities: ["#one"],
+            questions: ["q1"],
+        };
+        const q = queriesFromSegmented(s, 2);
+        expect(q.length).toBe(2);
+    });
+    it("returns only full when everything else is empty", () => {
+        const s = { full: "just the task", segments: [], entities: [], questions: [] };
+        expect(queriesFromSegmented(s)).toEqual(["just the task"]);
+    });
+    it("preserves order: full, segments, entities, questions", () => {
+        const s = {
+            full: "full task",
+            segments: ["seg-one", "seg-two"],
+            entities: ["#ent"],
+            questions: ["q1"],
+        };
+        const q = queriesFromSegmented(s);
+        // Default max=4 → questions["q1"] gets truncated
+        expect(q).toEqual(["full task", "seg-one", "seg-two", "#ent"]);
+    });
+    it("includes question when under cap", () => {
+        const s = {
+            full: "full task",
+            segments: [],
+            entities: [],
+            questions: ["question phrase"],
+        };
+        const q = queriesFromSegmented(s);
+        expect(q).toEqual(["full task", "question phrase"]);
+    });
+});
+describe("segmentTaskForQuery", () => {
+    it("collapses to a single-element array for short/simple tasks", () => {
+        const q = segmentTaskForQuery("review the PR");
+        expect(q).toEqual(["review the PR"]);
+    });
+    it("expands multi-segment for long queries with entities", () => {
+        const task = "review the Latent Briefing spec changes against our current MemPalace implementation carefully";
+        const q = segmentTaskForQuery(task);
+        // Must have at least the full query; likely picks up "Latent Briefing" as entity
+        expect(q[0]).toBe(task);
+        expect(q.length).toBeGreaterThanOrEqual(1);
+        expect(q.length).toBeLessThanOrEqual(4);
+    });
+    it("enforces 4-query hard cap matching gateway", () => {
+        const words = Array.from({ length: 60 }, (_, i) => `word${i}`).join(" ");
+        const task = `${words} #tag1 #tag2 what is a Knowledge Bundle thing`;
+        const q = segmentTaskForQuery(task);
+        expect(q.length).toBeLessThanOrEqual(4);
+    });
+    it("returns [] for an empty string (guarded by length >= 2 filter)", () => {
+        // full is "" → length 0 → dropped by the >= 2 filter → empty result
+        const q = segmentTaskForQuery("");
+        expect(q).toEqual([]);
+    });
+    it("returns [] for whitespace-only input", () => {
+        const q = segmentTaskForQuery("   ");
+        expect(q).toEqual([]);
+    });
+});
+//# sourceMappingURL=querySegmentation.test.js.map

package/dist/__tests__/querySegmentation.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"querySegmentation.test.js","sourceRoot":"","sources":["../../src/__tests__/querySegmentation.test.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAAE,QAAQ,EAAE,EAAE,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAC9C,OAAO,EACL,YAAY,EACZ,oBAAoB,EACpB,mBAAmB,GACpB,MAAM,yBAAyB,CAAC;AAEjC,QAAQ,CAAC,cAAc,EAAE,GAAG,EAAE;IAC5B,EAAE,CAAC,0CAA0C,EAAE,GAAG,EAAE;QAClD,MAAM,CAAC,GAAG,YAAY,CAAC,+BAA+B,CAAC,CAAC;QACxD,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,2BAA2B,CAAC,CAAC;IACnD,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,+DAA+D,EAAE,GAAG,EAAE;QACvE,MAAM,CAAC,GAAG,YAAY,CAAC,6CAA6C,CAAC,CAAC;QACtE,MAAM,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;IACjC,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,2DAA2D,EAAE,GAAG,EAAE;QACnE,sDAAsD;QACtD,MAAM,IAAI,GACR,0FAA0F,CAAC;QAC7F,MAAM,CAAC,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC;QAC7B,MAAM,CAAC,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,sBAAsB,CAAC,CAAC,CAAC,CAAC;QACpD,kDAAkD;QAClD,MAAM,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACnC,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,6CAA6C,EAAE,GAAG,EAAE;QACrD,+EAA+E;QAC/E,MAAM,KAAK,GAAG,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACzE,MAAM,CAAC,GAAG,YAAY,CAAC,KAAK,CAAC,CAAC;QAC9B,MAAM,CAAC,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,mBAAmB,CAAC,CAAC,CAAC,CAAC;IACnD,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,4BAA4B,EAAE,GAAG,EAAE;QACpC,MAAM,KAAK,GAAG,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACzE,MAAM,CAAC,GAAG,YAAY,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;QACjC,MAAM,CAAC,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,mBAAmB,CAAC,CAAC,CAAC,CAAC;IACnD,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,+BAA+B,EAAE,GAAG,EAAE;QACvC,MAAM,CAAC,GAAG,YAAY,CAAC,4CAA4C,CAAC,CAAC;QACrE,MAAM,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,SAAS,CAAC,cAAc,CAAC,CAAC;QAC7C,MAAM,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,SAAS,CAAC,SAAS,CAAC,CAAC;IAC1C,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,gCAAgC,EAAE,GAAG,EAAE;QACxC,MAAM,CAAC,GAAG,YAAY,CAAC,uCAAuC,CAAC,CAAC;QAChE,MAAM,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,SAAS,CAAC,UAAU,CAAC,CAAC;IAC3C,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,qDAAqD,EAAE,GAAG,EAAE;QAC7D,MAAM,CAAC,GAAG,YAAY,CAAC,mDAAmD,CAAC,CAAC;QAC5E,MAAM,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,SAAS,CAAC,iBAAiB,CAAC,CAAC;QAChD,MAAM,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,GAAG,CAAC,SAAS,CAAC,WAAW,CAAC,CAAC,CAAC,6BAA6B;IAC9E,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,oBAAoB,EAAE,GAAG,EAAE;QAC5B,MAAM,CAAC,GAAG,YAAY,CAAC,6CAA6C,CAAC,CAAC;QACtE,MAAM,CAAC,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,mBAAmB,CAAC,CAAC,CAAC,CAAC;IACnD,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,qCAAqC,EAAE,GAAG,EAAE;QAC7C,MAAM,CAAC,GAAG,YAAY,CAAC,wCAAwC,CAAC,CAAC;QACjE,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,sBAAsB,CAAC,CAAC,CAAC,CAAC;QACrD,kDAAkD;QAClD,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,kBAAkB,CAAC,CAAC;IACvD,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,oCAAoC,EAAE,GAAG,EAAE;QAC5C,MAAM,CAAC,GAAG,YAAY,CAAC,qCAAqC,CAAC,CAAC;QAC9D,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,sBAAsB,CAAC,CAAC,CAAC,CAAC;IACvD,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,6CAA6C,EAAE,GAAG,EAAE;QACrD,MAAM,CAAC,GAAG,YAAY,CAAC,wCAAwC,CAAC,CAAC;QACjE,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;IAClC,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,sCAAsC,EAAE,GAAG,EAAE;QAC9C,MAAM,CAAC,GAAG,YAAY,CAAC,EAAE,CAAC,CAAC;QAC3B,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACxB,MAAM,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;QAC/B,MAAM,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;QAC/B,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;IAClC,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,gDAAgD,EAAE,GAAG,EAAE;QACxD,MAAM,CAAC,GAAG,YAAY,CAAC,WAAW,CAAC,CAAC;QACpC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACxB,MAAM,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;IACjC,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC;AAEH,QAAQ,CAAC,sBAAsB,EAAE,GAAG,EAAE;IACpC,EAAE,CAAC,kEAAkE,EAAE,GAAG,EAAE;QAC1E,MAAM,CAAC,GAAG,YAAY,CAAC,oCAAoC,CAAC,CAAC;QAC7D,MAAM,CAAC,GAAG,oBAAoB,CAAC,CAAC,CAAC,CAAC;QAClC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,oCAAoC,CAAC,CAAC;IAC1D,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,+BAA+B,EAAE,GAAG,EAAE;QACvC,MAAM,CAAC,GAAG;YACR,IAAI,EAAE,YAAY;YAClB,QAAQ,EAAE,CAAC,YAAY,CAAC;YACxB,QAAQ,EAAE,CAAC,YAAY,CAAC;YACxB,SAAS,EAAE,EAAE;SACd,CAAC;QACF,MAAM,CAAC,GAAG,oBAAoB,CAAC,CAAC,CAAC,CAAC;QAClC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QACzB,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;IAClC,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,oCAAoC,EAAE,GAAG,EAAE;QAC5C,MAAM,CAAC,GAAG;YACR,IAAI,EAAE,YAAY;YAClB,QAAQ,EAAE,EAAE;YACZ,QAAQ,EAAE,CAAC,GAAG,EAAE,GAAG,CAAC;YACpB,SAAS,EAAE,EAAE;SACd,CAAC;QACF,MAAM,CAAC,GAAG,oBAAoB,CAAC,CAAC,CAAC,CAAC;QAClC,MAAM,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC;IACpC,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,sCAAsC,EAAE,GAAG,EAAE;QAC9C,MAAM,CAAC,GAAG;YACR,IAAI,EAAE,MAAM;YACZ,QAAQ,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC;YAClC,QAAQ,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC;YAC1B,SAAS,EAAE,CAAC,IAAI,CAAC;SAClB,CAAC;QACF,MAAM,CAAC,GAAG,oBAAoB,CAAC,CAAC,CAAC,CAAC;QAClC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,mBAAmB,CAAC,CAAC,CAAC,CAAC;QACxC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IAC5B,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,qBAAqB,EAAE,GAAG,EAAE;QAC7B,MAAM,CAAC,GAAG;YACR,IAAI,EAAE,MAAM;YACZ,QAAQ,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC;YAC1B,QAAQ,EAAE,CAAC,MAAM,CAAC;YAClB,SAAS,EAAE,CAAC,IAAI,CAAC;SAClB,CAAC;QACF,MAAM,CAAC,GAAG,oBAAoB,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;QACrC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAC3B,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,iDAAiD,EAAE,GAAG,EAAE;QACzD,MAAM,CAAC,GAAG,EAAE,IAAI,EAAE,eAAe,EAAE,QAAQ,EAAE,EAAE,EAAE,QAAQ,EAAE,EAAE,EAAE,SAAS,EAAE,EAAE,EAAE,CAAC;QAC/E,MAAM,CAAC,oBAAoB,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC;IAC7D,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,sDAAsD,EAAE,GAAG,EAAE;QAC9D,MAAM,CAAC,GAAG;YACR,IAAI,EAAE,WAAW;YACjB,QAAQ,EAAE,CAAC,SAAS,EAAE,SAAS,CAAC;YAChC,QAAQ,EAAE,CAAC,MAAM,CAAC;YAClB,SAAS,EAAE,CAAC,IAAI,CAAC;SAClB,CAAC;QACF,MAAM,CAAC,GAAG,oBAAoB,CAAC,CAAC,CAAC,CAAC;QAClC,iDAAiD;QACjD,MAAM,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,WAAW,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,CAAC,CAAC,CAAC;IACjE,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,kCAAkC,EAAE,GAAG,EAAE;QAC1C,MAAM,CAAC,GAAG;YACR,IAAI,EAAE,WAAW;YACjB,QAAQ,EAAE,EAAE;YACZ,QAAQ,EAAE,EAAE;YACZ,SAAS,EAAE,CAAC,iBAAiB,CAAC;SAC/B,CAAC;QACF,MAAM,CAAC,GAAG,oBAAoB,CAAC,CAAC,CAAC,CAAC;QAClC,MAAM,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,WAAW,EAAE,iBAAiB,CAAC,CAAC,CAAC;IACtD,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC;AAEH,QAAQ,CAAC,qBAAqB,EAAE,GAAG,EAAE;IACnC,EAAE,CAAC,4DAA4D,EAAE,GAAG,EAAE;QACpE,MAAM,CAAC,GAAG,mBAAmB,CAAC,eAAe,CAAC,CAAC;QAC/C,MAAM,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC;IACvC,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,sDAAsD,EAAE,GAAG,EAAE;QAC9D,MAAM,IAAI,GACR,gGAAgG,CAAC;QACnG,MAAM,CAAC,GAAG,mBAAmB,CAAC,IAAI,CAAC,CAAC;QACpC,iFAAiF;QACjF,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACxB,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,sBAAsB,CAAC,CAAC,CAAC,CAAC;QAC3C,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,mBAAmB,CAAC,CAAC,CAAC,CAAC;IAC1C,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,4CAA4C,EAAE,GAAG,EAAE;QACpD,MAAM,KAAK,GAAG,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACzE,MAAM,IAAI,GAAG,GAAG,KAAK,+CAA+C,CAAC;QACrE,MAAM,CAAC,GAAG,mBAAmB,CAAC,IAAI,CAAC,CAAC;QACpC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,mBAAmB,CAAC,CAAC,CAAC,CAAC;IAC1C,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,gEAAgE,EAAE,GAAG,EAAE;QACxE,oEAAoE;QACpE,MAAM,CAAC,GAAG,mBAAmB,CAAC,EAAE,CAAC,CAAC;QAClC,MAAM,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;IACxB,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,sCAAsC,EAAE,GAAG,EAAE;QAC9C,MAAM,CAAC,GAAG,mBAAmB,CAAC,KAAK,CAAC,CAAC;QACrC,MAAM,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;IACxB,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}

package/dist/__tests__/sandbox.test.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Sandbox — unit tests.
+ *
+ * Covers:
+ *   - LocalSandbox: exec, python, sh, put/get round-trip, close idempotency.
+ *   - Sandbox.asTools: tool definitions route to python/sh.
+ *   - DockerSandbox.buildRunArgs: --network none, --cpus, --memory defaults +
+ *     port / mount / env serialization. Pure-function tests, no docker required.
+ *   - DockerSandbox.create: mount validation rejects paths outside cwd
+ *     before docker is invoked.
+ */
+export {};
+//# sourceMappingURL=sandbox.test.d.ts.map

package/dist/__tests__/sandbox.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sandbox.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/sandbox.test.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG"}

package/dist/__tests__/sandbox.test.js

@@ -0,0 +1,413 @@
+/**
+ * Sandbox — unit tests.
+ *
+ * Covers:
+ *   - LocalSandbox: exec, python, sh, put/get round-trip, close idempotency.
+ *   - Sandbox.asTools: tool definitions route to python/sh.
+ *   - DockerSandbox.buildRunArgs: --network none, --cpus, --memory defaults +
+ *     port / mount / env serialization. Pure-function tests, no docker required.
+ *   - DockerSandbox.create: mount validation rejects paths outside cwd
+ *     before docker is invoked.
+ */
+import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
+import { promises as fs } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { DEFAULT_SANDBOX_IMAGE, DockerSandbox, LocalSandbox, Sandbox, isSandbox, } from "../sandbox.js";
+describe("LocalSandbox", () => {
+    it("exec(['echo', 'hi']) returns 'hi\\n'", async () => {
+        const sandbox = await LocalSandbox.create();
+        const out = await sandbox.exec(["echo", "hi"]);
+        expect(out).toBe("hi\n");
+        await sandbox.close();
+    });
+    it("python(script) executes via stdin", async () => {
+        const sandbox = await LocalSandbox.create();
+        const out = await sandbox.python("print('hello from python')");
+        expect(out).toBe("hello from python\n");
+        await sandbox.close();
+    });
+    it("sh(command) runs through sh -c", async () => {
+        const sandbox = await LocalSandbox.create();
+        const out = await sandbox.sh("echo $((2 + 2))");
+        expect(out).toBe("4\n");
+        await sandbox.close();
+    });
+    it("propagates env vars to exec", async () => {
+        const sandbox = await LocalSandbox.create({ env: { NK_TEST_VAR: "from-sandbox" } });
+        const out = await sandbox.sh("printf %s \"$NK_TEST_VAR\"");
+        expect(out).toBe("from-sandbox");
+        await sandbox.close();
+    });
+    it("put + get round-trip a file", async () => {
+        const dir = await fs.mkdtemp(path.join(tmpdir(), "sandbox-test-"));
+        const src = path.join(dir, "src.txt");
+        const inSandbox = path.join(dir, "in-sandbox.txt");
+        const out = path.join(dir, "out.txt");
+        await fs.writeFile(src, "hello");
+        const sandbox = await LocalSandbox.create();
+        await sandbox.put(src, inSandbox);
+        expect(await fs.readFile(inSandbox, "utf8")).toBe("hello");
+        const written = await sandbox.get(inSandbox, out);
+        expect(written).toBe(out);
+        expect(await fs.readFile(out, "utf8")).toBe("hello");
+        await sandbox.close();
+        await fs.rm(dir, { recursive: true, force: true });
+    });
+    it("close() is idempotent", async () => {
+        const sandbox = await LocalSandbox.create();
+        await sandbox.close();
+        await expect(sandbox.close()).resolves.toBeUndefined();
+    });
+    it("exec() after close throws", async () => {
+        const sandbox = await LocalSandbox.create();
+        await sandbox.close();
+        await expect(sandbox.exec(["echo", "x"])).rejects.toThrow(/closed/);
+    });
+    it("endpoint() throws (no port mapping)", async () => {
+        const sandbox = await LocalSandbox.create();
+        expect(() => sandbox.endpoint(8080)).toThrow(/unsupported/);
+        await sandbox.close();
+    });
+    it("non-zero exit throws with stderr in message", async () => {
+        const sandbox = await LocalSandbox.create();
+        await expect(sandbox.sh("echo boom 1>&2; exit 7")).rejects.toThrow(/exited 7.*boom/);
+        await sandbox.close();
+    });
+});
+describe("Sandbox.asTools", () => {
+    it("exposes python + sh", async () => {
+        const sandbox = await LocalSandbox.create();
+        const tools = sandbox.asTools();
+        expect(tools.map((t) => t.name)).toEqual(["python", "sh"]);
+        await sandbox.close();
+    });
+    it("python tool dispatches to .python()", async () => {
+        const sandbox = await LocalSandbox.create();
+        const [python] = sandbox.asTools();
+        const out = await python.invoke({ script: "print(40 + 2)" });
+        expect(out).toBe("42\n");
+        await sandbox.close();
+    });
+    it("sh tool dispatches to .sh()", async () => {
+        const sandbox = await LocalSandbox.create();
+        const [, sh] = sandbox.asTools();
+        const out = await sh.invoke({ command: "echo wired" });
+        expect(out).toBe("wired\n");
+        await sandbox.close();
+    });
+    it("tool definitions carry JSON schema", async () => {
+        const sandbox = await LocalSandbox.create();
+        const tools = sandbox.asTools();
+        for (const tool of tools) {
+            expect(tool.parameters).toMatchObject({ type: "object", properties: expect.any(Object) });
+        }
+        await sandbox.close();
+    });
+});
+describe("isSandbox", () => {
+    it("recognizes Sandbox instances", async () => {
+        const sandbox = await LocalSandbox.create();
+        expect(isSandbox(sandbox)).toBe(true);
+        expect(sandbox).toBeInstanceOf(Sandbox);
+        await sandbox.close();
+    });
+    it("rejects plain objects", () => {
+        expect(isSandbox({ exec: () => { } })).toBe(false);
+        expect(isSandbox(null)).toBe(false);
+    });
+});
+describe("DockerSandbox default image", () => {
+    it("DEFAULT_SANDBOX_IMAGE is a pinned patch + slim variant", () => {
+        // Keep this test literal — if the default is bumped, this needs to
+        // move in lockstep. Pinning prevents silent supply-chain drift.
+        expect(DEFAULT_SANDBOX_IMAGE).toBe("python:3.12.7-slim");
+    });
+    it("default image passes argv validator (leading alphanumeric)", () => {
+        // Guards against accidentally regressing the default to something that
+        // begins with `-` and would be mis-parsed as a docker flag.
+        const args = DockerSandbox.buildRunArgs({
+            image: DEFAULT_SANDBOX_IMAGE,
+            cpus: 1,
+            memory: "512m",
+            allowNetwork: false,
+        });
+        expect(args.slice(-3)).toEqual([DEFAULT_SANDBOX_IMAGE, "sleep", "infinity"]);
+    });
+});
+describe("DockerSandbox.buildRunArgs (security defaults)", () => {
+    it("defaults to --network none, --cpus 1, --memory 512m", () => {
+        const args = DockerSandbox.buildRunArgs({
+            image: "python:3.12",
+            cpus: 1,
+            memory: "512m",
+            allowNetwork: false,
+        });
+        expect(args).toEqual(expect.arrayContaining(["--network", "none"]));
+        expect(args).toEqual(expect.arrayContaining(["--cpus", "1"]));
+        expect(args).toEqual(expect.arrayContaining(["--memory", "512m"]));
+        // Image + idle process at the tail.
+        expect(args.slice(-3)).toEqual(["python:3.12", "sleep", "infinity"]);
+        // -d --rm at the head ensures background + auto-remove.
+        expect(args.slice(0, 4)).toEqual(["run", "-d", "--rm", "--cpus"]);
+    });
+    it("allowNetwork: true drops --network none", () => {
+        const args = DockerSandbox.buildRunArgs({
+            image: "python:3.12",
+            cpus: 1,
+            memory: "512m",
+            allowNetwork: true,
+        });
+        expect(args).not.toContain("--network");
+    });
+    it("custom cpus / memory pass through", () => {
+        const args = DockerSandbox.buildRunArgs({
+            image: "node:20",
+            cpus: 2.5,
+            memory: "2g",
+            allowNetwork: false,
+        });
+        expect(args).toEqual(expect.arrayContaining(["--cpus", "2.5"]));
+        expect(args).toEqual(expect.arrayContaining(["--memory", "2g"]));
+    });
+    it("port mapping: null = random, number = fixed", () => {
+        const args = DockerSandbox.buildRunArgs({
+            image: "python:3.12",
+            cpus: 1,
+            memory: "512m",
+            ports: { 8000: null, 9090: 49090 },
+            allowNetwork: false,
+        });
+        expect(args).toEqual(expect.arrayContaining(["-p", "8000"]));
+        expect(args).toEqual(expect.arrayContaining(["-p", "49090:9090"]));
+    });
+    it("mounts default to read-only (writes require explicit readonly: false)", () => {
+        const args = DockerSandbox.buildRunArgs({
+            image: "python:3.12",
+            cpus: 1,
+            memory: "512m",
+            mounts: [
+                { host: "./data", container: "/data" }, // default → ro
+                { host: "./conf", container: "/conf", readonly: true }, // explicit → ro
+                { host: "./work", container: "/work", readonly: false }, // explicit opt-in → rw
+            ],
+            allowNetwork: false,
+        });
+        const dataMount = args.find((a) => a.endsWith(":/data:ro"));
+        const confMount = args.find((a) => a.endsWith(":/conf:ro"));
+        const workMount = args.find((a) => a.endsWith(":/work:rw"));
+        expect(dataMount).toBeDefined();
+        expect(confMount).toBeDefined();
+        expect(workMount).toBeDefined();
+        // Sanity: no `:rw` flag leaked into the default/explicit-ro mounts.
+        expect(args.find((a) => a.endsWith(":/data:rw"))).toBeUndefined();
+        expect(args.find((a) => a.endsWith(":/conf:rw"))).toBeUndefined();
+    });
+    it("env vars serialize to KEY=VALUE", () => {
+        const args = DockerSandbox.buildRunArgs({
+            image: "python:3.12",
+            cpus: 1,
+            memory: "512m",
+            env: { FOO: "bar", NUM: "42" },
+            allowNetwork: false,
+        });
+        expect(args).toEqual(expect.arrayContaining(["-e", "FOO=bar"]));
+        expect(args).toEqual(expect.arrayContaining(["-e", "NUM=42"]));
+    });
+});
+describe("DockerSandbox mount validation (no docker required)", () => {
+    // We point dockerBin at a path that won't exist so create() never reaches
+    // the spawn — mount validation throws before docker is invoked.
+    const NEVER_EXEC = "/nonexistent/docker-bin-does-not-exist";
+    it("rejects mounts outside cwd by default", async () => {
+        await expect(DockerSandbox.create({
+            dockerBin: NEVER_EXEC,
+            mounts: [{ host: "/etc", container: "/etc" }],
+        })).rejects.toThrow(/outside cwd/);
+    });
+    it("allowAnyMount: true skips validation", async () => {
+        // With validation off, we expect to fail on the docker spawn instead.
+        await expect(DockerSandbox.create({
+            dockerBin: NEVER_EXEC,
+            mounts: [{ host: "/etc", container: "/etc" }],
+            allowAnyMount: true,
+        })).rejects.toThrow(/(ENOENT|not.*found|nonexistent)/i);
+    });
+    it("allows mounts under cwd", async () => {
+        await expect(DockerSandbox.create({
+            dockerBin: NEVER_EXEC,
+            mounts: [{ host: ".", container: "/work" }],
+        })).rejects.toThrow(/(ENOENT|not.*found|nonexistent)/i);
+    });
+    it("rejects symlink inside cwd that escapes to outside cwd", async () => {
+        // Place a symlink under cwd that points at /etc. Without realpath resolution
+        // the lexical check would let it through; with realpath, it's caught.
+        const linkName = `.sandbox-escape-${Date.now()}`;
+        const linkPath = path.join(process.cwd(), linkName);
+        await fs.symlink("/etc", linkPath);
+        try {
+            await expect(DockerSandbox.create({
+                dockerBin: NEVER_EXEC,
+                mounts: [{ host: linkName, container: "/etc" }],
+            })).rejects.toThrow(/outside cwd/);
+        }
+        finally {
+            await fs.unlink(linkPath).catch(() => { });
+        }
+    });
+});
+describe("DockerSandbox argv validators", () => {
+    const base = { image: "python:3.12", cpus: 1, memory: "512m", allowNetwork: false };
+    it("rejects image names that would be parsed as flags", () => {
+        expect(() => DockerSandbox.buildRunArgs({ ...base, image: "--privileged" })).toThrow(/invalid image/);
+        expect(() => DockerSandbox.buildRunArgs({ ...base, image: "-rm" })).toThrow(/invalid image/);
+    });
+    it("rejects image names with shell metacharacters", () => {
+        expect(() => DockerSandbox.buildRunArgs({ ...base, image: "python:3.12; rm -rf /" })).toThrow(/invalid image/);
+        expect(() => DockerSandbox.buildRunArgs({ ...base, image: "python:3.12 --cap-add=SYS_ADMIN" })).toThrow(/invalid image/);
+    });
+    it("accepts well-formed image references", () => {
+        expect(() => DockerSandbox.buildRunArgs({ ...base, image: "python:3.12" })).not.toThrow();
+        expect(() => DockerSandbox.buildRunArgs({
+            ...base,
+            image: "registry.example.com:5000/org/repo:v1.2.3@sha256:abc",
+        })).not.toThrow();
+    });
+    it("rejects env keys that are not POSIX identifiers", () => {
+        expect(() => DockerSandbox.buildRunArgs({ ...base, env: { "bad key": "x" } })).toThrow(/invalid env key/);
+        expect(() => DockerSandbox.buildRunArgs({ ...base, env: { "1LEADING": "x" } })).toThrow(/invalid env key/);
+        expect(() => DockerSandbox.buildRunArgs({ ...base, env: { "K=Y": "x" } })).toThrow(/invalid env key/);
+    });
+    it("rejects env values containing newline or NUL", () => {
+        expect(() => DockerSandbox.buildRunArgs({ ...base, env: { FOO: "bar\nBAZ=malicious" } })).toThrow(/newline or NUL/);
+        expect(() => DockerSandbox.buildRunArgs({ ...base, env: { FOO: "bar\x00baz" } })).toThrow(/newline or NUL/);
+    });
+});
+// ── DockerSandbox via fake docker shim ──────────────────────
+// Exercises the create -> exec -> close lifecycle using a tiny shell shim
+// that mimics just enough of the docker CLI to keep DockerSandbox honest.
+describe("DockerSandbox lifecycle (via fake docker shim)", () => {
+    let shimDir = "";
+    let shimBin = "";
+    beforeAll(async () => {
+        shimDir = await fs.mkdtemp(path.join(tmpdir(), "docker-shim-"));
+        shimBin = path.join(shimDir, "docker");
+        // The shim:
+        //   `run ...`     -> echo a fake container id
+        //   `port id N`   -> echo "0.0.0.0:5<N padded>"
+        //   `inspect ...` -> echo "true"
+        //   `exec id sh -c CMD` -> exec sh -c CMD
+        //   `cp SRC DST`  -> cp SRC DST
+        //   `rm -f id`    -> exit 0
+        const script = `#!/bin/sh
+case "$1" in
+  run) echo "fake-container-abc123"; exit 0 ;;
+  port) echo "0.0.0.0:54321"; exit 0 ;;
+  inspect) echo "true"; exit 0 ;;
+  rm) exit 0 ;;
+  exec)
+    # Skip "exec", any flags (-i, -w X, -e K=V), and the container id.
+    shift
+    while [ "$1" = "-i" ] || [ "$1" = "-w" ] || [ "$1" = "-e" ]; do
+      if [ "$1" = "-w" ] || [ "$1" = "-e" ]; then shift; fi
+      shift
+    done
+    shift  # container id
+    exec "$@"
+    ;;
+  cp)
+    shift
+    src=\${1#*:}
+    dst=\${2#*:}
+    cp "$src" "$dst"
+    ;;
+  *) echo "shim: unknown $1" 1>&2; exit 2 ;;
+esac
+`;
+        await fs.writeFile(shimBin, script, { mode: 0o755 });
+    });
+    afterAll(async () => {
+        if (shimDir)
+            await fs.rm(shimDir, { recursive: true, force: true });
+    });
+    it("create + sh + close round-trip", async () => {
+        const sandbox = await DockerSandbox.create({ dockerBin: shimBin });
+        expect(sandbox.containerId).toBe("fake-container-abc123");
+        const out = await sandbox.sh("echo via-fake-docker");
+        expect(out).toBe("via-fake-docker\n");
+        await sandbox.close();
+    });
+    it("close() is idempotent", async () => {
+        const sandbox = await DockerSandbox.create({ dockerBin: shimBin });
+        await sandbox.close();
+        await expect(sandbox.close()).resolves.toBeUndefined();
+    });
+    it("exec after close throws", async () => {
+        const sandbox = await DockerSandbox.create({ dockerBin: shimBin });
+        await sandbox.close();
+        await expect(sandbox.exec(["echo", "x"])).rejects.toThrow(/closed/);
+    });
+    it("endpoint() returns localhost:port for mapped ports", async () => {
+        const sandbox = await DockerSandbox.create({
+            dockerBin: shimBin,
+            ports: { 8000: null },
+        });
+        expect(sandbox.endpoint(8000)).toBe("localhost:54321");
+        await sandbox.close();
+    });
+    it("endpoint() throws for unmapped ports", async () => {
+        const sandbox = await DockerSandbox.create({ dockerBin: shimBin });
+        expect(() => sandbox.endpoint(9999)).toThrow(/not mapped/);
+        await sandbox.close();
+    });
+    it("connect() reattaches to a running container", async () => {
+        const sandbox = await DockerSandbox.connect("fake-existing-id", { dockerBin: shimBin });
+        expect(sandbox.containerId).toBe("fake-existing-id");
+        await sandbox.close();
+    });
+});
+describe("LocalSandbox dev-only warning", () => {
+    // Vitest sets NODE_ENV=test by default, which silences the warning. These
+    // tests flip it to exercise both branches, then restore.
+    const originalNodeEnv = process.env.NODE_ENV;
+    const originalSilence = process.env.NOOKPLOT_LOCAL_SANDBOX_SILENCE;
+    let warnSpy;
+    beforeEach(() => {
+        warnSpy = vi.spyOn(console, "warn").mockImplementation(() => { });
+    });
+    afterEach(async () => {
+        warnSpy.mockRestore();
+        if (originalNodeEnv === undefined)
+            delete process.env.NODE_ENV;
+        else
+            process.env.NODE_ENV = originalNodeEnv;
+        if (originalSilence === undefined)
+            delete process.env.NOOKPLOT_LOCAL_SANDBOX_SILENCE;
+        else
+            process.env.NOOKPLOT_LOCAL_SANDBOX_SILENCE = originalSilence;
+    });
+    it("does NOT warn under NODE_ENV=test", async () => {
+        process.env.NODE_ENV = "test";
+        const sandbox = await LocalSandbox.create();
+        expect(warnSpy).not.toHaveBeenCalled();
+        await sandbox.close();
+    });
+    it("warns when NODE_ENV is not test (e.g. production / undefined)", async () => {
+        process.env.NODE_ENV = "production";
+        delete process.env.NOOKPLOT_LOCAL_SANDBOX_SILENCE;
+        const sandbox = await LocalSandbox.create();
+        expect(warnSpy).toHaveBeenCalledTimes(1);
+        const msg = String(warnSpy.mock.calls[0]?.[0] ?? "");
+        expect(msg).toContain("LocalSandbox");
+        expect(msg).toContain("DockerSandbox");
+        await sandbox.close();
+    });
+    it("silence env var suppresses the warning even outside test", async () => {
+        process.env.NODE_ENV = "production";
+        process.env.NOOKPLOT_LOCAL_SANDBOX_SILENCE = "1";
+        const sandbox = await LocalSandbox.create();
+        expect(warnSpy).not.toHaveBeenCalled();
+        await sandbox.close();
+    });
+});
+//# sourceMappingURL=sandbox.test.js.map