@unerr-ai/unerr 0.1.0 → 0.1.1

package/dist/__tests__/network-boundary.test.js

@@ -0,0 +1,190 @@
+/**
+ * Sprint L5.2 — Network Boundary Contract Tests
+ *
+ * Static contract tests verifying that every cloud-dependent service
+ * is structurally disabled (null / NullProxy) in Local Mode. These
+ * tests catch regressions at the contract level — even if a future
+ * code change introduces a network call, these tests will catch it.
+ *
+ * A security-conscious user reading these tests should be convinced
+ * that their data never leaves their machine in Local Mode.
+ *
+ * CONTRACT: TL-1, TL-3, TL-15
+ */
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { getBlockedCount, resetBlockedCount, seal, unseal, } from "../proxy/network-firewall.js";
+// ── Shared Mock Graph ──────────────────────────────────────────────
+function createMockGraph() {
+    const mockEntity = {
+        key: "fn::test",
+        kind: "function",
+        name: "testFn",
+        file_path: "src/test.ts",
+        start_line: 1,
+        end_line: 10,
+        signature: "(): void",
+        body: "function testFn() {}",
+        fan_in: 2,
+        fan_out: 1,
+        risk_level: "normal",
+    };
+    const mockDb = {
+        run: vi.fn((_query) => ({
+            rows: [],
+        })),
+    };
+    return {
+        db: mockDb,
+        getEntity: vi.fn().mockReturnValue(mockEntity),
+        getCallersOf: vi.fn().mockReturnValue([]),
+        getCalleesOf: vi.fn().mockReturnValue([]),
+        getEntitiesByFile: vi.fn().mockReturnValue([mockEntity]),
+        searchEntities: vi.fn().mockReturnValue([mockEntity]),
+        getImports: vi.fn().mockReturnValue([]),
+        hasRules: vi.fn().mockReturnValue(true),
+        getRules: vi.fn().mockReturnValue([]),
+        getPatterns: vi
+            .fn()
+            .mockReturnValue([
+            { name: "test-pattern", type: "naming", adherence: 0.9 },
+        ]),
+        hasJustifications: vi.fn().mockReturnValue(true),
+        getBusinessContext: vi.fn().mockReturnValue(null),
+        getConventions: vi.fn().mockReturnValue([]),
+        getCrossBoundaryLinks: vi.fn().mockReturnValue([]),
+        getCriticalNodes: vi.fn().mockReturnValue([]),
+        getDriftEntitiesForFile: vi.fn().mockReturnValue([]),
+        upsertDriftEntity: vi.fn(),
+        removeDriftEntity: vi.fn(),
+        clearDriftOverlay: vi.fn(),
+        getDriftSummary: vi
+            .fn()
+            .mockReturnValue({ added: 0, modified: 0, deleted: 0, total: 0 }),
+        healthCheck: vi.fn().mockReturnValue({ status: "ok", latencyMs: 1 }),
+        isLoaded: vi.fn().mockReturnValue(true),
+        loadSnapshot: vi.fn(),
+        loadRules: vi.fn(),
+        loadPatterns: vi.fn(),
+        loadJustifications: vi.fn(),
+        applyDelta: vi.fn().mockReturnValue({
+            applied: 0,
+            deleted: 0,
+            edges: 0,
+            justifications: 0,
+            overlayExpired: 0,
+        }),
+        getLocalProjectStats: vi.fn().mockReturnValue({
+            fileCount: 100,
+            entityCount: 500,
+            edgeCount: 1200,
+            communityCount: 10,
+            ruleCount: 5,
+        }),
+        getDeepDiveProjectState: vi.fn().mockReturnValue("none"),
+        persistCorrections: vi.fn(),
+        getRuleHealthSummary: vi.fn().mockReturnValue(null),
+        getRuleExceptions: vi.fn().mockReturnValue([]),
+    };
+}
+// ── Test Suite ─────────────────────────────────────────────────────
+describe("Network Boundary Contracts (L5.2)", () => {
+    afterEach(() => {
+        unseal();
+        resetBlockedCount();
+    });
+    it("local-routed tools resolve without network calls", async () => {
+        seal();
+        const { QueryRouter } = await import("../intelligence/query-router.js");
+        const graph = createMockGraph();
+        const router = new QueryRouter(graph);
+        router.setMode("local", "Local Mode");
+        await router.execute("get_function", { key: "fn::test" });
+        await router.execute("search_code", { query: "test" });
+        await router.execute("get_callers", { key: "fn::test" });
+        await router.execute("get_conventions", {});
+        expect(getBlockedCount()).toBe(0);
+    });
+    it("Local Mode QueryRouter handles errors locally (TL-15)", async () => {
+        seal();
+        const { QueryRouter } = await import("../intelligence/query-router.js");
+        const graph = createMockGraph();
+        graph.getEntity = vi.fn().mockImplementation(() => {
+            throw new Error("Simulated local failure");
+        });
+        const router = new QueryRouter(graph);
+        router.setMode("local", "Local Mode");
+        const result = await router.execute("get_function", { key: "nonexistent" });
+        expect(result._meta.source).toBe("local");
+        expect(result.content).toHaveProperty("error");
+        expect(getBlockedCount()).toBe(0);
+    });
+    it("NetworkFirewall rejects app.unerr.dev when sealed", async () => {
+        seal();
+        const result = await globalThis
+            .fetch("https://app.unerr.dev/api/repos/test/profile")
+            .catch((e) => e);
+        expect(result).toBeInstanceOf(Error);
+        expect(result.message).toContain("[NetworkFirewall]");
+        expect(getBlockedCount()).toBe(1);
+    });
+    it("NetworkFirewall rejects api.anthropic.com when sealed (no allowlist)", async () => {
+        seal();
+        const result = await globalThis
+            .fetch("https://api.anthropic.com/v1/messages")
+            .catch((e) => e);
+        expect(result).toBeInstanceOf(Error);
+        expect(result.message).toContain("[NetworkFirewall]");
+        expect(getBlockedCount()).toBe(1);
+    });
+    it("NetworkFirewall allows localhost (Ollama, LM Studio) when sealed", async () => {
+        seal();
+        const localhostUrls = [
+            "http://localhost:11434/api/tags",
+            "http://127.0.0.1:1234/v1/models",
+            "http://localhost:8080/health",
+        ];
+        for (const url of localhostUrls) {
+            const result = await globalThis.fetch(url).catch((e) => e);
+            if (result instanceof Error) {
+                expect(result.message).not.toContain("[NetworkFirewall]");
+            }
+        }
+        expect(getBlockedCount()).toBe(0);
+    });
+    it("local-routed tools resolve from CozoDB with zero network calls", async () => {
+        seal();
+        const { QueryRouter } = await import("../intelligence/query-router.js");
+        const graph = createMockGraph();
+        const router = new QueryRouter(graph);
+        router.setMode("local", "Local Mode");
+        const localOnlyTools = [
+            { name: "get_function", args: { key: "fn::test" } },
+            { name: "get_class", args: { key: "fn::test" } },
+            { name: "get_file", args: { key: "src/test.ts" } },
+            { name: "get_callers", args: { key: "fn::test" } },
+            { name: "get_callees", args: { key: "fn::test" } },
+            { name: "get_imports", args: { file_path: "src/test.ts" } },
+            { name: "search_code", args: { query: "test" } },
+            { name: "get_rules", args: {} },
+            { name: "get_business_context", args: { key: "fn::test" } },
+            { name: "get_conventions", args: {} },
+            { name: "get_cross_boundary_links", args: {} },
+            { name: "get_critical_nodes", args: {} },
+        ];
+        for (const tool of localOnlyTools) {
+            const result = await router.execute(tool.name, tool.args);
+            expect(result._meta.source).toBe("local");
+        }
+        expect(getBlockedCount()).toBe(0);
+    });
+    it("get_project_stats returns from local CozoDB (not cloud API)", async () => {
+        seal();
+        const { QueryRouter } = await import("../intelligence/query-router.js");
+        const graph = createMockGraph();
+        const router = new QueryRouter(graph);
+        router.setMode("local", "Local Mode");
+        const result = await router.execute("get_project_stats", {});
+        expect(result._meta.source).toBe("local");
+        expect(getBlockedCount()).toBe(0);
+    });
+});

package/dist/__tests__/network-firewall.test.js

@@ -0,0 +1,112 @@
+/**
+ * Tests for Sprint L8.4 — Network Firewall allowlist & anthropic-direct exception.
+ */
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { addAllowedHost, addAllowedUrl, getBlockedCount, isSealed, resetBlockedCount, seal, unseal, } from "../proxy/network-firewall.js";
+describe("NetworkFirewall (L8.4)", () => {
+    beforeEach(() => {
+        unseal();
+        resetBlockedCount();
+    });
+    afterEach(() => {
+        unseal();
+        resetBlockedCount();
+    });
+    it("addAllowedHost before seal allows that host", async () => {
+        addAllowedHost("api.anthropic.com");
+        seal();
+        expect(isSealed()).toBe(true);
+        // Should NOT block api.anthropic.com
+        const resp = await globalThis
+            .fetch("https://api.anthropic.com/v1/messages")
+            .catch((e) => e);
+        // If it's a network error (server not reachable), that's fine — it wasn't BLOCKED
+        if (resp instanceof Error) {
+            expect(resp.message).not.toContain("[NetworkFirewall]");
+        }
+        expect(getBlockedCount()).toBe(0);
+    });
+    it("addAllowedUrl extracts hostname and allows it", async () => {
+        addAllowedUrl("http://localhost:11434");
+        seal();
+        // localhost is always allowed, but this tests the URL parsing path
+        expect(isSealed()).toBe(true);
+        expect(getBlockedCount()).toBe(0);
+    });
+    it("blocks non-allowlisted hosts after seal", async () => {
+        seal();
+        const result = await globalThis
+            .fetch("https://app.unerr.dev/api/health")
+            .catch((e) => e);
+        expect(result).toBeInstanceOf(Error);
+        expect(result.message).toContain("[NetworkFirewall]");
+        expect(result.message).toContain("app.unerr.dev");
+        expect(getBlockedCount()).toBe(1);
+    });
+    it("app.unerr.dev is NEVER in allowlist", async () => {
+        addAllowedHost("api.anthropic.com");
+        seal();
+        const result = await globalThis
+            .fetch("https://app.unerr.dev/api/health")
+            .catch((e) => e);
+        expect(result).toBeInstanceOf(Error);
+        expect(result.message).toContain("[NetworkFirewall]");
+        expect(getBlockedCount()).toBe(1);
+    });
+    it("addAllowedHost throws after seal (immutability)", () => {
+        seal();
+        expect(() => addAllowedHost("evil.com")).toThrow("firewall is already sealed");
+    });
+    it("addAllowedUrl throws after seal (immutability)", () => {
+        seal();
+        expect(() => addAllowedUrl("https://evil.com")).toThrow("firewall is already sealed");
+    });
+    it("localhost always allowed without explicit allowlist", async () => {
+        seal();
+        const result = await globalThis
+            .fetch("http://localhost:11434/api/tags")
+            .catch((e) => e);
+        // Should not be a firewall error (may be ECONNREFUSED if Ollama isn't running)
+        if (result instanceof Error) {
+            expect(result.message).not.toContain("[NetworkFirewall]");
+        }
+        expect(getBlockedCount()).toBe(0);
+    });
+    it("seal() with allowedBaseUrls still works (backwards compat)", async () => {
+        seal(["http://localhost:1234"]);
+        expect(isSealed()).toBe(true);
+        expect(getBlockedCount()).toBe(0);
+    });
+    it("anthropic-direct: api.anthropic.com allowed, other hosts blocked", async () => {
+        addAllowedHost("api.anthropic.com");
+        seal();
+        // Anthropic allowed
+        const anthropicResult = await globalThis
+            .fetch("https://api.anthropic.com/v1/messages")
+            .catch((e) => e);
+        if (anthropicResult instanceof Error) {
+            expect(anthropicResult.message).not.toContain("[NetworkFirewall]");
+        }
+        // Random host blocked
+        const otherResult = await globalThis
+            .fetch("https://evil.example.com/steal")
+            .catch((e) => e);
+        expect(otherResult).toBeInstanceOf(Error);
+        expect(otherResult.message).toContain("[NetworkFirewall]");
+        expect(getBlockedCount()).toBe(1);
+    });
+    it("unseal clears allowlist and restores fetch", () => {
+        addAllowedHost("api.anthropic.com");
+        seal();
+        expect(isSealed()).toBe(true);
+        unseal();
+        expect(isSealed()).toBe(false);
+        // After unseal + re-seal, anthropic should be blocked (allowlist cleared)
+        seal();
+        // No addAllowedHost this time — anthropic should be blocked
+        void globalThis
+            .fetch("https://api.anthropic.com/v1/messages")
+            .catch(() => { });
+        expect(getBlockedCount()).toBe(1);
+    });
+});

package/dist/__tests__/nudge-invariants.test.js

@@ -0,0 +1,160 @@
+/**
+ * Nudge clarity invariants — block any regression to the abstract-placeholder
+ * or hedge-verb patterns documented in CLAUDE.md "Writing nudges and hints".
+ *
+ * Anything the agent reads as advisory (Consider/Verify/Review/Check) or
+ * abstract (`:N`, `<name>`) creates retry loops or silent drops. These tests
+ * fail loud if either pattern returns.
+ */
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+import { SIGNAL_PREFIX_LEGEND } from "../proxy/response-envelope.js";
+const HEDGE_VERBS = [
+    /\bConsider\b/,
+    /\bVerify\b/,
+    /\bReview\b/,
+    /\bCheck\b/, // followed by space (avoid "Checked", "checkbox" in identifiers)
+    /\bmay want to\b/i,
+];
+const ROOT = join(__dirname, "..");
+function readSource(rel) {
+    return readFileSync(join(ROOT, rel), "utf-8");
+}
+/**
+ * Extract every `action: "..."` string literal from a source file. Skips
+ * action: undefined and action: variable-reference forms.
+ */
+function extractActionLiterals(src) {
+    const out = [];
+    // Match: action: "..."  or  action: `...`
+    const re = /action:\s*(?:"([^"\\]*(?:\\.[^"\\]*)*)"|`([^`\\]*(?:\\.[^`\\]*)*)`)/g;
+    let m;
+    m = re.exec(src);
+    while (m !== null) {
+        const literal = m[1] ?? m[2];
+        if (literal)
+            out.push(literal);
+        m = re.exec(src);
+    }
+    return out;
+}
+describe("nudge invariants — SIGNAL_PREFIX_LEGEND", () => {
+    it("contains no literal `:N` cursor placeholder", () => {
+        // The page hint format example must use concrete-value language, not :N.
+        // Concrete shape uses <nextValue>, <remaining>, etc. as descriptive
+        // placeholders inside angle brackets — those are documentation form,
+        // not emission form.
+        expect(SIGNAL_PREFIX_LEGEND).not.toMatch(/:N\b/);
+    });
+    it("contains no bare `<name>` parameter placeholder", () => {
+        // Angle-bracket descriptors are allowed in format documentation
+        // (<tool>, <cursorArg>, <nextValue>) but the literal "<name>" was the
+        // pre-rewrite stand-in for an entity that never got substituted.
+        expect(SIGNAL_PREFIX_LEGEND).not.toContain("<name>");
+    });
+    it("uses imperative verbs, not hedge verbs", () => {
+        for (const re of HEDGE_VERBS) {
+            expect(SIGNAL_PREFIX_LEGEND).not.toMatch(re);
+        }
+    });
+});
+describe("nudge invariants — signal-scorer action strings", () => {
+    const src = readSource("intelligence/signal-scorer.ts");
+    const actions = extractActionLiterals(src);
+    it("scorer file has multiple action: literals (sanity check)", () => {
+        expect(actions.length).toBeGreaterThan(5);
+    });
+    it("no action string uses hedge verbs", () => {
+        for (const action of actions) {
+            for (const re of HEDGE_VERBS) {
+                if (re.test(action)) {
+                    throw new Error(`signal-scorer action uses hedge verb (${re}): "${action}"`);
+                }
+            }
+        }
+    });
+    it("no action string uses the deictic phrase 'this entity / pattern / file'", () => {
+        for (const action of actions) {
+            // The audit explicitly identified 'this entity', 'this pattern',
+            // 'this file' as the recurring deictic anti-pattern.
+            expect(action).not.toMatch(/\bthis (entity|pattern|file)\b/);
+        }
+    });
+});
+describe("nudge invariants — isError reaches the agent's MCP context", () => {
+    const src = readSource("proxy/proxy.ts");
+    const lines = src.split("\n");
+    /**
+     * For every line that writes a `[unerr]` error to stderr, the surrounding
+     * window (next 12 lines) must include `isError: true`. This couples the
+     * human-debug channel (stderr → .unerr/logs/) with the agent-context
+     * channel (MCP CallToolResult.isError). The user's original concern:
+     * "make sure isError writes to err stream AND err stream gets into the
+     *  coding agent context" — codified.
+     */
+    it("every stderr error log in proxy.ts pairs with an isError:true on the wire", () => {
+        const orphans = [];
+        for (let i = 0; i < lines.length; i++) {
+            const raw = lines[i];
+            if (!raw)
+                continue;
+            // Match the stderr error pattern we standardized on.
+            if (!/process\.stderr\.write\([\s\S]*\[unerr\][^)]*(failed|threw|disabled|validation)/i.test(raw))
+                continue;
+            // Look ahead up to 12 lines for `isError: true`.
+            const window = lines.slice(i, Math.min(lines.length, i + 13)).join("\n");
+            if (!/isError:\s*true/.test(window)) {
+                orphans.push({ line: i + 1, text: raw.trim().slice(0, 100) });
+            }
+        }
+        if (orphans.length > 0) {
+            const msg = orphans
+                .map((o) => `  proxy.ts:${o.line} → ${o.text}`)
+                .join("\n");
+            throw new Error(`${orphans.length} stderr error log(s) in proxy.ts do not set isError:true within 12 lines. Pair every human-debug log with a wire isError so the agent sees the failure:\n${msg}`);
+        }
+    });
+    it("contains the expected error-routing sites (sanity check)", () => {
+        // Documents the four MCP error paths that must surface isError to MCP
+        // clients. If anyone removes a path, this fires.
+        expect(src).toMatch(/record_fact failed/);
+        expect(src).toMatch(/recall_facts failed/);
+        expect(src).toMatch(/tools\/call validation failed for/);
+        expect(src).toMatch(/router\.execute\(\$\{name\}\) threw/);
+    });
+});
+describe("nudge invariants — wire-cap nudges", () => {
+    const src = readSource("proxy/wire-cap.ts");
+    it("the buildPageHint template uses a numeric cursor (no `:N` in code)", () => {
+        // The page-hint template now interpolates `${nextCursor}`. If anyone
+        // ever reverts to a literal `:N`, this catches it.
+        expect(src).not.toMatch(/\$\{cursorArg\}:N/);
+        expect(src).not.toMatch(/`ur\|pg \$\{toolName\}[^`]*:N[`\s—]/);
+    });
+    it("PER_TOOL_CAPS.filterHint values are concrete (no `<name>` / `:T` / `:V` placeholders)", () => {
+        // Page-hint format: `ur|pg <tool> +N — <cursor>:<n>/<filterHint>`. The
+        // filterHint is appended verbatim. Literal placeholders (`<name>`, `:T`,
+        // `:V`) train the agent to paste the placeholder instead of substituting
+        // a real value — the exact anti-pattern this audit eliminated. Concrete
+        // values or pipe-separated enums only.
+        const capMatches = src.matchAll(/filterHint:\s*"([^"]+)"/g);
+        const offenders = [];
+        for (const match of capMatches) {
+            const hint = match[1] ?? "";
+            // Forbid angle-bracket placeholders (`<name>`, `<entity>`, etc).
+            if (/<[^>]+>/.test(hint)) {
+                offenders.push(`${hint} (contains <…> placeholder)`);
+                continue;
+            }
+            // Forbid single-letter trailing placeholders (`fact_type:T`, `:V`).
+            // A single-uppercase-letter value never reads as concrete.
+            if (/:[A-Z](\s|$|\/|\|)/.test(hint)) {
+                offenders.push(`${hint} (single-letter placeholder)`);
+            }
+        }
+        if (offenders.length > 0) {
+            throw new Error(`PER_TOOL_CAPS filterHint values must be concrete:\n${offenders.map((o) => `  - ${o}`).join("\n")}`);
+        }
+    });
+});