@rubytech/create-maxy-code 0.1.60 → 0.1.62

package/payload/premium-plugins/real-agent/plugins/epc/mcp/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "@maxy/epc",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "main": "dist/index.js",
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "neo4j-driver": "^5.28.1"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.0",
+    "@types/node": "^22.0.0",
+    "vitest": "^4.1.2"
+  }
+}

package/payload/premium-plugins/real-agent/plugins/epc/mcp/src/__tests__/epc-api.test.ts

@@ -0,0 +1,251 @@
+/**
+ * epc-api.ts behaviour with mocked fetch + mocked neo4j store. Covers:
+ *  - missing-key path throws KeyNotRegisteredError
+ *  - 4xx upstream (non-404) maps to EpcError with status preserved
+ *  - 5xx upstream maps to EpcError with status preserved
+ *  - 404 maps to { status: 404, rows: [] } (caller turns into ok+empty)
+ *  - non-JSON body maps to BadResponseError
+ *  - malformed JSON (missing rows) maps to BadResponseError
+ *  - happy path returns parsed rows
+ *  - groupAndPickMostRecent picks the latest lodgement-date per UPRN
+ */
+
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+vi.mock("../lib/neo4j.js", () => {
+  let stored: { encryptedKey: string } | null = null;
+  return {
+    getSession: () => ({
+      run: vi.fn(async (cypher: string, params: Record<string, unknown>) => {
+        if (/MATCH \(k:EpcApiKey/.test(cypher) && /RETURN/.test(cypher)) {
+          return {
+            records: stored
+              ? [
+                  {
+                    get: (k: string) => {
+                      if (k === "encryptedKey") return stored!.encryptedKey;
+                      if (k === "createdAt") return "2026-01-01T00:00:00Z";
+                      if (k === "updatedAt") return "2026-01-01T00:00:00Z";
+                      return null;
+                    },
+                  },
+                ]
+              : [],
+          };
+        }
+        if (/MERGE \(k:EpcApiKey/.test(cypher)) {
+          stored = { encryptedKey: String(params.encryptedKey) };
+          return { records: [] };
+        }
+        if (/DELETE k/.test(cypher)) {
+          const count = stored ? 1 : 0;
+          stored = null;
+          return {
+            records: [{ get: (k: string) => (k === "deleted" ? { toNumber: () => count } : null) }],
+          };
+        }
+        return { records: [] };
+      }),
+      close: vi.fn(async () => {}),
+    }),
+    closeDriver: vi.fn(async () => {}),
+  };
+});
+
+vi.mock("../lib/crypto.js", () => ({
+  encrypt: (s: string) => `enc:${s}`,
+  decrypt: (s: string) => s.replace(/^enc:/, ""),
+}));
+
+import {
+  epcSearch,
+  groupAndPickMostRecent,
+  KeyNotRegisteredError,
+  EpcError,
+  BadResponseError,
+  M2_TO_SQFT,
+} from "../lib/epc-api.js";
+import { keyRegister } from "../tools/key-register.js";
+
+const originalFetch = globalThis.fetch;
+
+function mockFetch(impl: (url: string, init?: RequestInit) => Response | Promise<Response>) {
+  globalThis.fetch = vi.fn(async (url: string | URL | Request, init?: RequestInit) =>
+    impl(String(url), init),
+  ) as unknown as typeof fetch;
+}
+
+afterEach(() => {
+  globalThis.fetch = originalFetch;
+  vi.restoreAllMocks();
+});
+
+async function registerTestKey(accountId = "acc-1") {
+  // Register-time probe gets 200 -> validated.
+  mockFetch(() => new Response(JSON.stringify({ rows: [] }), { status: 200 }));
+  await keyRegister({ apiKey: "tester@example.com:abc12345", accountId });
+}
+
+describe("epcSearch", () => {
+  it("throws KeyNotRegisteredError when no key is stored", async () => {
+    await expect(
+      epcSearch({
+        toolName: "epc-lookup-by-address",
+        accountId: "ghost-account",
+        identifier: "1 The Street",
+        params: { address: "1 The Street" },
+      }),
+    ).rejects.toBeInstanceOf(KeyNotRegisteredError);
+  });
+
+  it("returns parsed rows on success", async () => {
+    await registerTestKey();
+    mockFetch(
+      () =>
+        new Response(
+          JSON.stringify({
+            rows: [{ "lmk-key": "abc", uprn: "1", "total-floor-area": "70.0" }],
+          }),
+          { status: 200 },
+        ),
+    );
+    const { status, rows } = await epcSearch({
+      toolName: "epc-lookup-by-address",
+      accountId: "acc-1",
+      identifier: "1 The Street",
+      params: { address: "1 The Street", postcode: "CM23 5SR" },
+    });
+    expect(status).toBe(200);
+    expect(rows).toHaveLength(1);
+    expect(rows[0].uprn).toBe("1");
+  });
+
+  it("returns empty rows on HTTP 404 (no EPC on file)", async () => {
+    await registerTestKey();
+    mockFetch(() => new Response("not found", { status: 404 }));
+    const { status, rows } = await epcSearch({
+      toolName: "epc-lookup-by-address",
+      accountId: "acc-1",
+      identifier: "999 Nowhere",
+      params: { address: "999 Nowhere" },
+    });
+    expect(status).toBe(404);
+    expect(rows).toEqual([]);
+  });
+
+  it("maps HTTP 4xx (non-404) to EpcError preserving status", async () => {
+    await registerTestKey();
+    mockFetch(() => new Response("rate limited", { status: 429 }));
+    try {
+      await epcSearch({
+        toolName: "epc-lookup-by-address",
+        accountId: "acc-1",
+        identifier: "1 The Street",
+        params: { address: "1 The Street" },
+      });
+      throw new Error("expected EpcError");
+    } catch (err) {
+      expect(err).toBeInstanceOf(EpcError);
+      expect((err as EpcError).status).toBe(429);
+    }
+  });
+
+  it("maps HTTP 5xx to EpcError preserving status", async () => {
+    await registerTestKey();
+    mockFetch(() => new Response("upstream down", { status: 500 }));
+    try {
+      await epcSearch({
+        toolName: "epc-lookup-by-address",
+        accountId: "acc-1",
+        identifier: "1 The Street",
+        params: { address: "1 The Street" },
+      });
+      throw new Error("expected EpcError");
+    } catch (err) {
+      expect(err).toBeInstanceOf(EpcError);
+      expect((err as EpcError).status).toBe(500);
+    }
+  });
+
+  it("maps non-JSON body to BadResponseError", async () => {
+    await registerTestKey();
+    mockFetch(() => new Response("<html>maintenance</html>", { status: 200 }));
+    await expect(
+      epcSearch({
+        toolName: "epc-lookup-by-address",
+        accountId: "acc-1",
+        identifier: "1 The Street",
+        params: { address: "1 The Street" },
+      }),
+    ).rejects.toBeInstanceOf(BadResponseError);
+  });
+
+  it("maps JSON without rows array to BadResponseError", async () => {
+    await registerTestKey();
+    mockFetch(() => new Response(JSON.stringify({ error: "schema drift" }), { status: 200 }));
+    await expect(
+      epcSearch({
+        toolName: "epc-lookup-by-address",
+        accountId: "acc-1",
+        identifier: "1 The Street",
+        params: { address: "1 The Street" },
+      }),
+    ).rejects.toBeInstanceOf(BadResponseError);
+  });
+
+  it("sends Authorization: Basic header", async () => {
+    await registerTestKey();
+    let seenAuth: string | undefined;
+    mockFetch((_url, init) => {
+      const headers = init?.headers as Record<string, string> | undefined;
+      seenAuth = headers?.Authorization;
+      return new Response(JSON.stringify({ rows: [] }), { status: 200 });
+    });
+    await epcSearch({
+      toolName: "epc-lookup-by-address",
+      accountId: "acc-1",
+      identifier: "1 The Street",
+      params: { address: "1 The Street" },
+    });
+    expect(seenAuth).toMatch(/^Basic /);
+    const credential = Buffer.from(seenAuth!.replace(/^Basic /, ""), "base64").toString("utf-8");
+    expect(credential).toBe("tester@example.com:abc12345");
+  });
+});
+
+describe("groupAndPickMostRecent", () => {
+  it("picks the latest lodgement-date per UPRN and converts m² to sqft", () => {
+    const rows = [
+      { uprn: "100", "lodgement-date": "2018-04-01", "total-floor-area": "70.0", address1: "1 The Street", postcode: "CM23 5SR", "current-energy-rating": "D", "potential-energy-rating": "C" },
+      { uprn: "100", "lodgement-date": "2024-09-15", "total-floor-area": "72.5", address1: "1 The Street", postcode: "CM23 5SR", "current-energy-rating": "C", "potential-energy-rating": "B" },
+      { uprn: "200", "lodgement-date": "2021-01-01", "total-floor-area": "55.0", address1: "2 The Street", postcode: "CM23 5SR", "current-energy-rating": "E", "potential-energy-rating": "C" },
+    ];
+    const matches = groupAndPickMostRecent(rows);
+    expect(matches).toHaveLength(2);
+    const m100 = matches.find((m) => m.uprn === "100")!;
+    expect(m100.lodgement_date).toBe("2024-09-15");
+    expect(m100.total_floor_area_m2).toBe(72.5);
+    expect(m100.total_floor_area_sqft).toBe(Number((72.5 * M2_TO_SQFT).toFixed(2)));
+    expect(m100.current_energy_rating).toBe("C");
+    const m200 = matches.find((m) => m.uprn === "200")!;
+    expect(m200.total_floor_area_m2).toBe(55.0);
+  });
+
+  it("falls back to address+postcode when UPRN is absent", () => {
+    const rows = [
+      { "lodgement-date": "2020-01-01", "total-floor-area": "60", address1: "5 The Lane", postcode: "CM23 1AA" },
+      { "lodgement-date": "2022-06-01", "total-floor-area": "61", address1: "5 The Lane", postcode: "CM23 1AA" },
+    ];
+    const matches = groupAndPickMostRecent(rows);
+    expect(matches).toHaveLength(1);
+    expect(matches[0].lodgement_date).toBe("2022-06-01");
+    expect(matches[0].uprn).toBeNull();
+  });
+
+  it("tolerates missing total-floor-area", () => {
+    const rows = [{ uprn: "300", "lodgement-date": "2023-01-01" }];
+    const matches = groupAndPickMostRecent(rows);
+    expect(matches[0].total_floor_area_m2).toBeNull();
+    expect(matches[0].total_floor_area_sqft).toBeNull();
+  });
+});

package/payload/premium-plugins/real-agent/plugins/epc/mcp/src/__tests__/key-roundtrip.test.ts

@@ -0,0 +1,113 @@
+/**
+ * EPC key register / list / deregister round-trip against a mocked Neo4j
+ * session, mocked crypto, and mocked fetch for the register-time probe
+ * against the EPC register.
+ */
+
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+vi.mock("../lib/neo4j.js", () => {
+  let stored: { encryptedKey: string; createdAt: string; updatedAt: string } | null = null;
+  return {
+    getSession: () => ({
+      run: vi.fn(async (cypher: string, params: Record<string, unknown>) => {
+        if (/CREATE INDEX/.test(cypher)) return { records: [] };
+        if (/MERGE \(k:EpcApiKey/.test(cypher)) {
+          const now = String(params.now ?? new Date().toISOString());
+          stored = {
+            encryptedKey: String(params.encryptedKey),
+            createdAt: stored?.createdAt ?? now,
+            updatedAt: now,
+          };
+          return { records: [] };
+        }
+        if (/MATCH \(k:EpcApiKey/.test(cypher) && /DELETE/.test(cypher)) {
+          const count = stored ? 1 : 0;
+          stored = null;
+          return {
+            records: [{ get: (k: string) => (k === "deleted" ? { toNumber: () => count } : null) }],
+          };
+        }
+        if (/MATCH \(k:EpcApiKey/.test(cypher) && /RETURN/.test(cypher)) {
+          return {
+            records: stored
+              ? [
+                  {
+                    get: (k: string) => {
+                      if (k === "encryptedKey") return stored!.encryptedKey;
+                      if (k === "createdAt") return stored!.createdAt;
+                      if (k === "updatedAt") return stored!.updatedAt;
+                      return null;
+                    },
+                  },
+                ]
+              : [],
+          };
+        }
+        return { records: [] };
+      }),
+      close: vi.fn(async () => {}),
+    }),
+    closeDriver: vi.fn(async () => {}),
+  };
+});
+
+vi.mock("../lib/crypto.js", () => ({
+  encrypt: (s: string) => `enc:${s}`,
+  decrypt: (s: string) => s.replace(/^enc:/, ""),
+}));
+
+import { keyRegister } from "../tools/key-register.js";
+import { keyDeregister } from "../tools/key-deregister.js";
+import { keyList } from "../tools/key-list.js";
+
+const originalFetch = globalThis.fetch;
+
+afterEach(() => {
+  globalThis.fetch = originalFetch;
+  vi.restoreAllMocks();
+});
+
+describe("epc key round-trip", () => {
+  it("rejects an unregistered account on list", async () => {
+    const out = await keyList({ accountId: "acc-empty" });
+    expect(out).toMatch(/No EPC API key registered/);
+  });
+
+  it("rejects deregister when no key is stored", async () => {
+    await expect(keyDeregister({ accountId: "acc-empty-2" })).rejects.toThrow(
+      /No EPC API key/,
+    );
+  });
+
+  it("rejects credentials without the required email:api-key shape", async () => {
+    await expect(
+      keyRegister({ apiKey: "just-the-key", accountId: "acc-bad" }),
+    ).rejects.toThrow(/email:api-key/);
+  });
+
+  it("rejects registration when EPC returns 401", async () => {
+    globalThis.fetch = vi.fn(
+      async () => new Response("unauthorized", { status: 401 }),
+    ) as unknown as typeof fetch;
+    await expect(
+      keyRegister({ apiKey: "tester@example.com:bad-key", accountId: "acc-x" }),
+    ).rejects.toThrow(/rejected the credential/);
+  });
+
+  it("registers, lists, then deregisters successfully and never reveals the credential", async () => {
+    globalThis.fetch = vi.fn(
+      async () => new Response(JSON.stringify({ rows: [] }), { status: 200 }),
+    ) as unknown as typeof fetch;
+    await keyRegister({ apiKey: "tester@example.com:good-key-12345", accountId: "acc-r" });
+
+    const listed = await keyList({ accountId: "acc-r" });
+    expect(listed).toMatch(/EPC API key registered/);
+    expect(listed).not.toContain("good-key-12345");
+    expect(listed).not.toContain("tester@example.com");
+
+    await keyDeregister({ accountId: "acc-r" });
+    const afterDelete = await keyList({ accountId: "acc-r" });
+    expect(afterDelete).toMatch(/No EPC API key/);
+  });
+});

package/payload/premium-plugins/real-agent/plugins/epc/mcp/src/__tests__/lookup.test.ts

@@ -0,0 +1,181 @@
+/**
+ * Per-tool coverage for the two lookup adapters. Asserts:
+ *   - happy path: URL carries the expected query params, response surfaces
+ *     a single grouped match per UPRN with m² + sqft
+ *   - 4xx upstream (non-404) → EpcError with status preserved
+ *   - 404 upstream → ok response with empty matches
+ *   - non-JSON body → BadResponseError
+ *   - missing-key → KeyNotRegisteredError
+ */
+
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+vi.mock("../lib/neo4j.js", () => {
+  const stored = new Map<string, string>();
+  return {
+    getSession: () => ({
+      run: vi.fn(async (cypher: string, params: Record<string, unknown>) => {
+        const accountId = String(params.accountId ?? "");
+        if (/MATCH \(k:EpcApiKey/.test(cypher) && /RETURN/.test(cypher)) {
+          const encryptedKey = stored.get(accountId);
+          return {
+            records: encryptedKey
+              ? [
+                  {
+                    get: (k: string) => {
+                      if (k === "encryptedKey") return encryptedKey;
+                      if (k === "createdAt") return "2026-01-01T00:00:00Z";
+                      if (k === "updatedAt") return "2026-01-01T00:00:00Z";
+                      return null;
+                    },
+                  },
+                ]
+              : [],
+          };
+        }
+        if (/MERGE \(k:EpcApiKey/.test(cypher)) {
+          stored.set(accountId, String(params.encryptedKey));
+          return { records: [] };
+        }
+        if (/DELETE k/.test(cypher)) {
+          const had = stored.delete(accountId);
+          return {
+            records: [
+              {
+                get: (k: string) =>
+                  k === "deleted" ? { toNumber: () => (had ? 1 : 0) } : null,
+              },
+            ],
+          };
+        }
+        return { records: [] };
+      }),
+      close: vi.fn(async () => {}),
+    }),
+    closeDriver: vi.fn(async () => {}),
+  };
+});
+
+vi.mock("../lib/crypto.js", () => ({
+  encrypt: (s: string) => `enc:${s}`,
+  decrypt: (s: string) => s.replace(/^enc:/, ""),
+}));
+
+import { epcLookupByAddress, epcLookupByUprn } from "../tools/lookup.js";
+import { KeyNotRegisteredError, EpcError, BadResponseError } from "../lib/epc-api.js";
+import { keyRegister } from "../tools/key-register.js";
+
+const originalFetch = globalThis.fetch;
+
+function mockFetch(impl: (url: string) => Response | Promise<Response>) {
+  globalThis.fetch = vi.fn(async (url: string | URL | Request) => impl(String(url))) as unknown as typeof fetch;
+}
+
+afterEach(() => {
+  globalThis.fetch = originalFetch;
+  vi.restoreAllMocks();
+});
+
+async function registerKey(accountId: string) {
+  mockFetch(() => new Response(JSON.stringify({ rows: [] }), { status: 200 }));
+  await keyRegister({ apiKey: "tester@example.com:abc12345", accountId });
+}
+
+interface Case {
+  label: string;
+  call: (accountId: string) => Promise<string>;
+  expectedQuery: string[];
+  happyRow: Record<string, unknown>;
+}
+
+const cases: Case[] = [
+  {
+    label: "epc-lookup-by-address",
+    call: (accountId) =>
+      epcLookupByAddress({ accountId, address: "47 Phoenix Drive", postcode: "CM23 5SR" }),
+    expectedQuery: ["address=47", "postcode=CM23"],
+    happyRow: {
+      uprn: "100090940384",
+      "lodgement-date": "2023-05-15",
+      "total-floor-area": "75.0",
+      address1: "47 PHOENIX DRIVE",
+      posttown: "BISHOP'S STORTFORD",
+      postcode: "CM23 5SR",
+      "current-energy-rating": "C",
+      "potential-energy-rating": "B",
+    },
+  },
+  {
+    label: "epc-lookup-by-uprn",
+    call: (accountId) => epcLookupByUprn({ accountId, uprn: "100090940384" }),
+    expectedQuery: ["uprn=100090940384"],
+    happyRow: {
+      uprn: "100090940384",
+      "lodgement-date": "2023-05-15",
+      "total-floor-area": "75.0",
+      address1: "47 PHOENIX DRIVE",
+      postcode: "CM23 5SR",
+      "current-energy-rating": "C",
+      "potential-energy-rating": "B",
+    },
+  },
+];
+
+describe("epc lookup adapters", () => {
+  for (const c of cases) {
+    describe(c.label, () => {
+      const acct = `acct-${c.label}`;
+
+      it("happy path returns one ok-shaped match with m² and sqft", async () => {
+        await registerKey(acct);
+        let captured = "";
+        mockFetch((url) => {
+          captured = url;
+          return new Response(JSON.stringify({ rows: [c.happyRow] }), { status: 200 });
+        });
+        const text = await c.call(acct);
+        for (const q of c.expectedQuery) {
+          expect(captured).toContain(q);
+        }
+        const parsed = JSON.parse(text);
+        expect(parsed.status).toBe("ok");
+        expect(parsed.matches).toHaveLength(1);
+        expect(parsed.matches[0].total_floor_area_m2).toBe(75.0);
+        expect(parsed.matches[0].total_floor_area_sqft).toBeGreaterThan(800);
+        expect(parsed.matches[0].current_energy_rating).toBe("C");
+        expect(parsed.matches[0].uprn).toBe("100090940384");
+      });
+
+      it("404 surfaces as ok with empty matches", async () => {
+        await registerKey(acct);
+        mockFetch(() => new Response("not found", { status: 404 }));
+        const text = await c.call(acct);
+        const parsed = JSON.parse(text);
+        expect(parsed.status).toBe("ok");
+        expect(parsed.matches).toEqual([]);
+      });
+
+      it("maps HTTP 429 to EpcError preserving status", async () => {
+        await registerKey(acct);
+        mockFetch(() => new Response("rate limit", { status: 429 }));
+        try {
+          await c.call(acct);
+          throw new Error("expected EpcError");
+        } catch (err) {
+          expect(err).toBeInstanceOf(EpcError);
+          expect((err as EpcError).status).toBe(429);
+        }
+      });
+
+      it("maps non-JSON body to BadResponseError", async () => {
+        await registerKey(acct);
+        mockFetch(() => new Response("<html/>", { status: 200 }));
+        await expect(c.call(acct)).rejects.toBeInstanceOf(BadResponseError);
+      });
+
+      it("throws KeyNotRegisteredError when no key is stored", async () => {
+        await expect(c.call(`${acct}-ghost`)).rejects.toBeInstanceOf(KeyNotRegisteredError);
+      });
+    });
+  }
+});

package/payload/premium-plugins/real-agent/plugins/epc/mcp/src/__tests__/schema-parity.test.ts

@@ -0,0 +1,54 @@
+/**
+ * Schema parity: every tool declared in PLUGIN.md frontmatter must have a
+ * handler registered in index.ts, and every handler in index.ts must be
+ * declared in PLUGIN.md. Blocks silent drift between the manifest the
+ * platform reads and the tool surface the server exposes.
+ */
+
+import { describe, expect, it } from "vitest";
+import { readFileSync } from "node:fs";
+import { resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const PLUGIN_ROOT = resolve(here, "../../..");
+
+function readPluginMdTools(): string[] {
+  const md = readFileSync(resolve(PLUGIN_ROOT, "PLUGIN.md"), "utf-8");
+  const fmMatch = md.match(/^---\n([\s\S]*?)\n---/);
+  if (!fmMatch) throw new Error("PLUGIN.md frontmatter not found");
+  const tools: string[] = [];
+  for (const line of fmMatch[1].split("\n")) {
+    const m = line.match(/^\s+-\s+name:\s+(\S+)/);
+    if (m) tools.push(m[1]);
+  }
+  return tools;
+}
+
+function readIndexTools(): string[] {
+  const src = readFileSync(resolve(PLUGIN_ROOT, "mcp/src/index.ts"), "utf-8");
+  const matches = src.matchAll(/server\.tool\(\s*"([^"]+)"/g);
+  return Array.from(matches, (m) => m[1]);
+}
+
+describe("schema parity", () => {
+  it("PLUGIN.md frontmatter and index.ts register the same tool set", () => {
+    const declared = readPluginMdTools().sort();
+    const registered = readIndexTools().sort();
+    expect(registered).toEqual(declared);
+  });
+
+  it("declares all 5 tools (3 key-mgmt + 2 lookup)", () => {
+    const declared = readPluginMdTools();
+    expect(declared).toHaveLength(5);
+    for (const name of [
+      "epc-key-register",
+      "epc-key-deregister",
+      "epc-key-list",
+      "epc-lookup-by-address",
+      "epc-lookup-by-uprn",
+    ]) {
+      expect(declared).toContain(name);
+    }
+  });
+});