@nkmc/gateway 0.1.0

package/test/registry/lazy-mount.test.ts

@@ -0,0 +1,138 @@
+import { describe, it, expect } from "vitest";
+import { AgentFs, MountResolver } from "@nkmc/agent-fs";
+import { MemoryBackend } from "@nkmc/agent-fs/testing";
+import type { Mount } from "@nkmc/agent-fs";
+
+describe("Lazy mount loading", () => {
+  it("MountResolver should call onMiss when no mount found", async () => {
+    const resolver = new MountResolver();
+    const dynamicBackend = new MemoryBackend();
+    dynamicBackend.seed("products", [{ id: "1", name: "Widget" }]);
+
+    let missCalled = false;
+    resolver.onMiss = async (path: string) => {
+      missCalled = true;
+      const domain = path.split("/").filter(Boolean)[0];
+      if (domain === "acme-store.com") {
+        resolver.add({
+          path: "/acme-store.com",
+          backend: dynamicBackend,
+        });
+        return true;
+      }
+      return false;
+    };
+
+    const result = await resolver.resolveAsync(
+      "/acme-store.com/products/1.json",
+    );
+    expect(missCalled).toBe(true);
+    expect(result).not.toBeNull();
+    expect(result!.mount.path).toBe("/acme-store.com");
+    expect(result!.relativePath).toBe("/products/1.json");
+  });
+
+  it("MountResolver should return null if onMiss returns false", async () => {
+    const resolver = new MountResolver();
+    resolver.onMiss = async () => false;
+
+    const result = await resolver.resolveAsync("/unknown.com/test");
+    expect(result).toBeNull();
+  });
+
+  it("MountResolver should not call onMiss when mount exists", async () => {
+    const resolver = new MountResolver();
+    const backend = new MemoryBackend();
+    resolver.add({ path: "/existing", backend });
+
+    let missCalled = false;
+    resolver.onMiss = async () => {
+      missCalled = true;
+      return false;
+    };
+
+    const result = await resolver.resolveAsync("/existing/file.json");
+    expect(missCalled).toBe(false);
+    expect(result).not.toBeNull();
+    expect(result!.mount.path).toBe("/existing");
+  });
+
+  it("MountResolver resolveAsync works without onMiss set", async () => {
+    const resolver = new MountResolver();
+    const result = await resolver.resolveAsync("/anything");
+    expect(result).toBeNull();
+  });
+
+  it("AgentFs should use resolveAsync for lazy loading", async () => {
+    const dynamicBackend = new MemoryBackend();
+    dynamicBackend.seed("products", [{ id: "42", name: "Widget" }]);
+
+    const fs = new AgentFs({
+      mounts: [],
+      onMiss: async (path, addMount) => {
+        const domain = path.split("/").filter(Boolean)[0];
+        if (domain === "acme-store.com") {
+          addMount({ path: "/acme-store.com", backend: dynamicBackend });
+          return true;
+        }
+        return false;
+      },
+    });
+
+    const result = await fs.execute("cat /acme-store.com/products/42.json");
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect((result.data as { name: string }).name).toBe("Widget");
+    }
+  });
+
+  it("AgentFs ls / should include lazily-loaded domains", async () => {
+    const staticBackend = new MemoryBackend();
+
+    const fs = new AgentFs({
+      mounts: [{ path: "/memory", backend: staticBackend }],
+      listDomains: async () => ["acme-store.com", "stripe.com"],
+    });
+
+    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/");
+      expect(entries).toContain("stripe.com/");
+    }
+  });
+
+  it("AgentFs ls / should deduplicate static mounts and dynamic domains", async () => {
+    const staticBackend = new MemoryBackend();
+
+    const fs = new AgentFs({
+      mounts: [{ path: "/acme-store.com", backend: staticBackend }],
+      listDomains: async () => ["acme-store.com"],
+    });
+
+    const result = await fs.execute("ls /");
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      const entries = result.data as string[];
+      const acmeCount = entries.filter(
+        (e: string) => e === "acme-store.com/",
+      ).length;
+      expect(acmeCount).toBe(1);
+    }
+  });
+
+  it("AgentFs should return NO_MOUNT when onMiss returns false", async () => {
+    const fs = new AgentFs({
+      mounts: [],
+      onMiss: async () => false,
+    });
+
+    const result = await fs.execute("cat /unknown.com/data");
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error.code).toBe("NO_MOUNT");
+    }
+  });
+});

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

@@ -0,0 +1,171 @@
+// packages/gateway/test/registry/memory-store.test.ts
+import { describe, it, expect, beforeEach } from "vitest";
+import { MemoryRegistryStore } from "../../src/registry/memory-store.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("MemoryRegistryStore", () => {
+  let store: MemoryRegistryStore;
+
+  beforeEach(() => {
+    store = new MemoryRegistryStore();
+  });
+
+  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 with empty matchedEndpoints", 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");
+    // "weather" matches the service description, not any endpoint
+    expect(results[0].matchedEndpoints).toEqual([]);
+  });
+
+  it("should search by endpoint description and return matchedEndpoints", async () => {
+    const record = makeRecord("stripe.com", { description: "Payments" });
+    record.endpoints = [
+      { method: "POST", path: "/charges", description: "Create a charge" },
+      { method: "GET", path: "/charges/{id}", description: "Retrieve a charge" },
+      { method: "GET", path: "/balance", description: "Get balance" },
+    ];
+    await store.put("stripe.com", record);
+    const results = await store.search("charge");
+    expect(results).toHaveLength(1);
+    expect(results[0].domain).toBe("stripe.com");
+    expect(results[0].matchedEndpoints).toHaveLength(2);
+    expect(results[0].matchedEndpoints).toEqual([
+      { method: "POST", path: "/charges", description: "Create a charge" },
+      { method: "GET", path: "/charges/{id}", description: "Retrieve a charge" },
+    ]);
+  });
+
+  it("should search by endpoint method", async () => {
+    const record = makeRecord("api.example.com", { description: "Example API" });
+    record.endpoints = [
+      { method: "DELETE", path: "/users/{id}", description: "Remove user" },
+      { method: "GET", path: "/users", description: "List users" },
+    ];
+    await store.put("api.example.com", record);
+    const results = await store.search("DELETE");
+    expect(results).toHaveLength(1);
+    expect(results[0].matchedEndpoints).toEqual([
+      { method: "DELETE", path: "/users/{id}", description: "Remove user" },
+    ]);
+  });
+
+  it("should search by endpoint path", async () => {
+    const record = makeRecord("api.weather.gov", { description: "Weather API" });
+    record.endpoints = [
+      { method: "GET", path: "/alerts/active", description: "Active alerts" },
+      { method: "GET", path: "/alerts/{id}", description: "Single alert" },
+      { method: "GET", path: "/stations", description: "Weather stations" },
+    ];
+    await store.put("api.weather.gov", record);
+    const results = await store.search("alerts");
+    expect(results).toHaveLength(1);
+    expect(results[0].matchedEndpoints).toHaveLength(2);
+    expect(results[0].matchedEndpoints[0].path).toBe("/alerts/active");
+    expect(results[0].matchedEndpoints[1].path).toBe("/alerts/{id}");
+  });
+
+  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("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([]);
+  });
+});

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

@@ -0,0 +1,267 @@
+import { describe, it, expect } from "vitest";
+import { compileOpenApiSpec, fetchAndCompile, extractBasePath } from "../../src/registry/openapi-compiler.js";
+
+const PETSTORE_SPEC = {
+  openapi: "3.0.0",
+  info: { title: "Petstore", description: "A sample pet store", version: "1.0.0" },
+  paths: {
+    "/pets": {
+      get: { summary: "List all pets", operationId: "listPets" },
+      post: { summary: "Create a pet", operationId: "createPet" },
+    },
+    "/pets/{petId}": {
+      get: { summary: "Get pet by ID", operationId: "getPet" },
+      delete: { summary: "Delete a pet", operationId: "deletePet" },
+    },
+  },
+};
+
+describe("compileOpenApiSpec", () => {
+  it("should extract service name and description from info", () => {
+    const { record } = compileOpenApiSpec(PETSTORE_SPEC, { domain: "petstore.com" });
+    expect(record.name).toBe("Petstore");
+    expect(record.description).toBe("A sample pet store");
+    expect(record.domain).toBe("petstore.com");
+  });
+
+  it("should extract endpoints from paths", () => {
+    const { record } = compileOpenApiSpec(PETSTORE_SPEC, { domain: "petstore.com" });
+    expect(record.endpoints).toHaveLength(4);
+    expect(record.endpoints[0]).toMatchObject({ method: "GET", path: "/pets", description: "List all pets" });
+    expect(record.endpoints[1]).toMatchObject({ method: "POST", path: "/pets" });
+  });
+
+  it("should infer resources from path patterns", () => {
+    const { resources } = compileOpenApiSpec(PETSTORE_SPEC, { domain: "petstore.com" });
+    expect(resources.length).toBeGreaterThanOrEqual(1);
+    expect(resources[0].name).toBe("pets");
+  });
+
+  it("should generate skill.md with Schema and API sections", () => {
+    const { skillMd } = compileOpenApiSpec(PETSTORE_SPEC, { domain: "petstore.com" });
+    expect(skillMd).toContain("Petstore");
+    expect(skillMd).toContain("## Schema");
+    expect(skillMd).toContain("### pets (public)");
+    expect(skillMd).toContain("## API");
+  });
+
+  it("should set source type to openapi", () => {
+    const { record } = compileOpenApiSpec(PETSTORE_SPEC, { domain: "petstore.com" });
+    expect(record.source?.type).toBe("openapi");
+  });
+
+  it("should use custom version", () => {
+    const { record } = compileOpenApiSpec(PETSTORE_SPEC, { domain: "petstore.com", version: "2.0" });
+    expect(record.version).toBe("2.0");
+  });
+
+  it("should set status and isDefault", () => {
+    const { record } = compileOpenApiSpec(PETSTORE_SPEC, { domain: "petstore.com" });
+    expect(record.status).toBe("active");
+    expect(record.isDefault).toBe(true);
+  });
+
+  it("should handle empty spec", () => {
+    const { record } = compileOpenApiSpec({}, { domain: "empty.com" });
+    expect(record.name).toBe("empty.com");
+    expect(record.endpoints).toEqual([]);
+  });
+
+  it("should extract basePath from servers[0].url", () => {
+    const spec = {
+      ...PETSTORE_SPEC,
+      servers: [{ url: "https://petstore.com/api/v3" }],
+    };
+    const { record } = compileOpenApiSpec(spec, { domain: "petstore.com" });
+    expect(record.source?.basePath).toBe("/api/v3");
+  });
+
+  it("should not set basePath when servers URL has no path", () => {
+    const spec = {
+      ...PETSTORE_SPEC,
+      servers: [{ url: "https://api.github.com" }],
+    };
+    const { record } = compileOpenApiSpec(spec, { domain: "api.github.com" });
+    expect(record.source?.basePath).toBeUndefined();
+  });
+});
+
+describe("schema extraction", () => {
+  const SPEC_WITH_SCHEMAS = {
+    openapi: "3.0.0",
+    info: { title: "Test API", version: "1.0.0" },
+    components: {
+      schemas: {
+        Pet: {
+          type: "object",
+          required: ["name"],
+          properties: {
+            id: { type: "integer", description: "Pet ID" },
+            name: { type: "string", description: "Pet name" },
+            tag: { type: "string" },
+          },
+        },
+      },
+    },
+    paths: {
+      "/pets": {
+        get: {
+          summary: "List pets",
+          parameters: [
+            { name: "limit", in: "query", required: false, schema: { type: "integer" }, description: "Max items" },
+            { name: "status", in: "query", required: true, schema: { type: "string" } },
+          ],
+          responses: {
+            "200": {
+              description: "A list of pets",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/Pet" },
+                },
+              },
+            },
+          },
+        },
+        post: {
+          summary: "Create pet",
+          requestBody: {
+            required: true,
+            content: {
+              "application/json": {
+                schema: { $ref: "#/components/schemas/Pet" },
+              },
+            },
+          },
+          responses: {
+            "201": { description: "Created" },
+          },
+        },
+      },
+      "/pets/{petId}": {
+        get: {
+          summary: "Get pet",
+          parameters: [
+            { name: "petId", in: "path", required: true, schema: { type: "string" } },
+          ],
+        },
+      },
+    },
+  };
+
+  it("should extract parameters from operations", () => {
+    const { record } = compileOpenApiSpec(SPEC_WITH_SCHEMAS, { domain: "test.com" });
+    const listPets = record.endpoints.find((e) => e.method === "GET" && e.path === "/pets");
+    expect(listPets?.parameters).toHaveLength(2);
+    expect(listPets?.parameters?.[0]).toMatchObject({
+      name: "limit",
+      in: "query",
+      required: false,
+      type: "integer",
+      description: "Max items",
+    });
+    expect(listPets?.parameters?.[1]).toMatchObject({
+      name: "status",
+      in: "query",
+      required: true,
+      type: "string",
+    });
+  });
+
+  it("should extract path parameters", () => {
+    const { record } = compileOpenApiSpec(SPEC_WITH_SCHEMAS, { domain: "test.com" });
+    const getPet = record.endpoints.find((e) => e.method === "GET" && e.path === "/pets/{petId}");
+    expect(getPet?.parameters).toHaveLength(1);
+    expect(getPet?.parameters?.[0]).toMatchObject({
+      name: "petId",
+      in: "path",
+      required: true,
+      type: "string",
+    });
+  });
+
+  it("should extract requestBody with $ref resolution", () => {
+    const { record } = compileOpenApiSpec(SPEC_WITH_SCHEMAS, { domain: "test.com" });
+    const createPet = record.endpoints.find((e) => e.method === "POST" && e.path === "/pets");
+    expect(createPet?.requestBody).toBeDefined();
+    expect(createPet?.requestBody?.contentType).toBe("application/json");
+    expect(createPet?.requestBody?.required).toBe(true);
+    expect(createPet?.requestBody?.properties).toHaveLength(3);
+    expect(createPet?.requestBody?.properties).toContainEqual({
+      name: "name",
+      type: "string",
+      required: true,
+      description: "Pet name",
+    });
+  });
+
+  it("should extract 2xx responses with $ref resolution", () => {
+    const { record } = compileOpenApiSpec(SPEC_WITH_SCHEMAS, { domain: "test.com" });
+    const listPets = record.endpoints.find((e) => e.method === "GET" && e.path === "/pets");
+    expect(listPets?.responses).toHaveLength(1);
+    expect(listPets?.responses?.[0].status).toBe(200);
+    expect(listPets?.responses?.[0].description).toBe("A list of pets");
+    expect(listPets?.responses?.[0].properties).toHaveLength(3);
+  });
+
+  it("should include schema tables in generated skill.md", () => {
+    const { skillMd } = compileOpenApiSpec(SPEC_WITH_SCHEMAS, { domain: "test.com" });
+    // Parameters table
+    expect(skillMd).toContain("**Parameters:**");
+    expect(skillMd).toContain("| limit | query | integer |");
+    expect(skillMd).toContain("| status | query | string | * |");
+    // Request body table
+    expect(skillMd).toContain("**Body** (application/json, required):");
+    expect(skillMd).toContain("| name | string | * |");
+    // Response
+    expect(skillMd).toContain("**Response 200**: A list of pets");
+    expect(skillMd).toContain("| id | integer |");
+  });
+
+  it("should not include schema fields when absent", () => {
+    const { record } = compileOpenApiSpec({
+      openapi: "3.0.0",
+      info: { title: "Bare", version: "1.0.0" },
+      paths: { "/health": { get: { summary: "Health check" } } },
+    }, { domain: "bare.com" });
+    const ep = record.endpoints[0];
+    expect(ep.parameters).toBeUndefined();
+    expect(ep.requestBody).toBeUndefined();
+    expect(ep.responses).toBeUndefined();
+  });
+});
+
+describe("fetchAndCompile", () => {
+  it("should fetch and compile remote spec", async () => {
+    const mockFetch = async (url: string) => {
+      return new Response(JSON.stringify(PETSTORE_SPEC), { status: 200, headers: { "Content-Type": "application/json" } });
+    };
+    const result = await fetchAndCompile("https://petstore.com/openapi.json", { domain: "petstore.com" }, mockFetch as any);
+    expect(result.record.name).toBe("Petstore");
+    expect(result.record.source?.url).toBe("https://petstore.com/openapi.json");
+  });
+
+  it("should throw on failed fetch", async () => {
+    const mockFetch = async () => new Response("Not found", { status: 404 });
+    await expect(fetchAndCompile("https://bad.com/spec.json", { domain: "bad.com" }, mockFetch as any)).rejects.toThrow("Failed to fetch spec");
+  });
+
+  it("should preserve basePath from spec in fetchAndCompile", async () => {
+    const specWithServers = {
+      ...PETSTORE_SPEC,
+      servers: [{ url: "https://api.stripe.com/v1" }],
+    };
+    const mockFetch = async () => {
+      return new Response(JSON.stringify(specWithServers), {
+        status: 200,
+        headers: { "Content-Type": "application/json" },
+      });
+    };
+    const result = await fetchAndCompile(
+      "https://api.stripe.com/openapi.json",
+      { domain: "api.stripe.com" },
+      mockFetch as any,
+    );
+    expect(result.record.source?.url).toBe("https://api.stripe.com/openapi.json");
+    expect(result.record.source?.basePath).toBe("/v1");
+  });
+});