@nkmc/gateway 0.1.0

package/test/registry/context7-backend.test.ts

@@ -0,0 +1,88 @@
+import { describe, it, expect } from "vitest";
+import { Context7Backend } from "../../src/registry/context7-backend.js";
+
+function createMockFetch(handlers: Record<string, (url: string, init?: RequestInit) => Response>) {
+  return async (url: string, init?: RequestInit) => {
+    for (const [pattern, handler] of Object.entries(handlers)) {
+      if (url.includes(pattern)) return handler(url, init);
+    }
+    return new Response("not found", { status: 404 });
+  };
+}
+
+describe("Context7Backend", () => {
+  it("list / should return usage instructions", async () => {
+    const backend = new Context7Backend({ fetchFn: (() => {}) as any });
+    const entries = await backend.list("/");
+    expect(entries.length).toBeGreaterThan(0);
+    expect(entries.some((e) => e.includes("grep"))).toBe(true);
+  });
+
+  it("search / should search libraries", async () => {
+    const backend = new Context7Backend({
+      fetchFn: createMockFetch({
+        "/libs/search": () =>
+          new Response(JSON.stringify([
+            { id: "/facebook/react", name: "React", description: "UI library", totalSnippets: 100 },
+            { id: "/vuejs/core", name: "Vue", description: "Progressive framework", totalSnippets: 80 },
+          ]), { status: 200 }),
+      }) as any,
+    });
+
+    const results = await backend.search("/", "react");
+    expect(results).toHaveLength(2);
+    expect((results[0] as any).id).toBe("/facebook/react");
+    expect((results[0] as any).name).toBe("React");
+    expect((results[0] as any).snippets).toBe(100);
+  });
+
+  it("read /{owner}/{repo} should query overview docs", async () => {
+    const backend = new Context7Backend({
+      fetchFn: createMockFetch({
+        "/context": () => new Response("React is a JavaScript library for building user interfaces.", { status: 200 }),
+      }) as any,
+    });
+
+    const result = (await backend.read("/facebook/react")) as any;
+    expect(result.libraryId).toBe("/facebook/react");
+    expect(result.docs).toContain("React");
+  });
+
+  it("search /{owner}/{repo} should query specific docs", async () => {
+    const backend = new Context7Backend({
+      fetchFn: createMockFetch({
+        "/context": (url) => {
+          expect(url).toContain("query=useState");
+          return new Response("useState is a Hook that lets you add state...", { status: 200 });
+        },
+      }) as any,
+    });
+
+    const results = await backend.search("/facebook/react", "useState");
+    expect(results).toHaveLength(1);
+    expect((results[0] as any).libraryId).toBe("/facebook/react");
+    expect((results[0] as any).docs).toContain("useState");
+  });
+
+  it("read / should return usage hint", async () => {
+    const backend = new Context7Backend({ fetchFn: (() => {}) as any });
+    const result = (await backend.read("/")) as any;
+    expect(result.usage).toBeTruthy();
+  });
+
+  it("write should throw read-only error", async () => {
+    const backend = new Context7Backend({ fetchFn: (() => {}) as any });
+    await expect(backend.write("/test", {})).rejects.toThrow("read-only");
+  });
+
+  it("remove should throw read-only error", async () => {
+    const backend = new Context7Backend({ fetchFn: (() => {}) as any });
+    await expect(backend.remove("/test")).rejects.toThrow("read-only");
+  });
+
+  it("search with single-segment path should return empty", async () => {
+    const backend = new Context7Backend({ fetchFn: (() => {}) as any });
+    const results = await backend.search("/react", "hooks");
+    expect(results).toEqual([]);
+  });
+});

package/test/registry/context7-e2e.test.ts

@@ -0,0 +1,92 @@
+/**
+ * E2E integration test: Context7 API (real network).
+ *
+ * Requires CONTEXT7_API_KEY environment variable.
+ * Skipped automatically when no API key is available.
+ *
+ * Run with: CONTEXT7_API_KEY=ctx7sk_xxx npx vitest run packages/gateway/test/registry/context7-e2e.test.ts
+ */
+import { describe, it, expect } from "vitest";
+import { Context7Client } from "../../src/registry/context7.js";
+import { Context7Backend } from "../../src/registry/context7-backend.js";
+import { MemoryRegistryStore } from "../../src/registry/memory-store.js";
+import { createRegistryResolver } from "../../src/registry/resolver.js";
+import { AgentFs } from "@nkmc/agent-fs";
+
+const API_KEY = process.env.CONTEXT7_API_KEY;
+
+describe.skipIf(!API_KEY)("Context7 Client E2E (real network)", () => {
+  const client = new Context7Client({ apiKey: API_KEY });
+
+  it("should search for React library", async () => {
+    const results = await client.searchLibraries("react");
+    expect(results.length).toBeGreaterThan(0);
+
+    const react = results.find((r) => r.id.includes("react"));
+    expect(react).toBeDefined();
+    expect(react!.name).toBeTruthy();
+  }, 15_000);
+
+  it("should query React hooks documentation", async () => {
+    const results = await client.searchLibraries("react");
+    const react = results.find((r) => r.id.includes("facebook/react") || r.id.includes("react"));
+    expect(react).toBeDefined();
+
+    const docs = await client.queryDocs(react!.id, "useState hook");
+    expect(docs.length).toBeGreaterThan(0);
+    expect(docs.toLowerCase()).toMatch(/react|hook|state|usestate/);
+  }, 30_000);
+
+  it("should search for Next.js library", async () => {
+    const results = await client.searchLibraries("nextjs");
+    expect(results.length).toBeGreaterThan(0);
+  }, 15_000);
+});
+
+describe.skipIf(!API_KEY)("Context7 via AgentFs E2E (real network)", () => {
+  const fs = new AgentFs({
+    mounts: [
+      { path: "/context7", backend: new Context7Backend({ apiKey: API_KEY }) },
+    ],
+    onMiss: async () => false,
+    listDomains: async () => [],
+  });
+
+  it("ls / should show context7", async () => {
+    const result = await fs.execute("ls /");
+    expect(result.ok).toBe(true);
+    expect(result.data).toContain("context7/");
+  });
+
+  it("ls /context7/ should show usage hints", async () => {
+    const result = await fs.execute("ls /context7/");
+    expect(result.ok).toBe(true);
+    const entries = result.data as string[];
+    expect(entries.length).toBeGreaterThan(0);
+    expect(entries.some((e) => e.includes("grep"))).toBe(true);
+  });
+
+  it('grep "react" /context7/ should search libraries', async () => {
+    const result = await fs.execute('grep "react" /context7/');
+    expect(result.ok).toBe(true);
+    const data = result.data as any[];
+    expect(data.length).toBeGreaterThan(0);
+    expect(data.some((r: any) => r.id?.includes("react"))).toBe(true);
+  }, 15_000);
+
+  it("cat /context7/facebook/react should return overview docs", async () => {
+    const result = await fs.execute("cat /context7/facebook/react");
+    expect(result.ok).toBe(true);
+    const data = result.data as any;
+    expect(data.libraryId).toBe("/facebook/react");
+    expect(data.docs.length).toBeGreaterThan(0);
+  }, 30_000);
+
+  it('grep "useState" /context7/facebook/react should query specific docs', async () => {
+    const result = await fs.execute('grep "useState" /context7/facebook/react');
+    expect(result.ok).toBe(true);
+    const data = result.data as any[];
+    expect(data.length).toBeGreaterThan(0);
+    expect((data[0] as any).docs).toBeTruthy();
+  }, 30_000);
+});

package/test/registry/context7.test.ts

@@ -0,0 +1,73 @@
+import { describe, it, expect } from "vitest";
+import { Context7Client } from "../../src/registry/context7.js";
+
+describe("Context7Client", () => {
+  it("should search libraries successfully", async () => {
+    const mockFetch = async (url: string) => {
+      expect(url).toContain("/libs/search");
+      expect(url).toContain("libraryName=react");
+      return new Response(JSON.stringify([{ id: "/facebook/react", name: "React" }]), { status: 200 });
+    };
+    const client = new Context7Client({ fetchFn: mockFetch as any });
+    const results = await client.searchLibraries("react");
+    expect(results).toHaveLength(1);
+    expect(results[0].id).toBe("/facebook/react");
+  });
+
+  it("should query docs successfully", async () => {
+    const mockFetch = async (url: string) => {
+      expect(url).toContain("/context");
+      expect(url).toContain("libraryId=");
+      expect(url).toContain("query=hooks");
+      return new Response("React hooks documentation...", { status: 200 });
+    };
+    const client = new Context7Client({ fetchFn: mockFetch as any });
+    const result = await client.queryDocs("/facebook/react", "hooks");
+    expect(result).toContain("React hooks");
+  });
+
+  it("should throw on failed query", async () => {
+    const mockFetch = async () => new Response("error", { status: 500 });
+    const client = new Context7Client({ fetchFn: mockFetch as any });
+    await expect(client.queryDocs("/bad/lib", "test")).rejects.toThrow("Context7 query failed");
+  });
+
+  it("should throw on failed search", async () => {
+    const mockFetch = async () => new Response("error", { status: 403 });
+    const client = new Context7Client({ fetchFn: mockFetch as any });
+    await expect(client.searchLibraries("test")).rejects.toThrow("Context7 search failed");
+  });
+
+  it("should use custom baseUrl", async () => {
+    let requestedUrl = "";
+    const mockFetch = async (url: string) => {
+      requestedUrl = url;
+      return new Response("ok", { status: 200 });
+    };
+    const client = new Context7Client({ baseUrl: "https://custom.api.com", fetchFn: mockFetch as any });
+    await client.queryDocs("/lib/id", "test");
+    expect(requestedUrl).toContain("https://custom.api.com");
+  });
+
+  it("should send auth header when apiKey is set", async () => {
+    let capturedHeaders: Record<string, string> = {};
+    const mockFetch = async (_url: string, init?: RequestInit) => {
+      capturedHeaders = init?.headers as Record<string, string>;
+      return new Response("ok", { status: 200 });
+    };
+    const client = new Context7Client({ apiKey: "ctx7sk_test123", fetchFn: mockFetch as any });
+    await client.queryDocs("/lib/id", "test");
+    expect(capturedHeaders["Authorization"]).toBe("Bearer ctx7sk_test123");
+  });
+
+  it("should not send auth header when apiKey is not set", async () => {
+    let capturedHeaders: Record<string, string> = {};
+    const mockFetch = async (_url: string, init?: RequestInit) => {
+      capturedHeaders = init?.headers as Record<string, string>;
+      return new Response("ok", { status: 200 });
+    };
+    const client = new Context7Client({ fetchFn: mockFetch as any });
+    await client.queryDocs("/lib/id", "test");
+    expect(capturedHeaders["Authorization"]).toBeUndefined();
+  });
+});

package/test/registry/d1-store.test.ts

@@ -0,0 +1,184 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { D1RegistryStore } from "../../src/registry/d1-store.js";
+import { SqliteD1 } from "../../src/testing/sqlite-d1.js";
+import type { ServiceRecord } from "../../src/registry/types.js";
+
+function makeRecord(
+  domain: string,
+  overrides?: Partial<ServiceRecord>,
+): ServiceRecord {
+  return {
+    domain,
+    name: overrides?.name ?? domain,
+    description: overrides?.description ?? `Service ${domain}`,
+    version: overrides?.version ?? "1.0",
+    roles: ["agent"],
+    skillMd: "---\nname: test\n---\n# Test",
+    endpoints: [
+      { method: "GET", path: "/api/test", description: "test endpoint" },
+    ],
+    isFirstParty: overrides?.isFirstParty ?? false,
+    createdAt: overrides?.createdAt ?? Date.now(),
+    updatedAt: overrides?.updatedAt ?? Date.now(),
+    status: overrides?.status ?? "active",
+    isDefault: overrides?.isDefault ?? true,
+  };
+}
+
+describe("D1RegistryStore", () => {
+  let db: SqliteD1;
+  let store: D1RegistryStore;
+
+  beforeEach(async () => {
+    db = new SqliteD1();
+    store = new D1RegistryStore(db);
+    await store.initSchema();
+  });
+
+  afterEach(() => {
+    db.close();
+  });
+
+  it("should put and get a service", async () => {
+    const record = makeRecord("acme-store.com");
+    await store.put("acme-store.com", record);
+    const result = await store.get("acme-store.com");
+    expect(result).toEqual(record);
+  });
+
+  it("should return null for unknown domain", async () => {
+    const result = await store.get("unknown.com");
+    expect(result).toBeNull();
+  });
+
+  it("should delete a service", async () => {
+    await store.put("acme.com", makeRecord("acme.com"));
+    await store.delete("acme.com");
+    expect(await store.get("acme.com")).toBeNull();
+  });
+
+  it("should list all services as summaries", async () => {
+    await store.put("acme.com", makeRecord("acme.com"));
+    await store.put("memory", makeRecord("memory", { isFirstParty: true }));
+    const list = await store.list();
+    expect(list).toHaveLength(2);
+    expect(list[0]).toEqual({
+      domain: "acme.com",
+      name: "acme.com",
+      description: "Service acme.com",
+      isFirstParty: false,
+    });
+  });
+
+  it("should search by description", async () => {
+    await store.put(
+      "weather.com",
+      makeRecord("weather.com", { description: "Weather forecasts" }),
+    );
+    await store.put(
+      "acme.com",
+      makeRecord("acme.com", { description: "E-commerce store" }),
+    );
+    const results = await store.search("weather");
+    expect(results).toHaveLength(1);
+    expect(results[0].domain).toBe("weather.com");
+  });
+
+  it("should search by endpoint description", async () => {
+    const record = makeRecord("stripe.com", { description: "Payments" });
+    record.endpoints = [
+      { method: "POST", path: "/charges", description: "Create a charge" },
+    ];
+    await store.put("stripe.com", record);
+    const results = await store.search("charge");
+    expect(results).toHaveLength(1);
+    expect(results[0].domain).toBe("stripe.com");
+  });
+
+  it("should return empty for no search match", async () => {
+    await store.put("acme.com", makeRecord("acme.com"));
+    const results = await store.search("zzzzz");
+    expect(results).toHaveLength(0);
+  });
+
+  it("should overwrite on duplicate put", async () => {
+    await store.put("acme.com", makeRecord("acme.com", { description: "v1" }));
+    await store.put("acme.com", makeRecord("acme.com", { description: "v2" }));
+    const result = await store.get("acme.com");
+    expect(result?.description).toBe("v2");
+  });
+
+  it("should call initSchema multiple times (idempotent)", async () => {
+    await store.initSchema();
+    await store.initSchema();
+    await store.put("test.com", makeRecord("test.com"));
+    expect(await store.get("test.com")).not.toBeNull();
+  });
+
+  it("should search by name", async () => {
+    await store.put(
+      "acme.com",
+      makeRecord("acme.com", { name: "Acme Store" }),
+    );
+    const results = await store.search("Acme");
+    expect(results).toHaveLength(1);
+    expect(results[0].domain).toBe("acme.com");
+  });
+
+  it("get() should return only isDefault=true records", async () => {
+    await store.put("acme.com", makeRecord("acme.com", { version: "1.0", isDefault: false }));
+    await store.put("acme.com", makeRecord("acme.com", { version: "2.0", isDefault: true }));
+    const result = await store.get("acme.com");
+    expect(result?.version).toBe("2.0");
+  });
+
+  it("list() should only return default versions", async () => {
+    await store.put("acme.com", makeRecord("acme.com", { version: "1.0", isDefault: false }));
+    await store.put("acme.com", makeRecord("acme.com", { version: "2.0", isDefault: true }));
+    const list = await store.list();
+    expect(list).toHaveLength(1);
+    expect(list[0].domain).toBe("acme.com");
+  });
+
+  it("getVersion() should return specific version", async () => {
+    await store.put("acme.com", makeRecord("acme.com", { version: "1.0", isDefault: false }));
+    await store.put("acme.com", makeRecord("acme.com", { version: "2.0", isDefault: true }));
+    const v1 = await store.getVersion("acme.com", "1.0");
+    expect(v1?.version).toBe("1.0");
+    expect(v1?.isDefault).toBe(false);
+  });
+
+  it("listVersions() should return all versions for a domain", async () => {
+    await store.put("acme.com", makeRecord("acme.com", { version: "1.0", createdAt: 1000 }));
+    await store.put("acme.com", makeRecord("acme.com", { version: "2.0", createdAt: 2000 }));
+    const versions = await store.listVersions("acme.com");
+    expect(versions).toHaveLength(2);
+    expect(versions[0].version).toBe("2.0"); // most recent first
+    expect(versions[1].version).toBe("1.0");
+  });
+
+  it("delete() should remove all versions", async () => {
+    await store.put("acme.com", makeRecord("acme.com", { version: "1.0" }));
+    await store.put("acme.com", makeRecord("acme.com", { version: "2.0" }));
+    await store.delete("acme.com");
+    expect(await store.get("acme.com")).toBeNull();
+    expect(await store.getVersion("acme.com", "1.0")).toBeNull();
+    expect(await store.listVersions("acme.com")).toEqual([]);
+  });
+
+  it("should store and retrieve source config", async () => {
+    const record = makeRecord("acme.com");
+    record.source = { type: "openapi", url: "https://acme.com/spec.json", refreshInterval: 3600 };
+    await store.put("acme.com", record);
+    const result = await store.get("acme.com");
+    expect(result?.source).toEqual(record.source);
+  });
+
+  it("should store and retrieve sunsetDate", async () => {
+    const record = makeRecord("acme.com");
+    record.sunsetDate = Date.now() + 86400000;
+    await store.put("acme.com", record);
+    const result = await store.get("acme.com");
+    expect(result?.sunsetDate).toBe(record.sunsetDate);
+  });
+});

package/test/registry/integration.test.ts

@@ -0,0 +1,129 @@
+import { describe, it, expect, beforeEach } from "vitest";
+import { AgentFs } from "@nkmc/agent-fs";
+import { MemoryBackend } from "@nkmc/agent-fs/testing";
+import { MemoryRegistryStore } from "../../src/registry/memory-store.js";
+import { parseSkillMd } from "../../src/registry/skill-parser.js";
+import { createRegistryResolver } from "../../src/registry/resolver.js";
+
+const WEATHER_SKILL = `---
+name: "Weather API"
+gateway: nkmc
+version: "1.0"
+roles: [agent]
+---
+
+# Weather API
+
+Real-time weather forecasts and historical data.
+
+## API
+
+### Get forecast
+
+\`GET /api/forecast\` — 0.01 USDC / 次，agent
+
+### Get history
+
+\`GET /api/history\` — 0.02 USDC / 次，agent
+`;
+
+const STORE_SKILL = `---
+name: "Acme Store"
+gateway: nkmc
+version: "2.0"
+roles: [agent, premium]
+---
+
+# Acme Store
+
+E-commerce platform for widgets and gadgets.
+
+## Schema
+
+### products (读: public / 写: agent)
+
+All available products.
+
+| field | type | description |
+|-------|------|-------------|
+| id | string | Product ID |
+| name | string | Product name |
+| price | number | Price in USD |
+
+## API
+
+### Create order
+
+\`POST /api/orders\` — 0.05 USDC / 次，agent
+`;
+
+describe("Registry Integration", () => {
+  let fs: AgentFs;
+  let store: MemoryRegistryStore;
+
+  beforeEach(async () => {
+    store = new MemoryRegistryStore();
+
+    await store.put(
+      "weather-api.com",
+      parseSkillMd("weather-api.com", WEATHER_SKILL),
+    );
+    await store.put(
+      "acme-store.com",
+      parseSkillMd("acme-store.com", STORE_SKILL),
+    );
+
+    const { onMiss, listDomains, searchDomains } =
+      createRegistryResolver(store);
+    const memoryBackend = new MemoryBackend();
+    memoryBackend.seed("notes", [{ id: "1", text: "hello" }]);
+
+    fs = new AgentFs({
+      mounts: [{ path: "/memory", backend: memoryBackend }],
+      onMiss,
+      listDomains,
+      searchDomains,
+    });
+  });
+
+  it("ls / shows static mounts and registry services", async () => {
+    const result = await fs.execute("ls /");
+    expect(result.ok).toBe(true);
+    const entries = result.data as string[];
+    expect(entries).toContain("memory/");
+    expect(entries).toContain("weather-api.com/");
+    expect(entries).toContain("acme-store.com/");
+  });
+
+  it("grep on root searches across all registered services", async () => {
+    const result = await fs.execute('grep "weather" /');
+    expect(result.ok).toBe(true);
+    const data = result.data as Array<{ domain: string }>;
+    expect(data.some((d) => d.domain === "weather-api.com")).toBe(true);
+  });
+
+  it("grep on root returns empty for no match", async () => {
+    const result = await fs.execute('grep "zzzznotfound" /');
+    expect(result.ok).toBe(true);
+    expect(result.data).toEqual([]);
+  });
+
+  it("static mount still works normally", async () => {
+    const result = await fs.execute("cat /memory/notes/1.json");
+    expect(result.ok).toBe(true);
+    expect((result.data as { text: string }).text).toBe("hello");
+  });
+
+  it("new service registration is immediately discoverable", async () => {
+    const newSkill = `---\nname: "New Service"\ngateway: nkmc\nversion: "1.0"\nroles: [agent]\n---\n\n# New Service\n\nBrand new.\n`;
+    await store.put(
+      "new-service.com",
+      parseSkillMd("new-service.com", newSkill),
+    );
+
+    const result = await fs.execute("ls /");
+    expect(result.ok).toBe(true);
+    const entries = result.data as string[];
+    expect(entries).toContain("new-service.com/");
+  });
+});