@nkmc/gateway 0.1.0

package/test/registry/resolver.test.ts

@@ -0,0 +1,228 @@
+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, extractDomainPath } from "../../src/registry/resolver.js";
+
+const ACME_SKILL = `---
+name: "Acme Store"
+gateway: nkmc
+version: "1.0"
+roles: [agent]
+---
+
+# Acme Store
+
+E-commerce store.
+
+## API
+
+### List products
+
+\`GET /api/products\` — 免費，public
+
+### Create order
+
+\`POST /api/orders\` — 0.05 USDC / 次，agent
+`;
+
+describe("RegistryResolver", () => {
+  let store: MemoryRegistryStore;
+
+  beforeEach(async () => {
+    store = new MemoryRegistryStore();
+    const record = parseSkillMd("acme-store.com", ACME_SKILL);
+    await store.put("acme-store.com", record);
+  });
+
+  it("should create AgentFs hooks from RegistryStore", async () => {
+    const { onMiss, listDomains } = createRegistryResolver(store);
+    expect(typeof onMiss).toBe("function");
+    expect(typeof listDomains).toBe("function");
+  });
+
+  it("listDomains should return registered domains", async () => {
+    const { listDomains } = createRegistryResolver(store);
+    const domains = await listDomains();
+    expect(domains).toContain("acme-store.com");
+  });
+
+  it("onMiss should create HttpBackend for known domain", async () => {
+    const { onMiss } = createRegistryResolver(store);
+    let mountAdded = false;
+    const added = await onMiss("/acme-store.com/products", (mount) => {
+      mountAdded = true;
+      expect(mount.path).toBe("/acme-store.com");
+    });
+    expect(added).toBe(true);
+    expect(mountAdded).toBe(true);
+  });
+
+  it("onMiss should return false for unknown domain", async () => {
+    const { onMiss } = createRegistryResolver(store);
+    const added = await onMiss("/unknown.com/test", () => {});
+    expect(added).toBe(false);
+  });
+
+  it("onMiss should cache — not recreate backend for same domain", async () => {
+    const { onMiss } = createRegistryResolver(store);
+    let addCount = 0;
+    const addMount = () => {
+      addCount++;
+    };
+    await onMiss("/acme-store.com/products", addMount);
+    await onMiss("/acme-store.com/orders", addMount);
+    expect(addCount).toBe(1); // Only first call creates the mount
+  });
+
+  it("should work end-to-end with AgentFs for ls /", async () => {
+    const { onMiss, listDomains } = createRegistryResolver(store);
+    const staticBackend = new MemoryBackend();
+
+    const fs = new AgentFs({
+      mounts: [{ path: "/memory", backend: staticBackend }],
+      onMiss,
+      listDomains,
+    });
+
+    const result = await fs.execute("ls /");
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      const entries = result.data as string[];
+      expect(entries).toContain("memory/");
+      expect(entries).toContain("acme-store.com/");
+    }
+  });
+
+  it("grep on root should search registry and return SearchResult", async () => {
+    const { onMiss, listDomains, searchDomains } =
+      createRegistryResolver(store);
+    const fs = new AgentFs({
+      mounts: [],
+      onMiss,
+      listDomains,
+      searchDomains,
+    });
+
+    const result = await fs.execute('grep "e-commerce" /');
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      const data = result.data as { domain: string; matchedEndpoints: unknown[] }[];
+      expect(data.length).toBeGreaterThan(0);
+      expect(data[0].domain).toBe("acme-store.com");
+      // "e-commerce" matches service description, not specific endpoints
+      expect(data[0].matchedEndpoints).toEqual([]);
+    }
+  });
+
+  it("grep on root should return matchedEndpoints when query matches endpoint", async () => {
+    const { searchDomains } = createRegistryResolver(store);
+    const results = await searchDomains("products");
+    expect(results.length).toBeGreaterThan(0);
+    expect(results[0].matchedEndpoints.length).toBeGreaterThan(0);
+    expect(results[0].matchedEndpoints[0].path).toBe("/api/products");
+  });
+
+  it("searchEndpoints should filter endpoints within a domain", async () => {
+    const { searchEndpoints } = createRegistryResolver(store);
+    const results = await searchEndpoints("acme-store.com", "products");
+    expect(results).toHaveLength(1);
+    expect(results[0]).toEqual({
+      method: "GET",
+      path: "/api/products",
+      description: expect.any(String),
+    });
+  });
+
+  it("searchEndpoints should return empty for unknown domain", async () => {
+    const { searchEndpoints } = createRegistryResolver(store);
+    const results = await searchEndpoints("unknown.com", "test");
+    expect(results).toEqual([]);
+  });
+
+  it("searchEndpoints should return empty when no endpoints match", async () => {
+    const { searchEndpoints } = createRegistryResolver(store);
+    const results = await searchEndpoints("acme-store.com", "zzzzz");
+    expect(results).toEqual([]);
+  });
+
+  it("searchEndpoints should work end-to-end with AgentFs for domain grep", async () => {
+    const { onMiss, listDomains, searchDomains, searchEndpoints } =
+      createRegistryResolver(store);
+    const fs = new AgentFs({
+      mounts: [],
+      onMiss,
+      listDomains,
+      searchDomains,
+      searchEndpoints,
+    });
+
+    const result = await fs.execute('grep "orders" /acme-store.com/');
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      const data = result.data as { method: string; path: string }[];
+      expect(data).toHaveLength(1);
+      expect(data[0].method).toBe("POST");
+      expect(data[0].path).toBe("/api/orders");
+    }
+  });
+
+  it("onMiss should reject sunset services", async () => {
+    const record = parseSkillMd("old-api.com", ACME_SKILL);
+    (record as any).status = "sunset";
+    (record as any).domain = "old-api.com";
+    await store.put("old-api.com", record);
+
+    const { onMiss } = createRegistryResolver(store);
+    const added = await onMiss("/old-api.com/test", () => {});
+    expect(added).toBe(false);
+  });
+
+  it("should accept RegistryResolverOptions object", async () => {
+    const { onMiss, listDomains } = createRegistryResolver({ store });
+    const domains = await listDomains();
+    expect(domains).toContain("acme-store.com");
+
+    let mounted = false;
+    await onMiss("/acme-store.com/test", () => { mounted = true; });
+    expect(mounted).toBe(true);
+  });
+});
+
+describe("extractDomainPath", () => {
+  it("should extract domain without version", () => {
+    expect(extractDomainPath("/api.cloudflare.com/zones/")).toEqual({
+      domain: "api.cloudflare.com",
+      version: null,
+    });
+  });
+
+  it("should extract domain with @version", () => {
+    expect(extractDomainPath("/api.cloudflare.com@v5/zones/")).toEqual({
+      domain: "api.cloudflare.com",
+      version: "v5",
+    });
+  });
+
+  it("should return null for empty path", () => {
+    expect(extractDomainPath("/")).toEqual({
+      domain: null,
+      version: null,
+    });
+  });
+
+  it("should handle bare domain", () => {
+    expect(extractDomainPath("/acme.com")).toEqual({
+      domain: "acme.com",
+      version: null,
+    });
+  });
+
+  it("should handle domain@version without trailing path", () => {
+    expect(extractDomainPath("/acme.com@2.0")).toEqual({
+      domain: "acme.com",
+      version: "2.0",
+    });
+  });
+});

package/test/registry/rpc-compiler.test.ts

@@ -0,0 +1,112 @@
+import { describe, it, expect } from "vitest";
+import { compileRpcDef } from "../../src/registry/rpc-compiler.js";
+import type { RpcManifestDef } from "../../src/onboard/types.js";
+
+const ETH_RPC_DEF: RpcManifestDef = {
+  url: "https://rpc.ankr.com/eth",
+  convention: "evm",
+  methods: [
+    { rpcMethod: "eth_blockNumber", description: "Returns the latest block number", resource: "blocks", fsOp: "list" },
+    { rpcMethod: "eth_getBlockByNumber", description: "Returns block by number", resource: "blocks", fsOp: "read" },
+    { rpcMethod: "eth_getBalance", description: "Returns account balance in wei", resource: "balances", fsOp: "read" },
+    { rpcMethod: "eth_gasPrice", description: "Returns current gas price in wei" },
+    { rpcMethod: "net_version", description: "Returns the network ID" },
+  ],
+};
+
+describe("compileRpcDef", () => {
+  it("should create a ServiceRecord with RPC endpoints", () => {
+    const { record } = compileRpcDef("rpc.ankr.com", ETH_RPC_DEF);
+    expect(record.domain).toBe("rpc.ankr.com");
+    expect(record.endpoints).toHaveLength(5);
+    expect(record.endpoints[0]).toMatchObject({
+      method: "RPC",
+      path: "eth_blockNumber",
+      description: "Returns the latest block number",
+    });
+  });
+
+  it("should set source type to jsonrpc", () => {
+    const { record } = compileRpcDef("rpc.ankr.com", ETH_RPC_DEF);
+    expect(record.source?.type).toBe("jsonrpc");
+    expect(record.source?.url).toBe("https://rpc.ankr.com/eth");
+  });
+
+  it("should populate rpc meta with resources", () => {
+    const { record } = compileRpcDef("rpc.ankr.com", ETH_RPC_DEF);
+    const rpc = record.source?.rpc;
+    expect(rpc).toBeDefined();
+    expect(rpc!.rpcUrl).toBe("https://rpc.ankr.com/eth");
+    expect(rpc!.convention).toBe("evm");
+
+    // Should have blocks, balances, plus inferred resources for gasPrice and net_version
+    const blockRes = rpc!.resources.find((r) => r.name === "blocks");
+    expect(blockRes).toBeDefined();
+    expect(blockRes!.methods).toEqual({
+      list: "eth_blockNumber",
+      read: "eth_getBlockByNumber",
+    });
+
+    const balanceRes = rpc!.resources.find((r) => r.name === "balances");
+    expect(balanceRes).toBeDefined();
+    expect(balanceRes!.methods).toEqual({ read: "eth_getBalance" });
+  });
+
+  it("should infer resource names from method prefix when not specified", () => {
+    const def: RpcManifestDef = {
+      url: "https://example.com/rpc",
+      methods: [
+        { rpcMethod: "eth_getBlockByNumber", description: "Get block" },
+        { rpcMethod: "eth_sendTransaction", description: "Send tx" },
+      ],
+    };
+    const { record } = compileRpcDef("example.com", def);
+    const rpc = record.source?.rpc;
+    expect(rpc!.convention).toBe("raw");
+    // eth_getBlockByNumber → "blocks", eth_sendTransaction → "transactions"
+    const names = rpc!.resources.map((r) => r.name);
+    expect(names).toContain("blocks");
+    expect(names).toContain("transactions");
+  });
+
+  it("should generate skillMd with RPC Methods section", () => {
+    const { skillMd } = compileRpcDef("rpc.ankr.com", ETH_RPC_DEF);
+    expect(skillMd).toContain("# rpc.ankr.com");
+    expect(skillMd).toContain("## RPC Methods");
+    expect(skillMd).toContain("eth_blockNumber");
+    expect(skillMd).toContain("eth_getBalance");
+    expect(skillMd).toContain("Convention: evm");
+  });
+
+  it("should use custom version and isFirstParty", () => {
+    const { record } = compileRpcDef("rpc.ankr.com", ETH_RPC_DEF, {
+      version: "2.0",
+      isFirstParty: true,
+    });
+    expect(record.version).toBe("2.0");
+    expect(record.isFirstParty).toBe(true);
+  });
+
+  it("should set status active and isDefault true", () => {
+    const { record } = compileRpcDef("rpc.ankr.com", ETH_RPC_DEF);
+    expect(record.status).toBe("active");
+    expect(record.isDefault).toBe(true);
+  });
+
+  it("should handle methods without resource or fsOp", () => {
+    const def: RpcManifestDef = {
+      url: "https://example.com/rpc",
+      methods: [
+        { rpcMethod: "net_version", description: "Network version" },
+      ],
+    };
+    const { record } = compileRpcDef("example.com", def);
+    expect(record.endpoints).toHaveLength(1);
+    expect(record.endpoints[0]).toMatchObject({ method: "RPC", path: "net_version" });
+    // "net_version" → action "version" → pluralized "versions"
+    const rpc = record.source?.rpc;
+    const res = rpc!.resources.find((r) => r.name === "versions");
+    expect(res).toBeDefined();
+    expect(res!.methods).toEqual({});
+  });
+});

package/test/registry/skill-parser.test.ts

@@ -0,0 +1,151 @@
+// packages/gateway/test/registry/skill-parser.test.ts
+import { describe, it, expect } from "vitest";
+import { parseSkillMd, parsePricingAnnotation } from "../../src/registry/skill-parser.js";
+
+const SAMPLE_SKILL_MD = `---
+name: "Acme Store"
+gateway: nkmc
+version: "1.0"
+roles:
+  - agent
+  - premium
+---
+
+# Acme Store
+
+An e-commerce store for widgets.
+
+## Schema
+
+### products (読: public / 写: agent)
+
+Product catalog.
+
+| field | type | description |
+|-------|------|-------------|
+| id | string | Product ID |
+| name | string | Product name |
+| price | number | Price in USD |
+
+## API
+
+### List products
+
+\`GET /api/products\` — 免費，public
+
+Returns all products.
+
+### Create order
+
+\`POST /api/orders\` — 0.05 USDC / 次，agent
+
+Creates a new order.
+`;
+
+describe("parseSkillMd", () => {
+  it("should extract frontmatter fields", () => {
+    const result = parseSkillMd("acme-store.com", SAMPLE_SKILL_MD);
+    expect(result.domain).toBe("acme-store.com");
+    expect(result.name).toBe("Acme Store");
+    expect(result.version).toBe("1.0");
+    expect(result.roles).toEqual(["agent", "premium"]);
+  });
+
+  it("should extract description from first paragraph", () => {
+    const result = parseSkillMd("acme-store.com", SAMPLE_SKILL_MD);
+    expect(result.description).toContain("e-commerce store");
+  });
+
+  it("should extract endpoint summaries from API section", () => {
+    const result = parseSkillMd("acme-store.com", SAMPLE_SKILL_MD);
+    expect(result.endpoints).toHaveLength(2);
+    expect(result.endpoints[0]).toMatchObject({
+      method: "GET",
+      path: "/api/products",
+      description: "List products",
+    });
+    expect(result.endpoints[1]).toMatchObject({
+      method: "POST",
+      path: "/api/orders",
+      description: "Create order",
+    });
+  });
+
+  it("should extract pricing from endpoint annotation", () => {
+    const result = parseSkillMd("acme-store.com", SAMPLE_SKILL_MD);
+    expect(result.endpoints[1].pricing).toEqual({
+      cost: 0.05,
+      currency: "USDC",
+      per: "call",
+    });
+  });
+
+  it("should not have pricing for free endpoints", () => {
+    const result = parseSkillMd("acme-store.com", SAMPLE_SKILL_MD);
+    expect(result.endpoints[0].pricing).toBeUndefined();
+  });
+
+  it("should store the raw skill.md", () => {
+    const result = parseSkillMd("acme-store.com", SAMPLE_SKILL_MD);
+    expect(result.skillMd).toBe(SAMPLE_SKILL_MD);
+  });
+
+  it("should default isFirstParty to false", () => {
+    const result = parseSkillMd("acme-store.com", SAMPLE_SKILL_MD);
+    expect(result.isFirstParty).toBe(false);
+  });
+
+  it("should accept isFirstParty override", () => {
+    const result = parseSkillMd("memory", SAMPLE_SKILL_MD, { isFirstParty: true });
+    expect(result.isFirstParty).toBe(true);
+    expect(result.domain).toBe("memory");
+  });
+
+  it("should handle minimal skill.md", () => {
+    const minimal = `---\nname: "Minimal"\ngateway: nkmc\nversion: "0.1"\nroles: [agent]\n---\n\n# Minimal\n\nA minimal service.\n`;
+    const result = parseSkillMd("minimal.com", minimal);
+    expect(result.name).toBe("Minimal");
+    expect(result.endpoints).toEqual([]);
+    expect(result.description).toContain("minimal service");
+  });
+
+  it("should set status to active and isDefault to true", () => {
+    const result = parseSkillMd("acme-store.com", SAMPLE_SKILL_MD);
+    expect(result.status).toBe("active");
+    expect(result.isDefault).toBe(true);
+  });
+});
+
+describe("parsePricingAnnotation", () => {
+  it("should parse USDC per call", () => {
+    expect(parsePricingAnnotation("0.05 USDC / call")).toEqual({
+      cost: 0.05,
+      currency: "USDC",
+      per: "call",
+    });
+  });
+
+  it("should parse 次 as call", () => {
+    expect(parsePricingAnnotation("0.05 USDC / 次")).toEqual({
+      cost: 0.05,
+      currency: "USDC",
+      per: "call",
+    });
+  });
+
+  it("should parse per byte", () => {
+    expect(parsePricingAnnotation("0.001 ETH / byte")).toEqual({
+      cost: 0.001,
+      currency: "ETH",
+      per: "byte",
+    });
+  });
+
+  it("should return undefined for free text", () => {
+    expect(parsePricingAnnotation("免費，public")).toBeUndefined();
+  });
+
+  it("should return undefined for empty string", () => {
+    expect(parsePricingAnnotation("")).toBeUndefined();
+  });
+});

package/test/registry/skill-to-config.test.ts

@@ -0,0 +1,151 @@
+// packages/gateway/test/registry/skill-to-config.test.ts
+import { describe, it, expect } from "vitest";
+import { skillToHttpConfig } from "../../src/registry/skill-to-config.js";
+import type { ServiceRecord } from "../../src/registry/types.js";
+
+function makeRecord(domain: string, skillMd: string): ServiceRecord {
+  return {
+    domain,
+    name: domain,
+    description: "test",
+    version: "1.0",
+    roles: ["agent"],
+    skillMd,
+    endpoints: [],
+    isFirstParty: false,
+    createdAt: Date.now(),
+    updatedAt: Date.now(),
+    status: "active",
+    isDefault: true,
+  };
+}
+
+describe("skillToHttpConfig", () => {
+  it("should set baseUrl from domain with https", () => {
+    const record = makeRecord("acme-store.com", `---
+name: "Acme"
+gateway: nkmc
+version: "1.0"
+roles: [agent]
+---
+
+# Acme
+
+Test.
+
+## API
+
+### List products
+
+\`GET /api/products\` — 免费，public
+`);
+    const config = skillToHttpConfig(record);
+    expect(config.baseUrl).toBe("https://acme-store.com");
+  });
+
+  it("should create endpoints from API section", () => {
+    const record = makeRecord("acme-store.com", `---
+name: "Acme"
+gateway: nkmc
+version: "1.0"
+roles: [agent]
+---
+
+# Acme
+
+Test.
+
+## API
+
+### List products
+
+\`GET /api/products\` — 免费，public
+
+### Create order
+
+\`POST /api/orders\` — 0.05 USDC / 次，agent
+`);
+    const config = skillToHttpConfig(record);
+    expect(config.endpoints).toHaveLength(2);
+    expect(config.endpoints![0]).toEqual({
+      name: "list-products",
+      method: "GET",
+      apiPath: "/api/products",
+      description: "List products",
+    });
+    expect(config.endpoints![1]).toEqual({
+      name: "create-order",
+      method: "POST",
+      apiPath: "/api/orders",
+      description: "Create order",
+    });
+  });
+
+  it("should create resources from Schema section", () => {
+    const record = makeRecord("acme-store.com", `---
+name: "Acme"
+gateway: nkmc
+version: "1.0"
+roles: [agent]
+---
+
+# Acme
+
+Test.
+
+## Schema
+
+### products (読: public / 写: agent)
+
+Product catalog.
+
+| field | type | description |
+|-------|------|-------------|
+| id | string | Product ID |
+| name | string | Product name |
+`);
+    const config = skillToHttpConfig(record);
+    expect(config.resources).toHaveLength(1);
+    expect(config.resources![0].name).toBe("products");
+    expect(config.resources![0].apiPath).toBe("/products");
+    expect(config.resources![0].fields).toEqual([
+      { name: "id", type: "string", description: "Product ID" },
+      { name: "name", type: "string", description: "Product name" },
+    ]);
+  });
+
+  it("should include basePath in baseUrl when source has basePath", () => {
+    const record = makeRecord("api.cloudflare.com", `---
+name: "Cloudflare"
+gateway: nkmc
+version: "1.0"
+roles: [agent]
+---
+
+# Cloudflare
+
+Test.
+`);
+    record.source = { type: "openapi", basePath: "/client/v4" };
+    const config = skillToHttpConfig(record);
+    expect(config.baseUrl).toBe("https://api.cloudflare.com/client/v4");
+  });
+
+  it("should handle skill.md with no schema or api", () => {
+    const record = makeRecord("simple.com", `---
+name: "Simple"
+gateway: nkmc
+version: "1.0"
+roles: [agent]
+---
+
+# Simple
+
+A simple service.
+`);
+    const config = skillToHttpConfig(record);
+    expect(config.baseUrl).toBe("https://simple.com");
+    expect(config.resources).toEqual([]);
+    expect(config.endpoints).toEqual([]);
+  });
+});