@nkmc/agent-fs 0.1.0

package/test/http.test.ts

@@ -0,0 +1,360 @@
+import { describe, it, expect, beforeAll, afterAll } from "vitest";
+import { createServer, type Server } from "node:http";
+import {
+  HttpBackend,
+  type HttpBackendConfig,
+} from "../src/backends/http.js";
+
+// --- Mock API server ---
+
+interface MockRecord {
+  id: string;
+  [key: string]: unknown;
+}
+
+const mockData: Record<string, MockRecord[]> = {
+  users: [
+    { id: "1", name: "Alice", status: "active" },
+    { id: "2", name: "Bob", status: "inactive" },
+    { id: "3", name: "Charlie", status: "active" },
+  ],
+  products: [
+    { id: "1", name: "Widget", price: 9.99 },
+    { id: "2", name: "Gadget", price: 19.99 },
+  ],
+};
+
+let server: Server;
+let baseUrl: string;
+
+function createMockApiServer(): Promise<{ server: Server; baseUrl: string }> {
+  return new Promise((resolve) => {
+    const srv = createServer((req, res) => {
+      const url = new URL(req.url ?? "/", `http://localhost`);
+      const path = url.pathname;
+      const query = url.searchParams.get("q");
+
+      res.setHeader("Content-Type", "application/json");
+
+      // Verify auth
+      const auth = req.headers.authorization;
+      if (auth !== "Bearer test-token") {
+        res.writeHead(401);
+        res.end(JSON.stringify({ error: "Unauthorized" }));
+        return;
+      }
+
+      // Read body for POST/PUT
+      const chunks: Buffer[] = [];
+      req.on("data", (chunk: Buffer) => chunks.push(chunk));
+      req.on("end", () => {
+        const body = chunks.length
+          ? JSON.parse(Buffer.concat(chunks).toString())
+          : undefined;
+
+        // Route: GET /api/search?q=...
+        if (path === "/api/search" && req.method === "GET") {
+          const results = Object.values(mockData)
+            .flat()
+            .filter((r) => JSON.stringify(r).includes(query ?? ""));
+          res.writeHead(200);
+          res.end(JSON.stringify(results));
+          return;
+        }
+
+        // Route: POST /api/orders
+        if (path === "/api/orders" && req.method === "POST") {
+          res.writeHead(201);
+          res.end(JSON.stringify({ id: "order-1", ...body }));
+          return;
+        }
+
+        // Resource routes: /{resource} and /{resource}/{id}
+        const resourceMatch = path.match(/^\/(\w+)(?:\/(\w+))?$/);
+        if (resourceMatch) {
+          const [, resource, id] = resourceMatch;
+          const collection = mockData[resource];
+
+          if (!collection) {
+            res.writeHead(404);
+            res.end(JSON.stringify({ error: "Not found" }));
+            return;
+          }
+
+          switch (req.method) {
+            case "GET": {
+              if (id) {
+                const record = collection.find((r) => r.id === id);
+                if (!record) {
+                  res.writeHead(404);
+                  res.end(JSON.stringify({ error: "Not found" }));
+                  return;
+                }
+                res.writeHead(200);
+                res.end(JSON.stringify(record));
+              } else {
+                let items = collection;
+                if (query) {
+                  items = collection.filter((r) =>
+                    JSON.stringify(r).includes(query),
+                  );
+                }
+                res.writeHead(200);
+                res.end(JSON.stringify({ data: items }));
+              }
+              return;
+            }
+            case "POST": {
+              const newId = String(collection.length + 1);
+              const newRecord = { id: newId, ...body };
+              collection.push(newRecord);
+              res.writeHead(201);
+              res.end(JSON.stringify(newRecord));
+              return;
+            }
+            case "PUT": {
+              if (!id) {
+                res.writeHead(400);
+                res.end(JSON.stringify({ error: "ID required" }));
+                return;
+              }
+              const idx = collection.findIndex((r) => r.id === id);
+              if (idx === -1) {
+                res.writeHead(404);
+                res.end(JSON.stringify({ error: "Not found" }));
+                return;
+              }
+              collection[idx] = { ...collection[idx], ...body, id };
+              res.writeHead(200);
+              res.end(JSON.stringify(collection[idx]));
+              return;
+            }
+            case "DELETE": {
+              if (!id) {
+                res.writeHead(400);
+                res.end(JSON.stringify({ error: "ID required" }));
+                return;
+              }
+              const delIdx = collection.findIndex((r) => r.id === id);
+              if (delIdx === -1) {
+                res.writeHead(404);
+                res.end(JSON.stringify({ error: "Not found" }));
+                return;
+              }
+              collection.splice(delIdx, 1);
+              res.writeHead(200);
+              res.end(JSON.stringify({ deleted: true }));
+              return;
+            }
+          }
+        }
+
+        res.writeHead(404);
+        res.end(JSON.stringify({ error: "Not found" }));
+      });
+    });
+
+    srv.listen(0, () => {
+      const addr = srv.address();
+      const port = typeof addr === "object" && addr ? addr.port : 0;
+      resolve({ server: srv, baseUrl: `http://localhost:${port}` });
+    });
+  });
+}
+
+// --- Tests ---
+
+describe("HttpBackend", () => {
+  let backend: HttpBackend;
+
+  beforeAll(async () => {
+    const mock = await createMockApiServer();
+    server = mock.server;
+    baseUrl = mock.baseUrl;
+
+    backend = new HttpBackend({
+      baseUrl,
+      auth: { type: "bearer", token: "test-token" },
+      resources: [
+        {
+          name: "users",
+          listKey: "data",
+          fields: [
+            { name: "id", type: "string" },
+            { name: "name", type: "string" },
+            { name: "status", type: "string" },
+          ],
+        },
+        { name: "products", listKey: "data" },
+      ],
+      endpoints: [
+        {
+          name: "search",
+          method: "GET",
+          apiPath: "/api/search",
+          description: "Search across all resources",
+        },
+        {
+          name: "orders",
+          method: "POST",
+          apiPath: "/api/orders",
+          description: "Create an order",
+        },
+      ],
+    });
+  });
+
+  afterAll(
+    () =>
+      new Promise<void>((resolve) => {
+        server.close(() => resolve());
+      }),
+  );
+
+  describe("list", () => {
+    it("should list resources and _api at root", async () => {
+      const result = await backend.list("/");
+      expect(result).toContain("users/");
+      expect(result).toContain("products/");
+      expect(result).toContain("_api/");
+    });
+
+    it("should list record IDs in a resource", async () => {
+      const result = await backend.list("/users/");
+      expect(result).toContain("1.json");
+      expect(result).toContain("2.json");
+      expect(result).toContain("3.json");
+    });
+
+    it("should list available endpoints", async () => {
+      const result = await backend.list("/_api/");
+      expect(result).toHaveLength(2);
+      expect(result[0]).toContain("search");
+      expect(result[1]).toContain("orders");
+    });
+  });
+
+  describe("read", () => {
+    it("should read a single record", async () => {
+      const result = (await backend.read("/users/1.json")) as {
+        name: string;
+      };
+      expect(result.name).toBe("Alice");
+    });
+
+    it("should read all records in a resource", async () => {
+      const result = (await backend.read("/users/")) as unknown[];
+      expect(result).toHaveLength(3);
+    });
+
+    it("should read _schema", async () => {
+      const result = (await backend.read("/users/_schema")) as {
+        resource: string;
+        fields: unknown[];
+      };
+      expect(result.resource).toBe("users");
+      expect(result.fields).toHaveLength(3);
+    });
+
+    it("should invoke a GET endpoint", async () => {
+      const result = (await backend.read("/_api/search")) as unknown[];
+      expect(Array.isArray(result)).toBe(true);
+    });
+
+    it("should throw NotFoundError for missing record", async () => {
+      await expect(backend.read("/users/999.json")).rejects.toThrow();
+    });
+  });
+
+  describe("write", () => {
+    it("should create a new record", async () => {
+      const result = await backend.write("/users/", {
+        name: "Dave",
+        status: "active",
+      });
+      expect(result.id).toBeDefined();
+    });
+
+    it("should update an existing record", async () => {
+      const result = await backend.write("/users/1.json", {
+        name: "Alice Updated",
+      });
+      expect(result.id).toBe("1");
+
+      const updated = (await backend.read("/users/1.json")) as {
+        name: string;
+      };
+      expect(updated.name).toBe("Alice Updated");
+    });
+
+    it("should invoke a POST endpoint", async () => {
+      const result = await backend.write("/_api/orders", {
+        product: "Widget",
+        quantity: 2,
+      });
+      expect(result.id).toBe("order-1");
+    });
+  });
+
+  describe("remove", () => {
+    it("should delete a record", async () => {
+      await backend.remove("/users/2.json");
+      const list = await backend.list("/users/");
+      expect(list).not.toContain("2.json");
+    });
+
+    it("should throw for non-existent record", async () => {
+      await expect(backend.remove("/users/999.json")).rejects.toThrow();
+    });
+  });
+
+  describe("search", () => {
+    it("should search records with server-side query", async () => {
+      const results = (await backend.search("/users/", "active")) as {
+        name: string;
+      }[];
+      expect(results.length).toBeGreaterThanOrEqual(1);
+    });
+  });
+
+  describe("auth", () => {
+    it("should fail without correct auth", async () => {
+      const noAuthBackend = new HttpBackend({
+        baseUrl,
+        auth: { type: "bearer", token: "wrong-token" },
+        resources: [{ name: "users", listKey: "data" }],
+      });
+
+      // The mock server returns 401, list returns empty because response is not array
+      await expect(noAuthBackend.read("/users/1.json")).rejects.toThrow();
+    });
+  });
+
+  describe("integration with AgentFs", async () => {
+    const { AgentFs } = await import("../src/agent-fs.js");
+
+    it("should work as a mount in AgentFs", async () => {
+      const agentFs = new AgentFs({
+        mounts: [{ path: "/service", backend }],
+      });
+
+      const lsRoot = await agentFs.execute("ls /");
+      expect(lsRoot.ok).toBe(true);
+      if (lsRoot.ok) {
+        expect(lsRoot.data).toContain("service/");
+      }
+
+      const lsService = await agentFs.execute("ls /service/");
+      expect(lsService.ok).toBe(true);
+      if (lsService.ok) {
+        expect(lsService.data).toContain("users/");
+      }
+
+      const catUser = await agentFs.execute("cat /service/users/1.json");
+      expect(catUser.ok).toBe(true);
+      if (catUser.ok) {
+        expect((catUser.data as { name: string }).name).toBe("Alice Updated");
+      }
+    });
+  });
+});

package/test/memory.test.ts

@@ -0,0 +1,120 @@
+import { describe, it, expect, beforeEach } from "vitest";
+import { MemoryBackend, NotFoundError } from "../src/backends/memory.js";
+
+describe("MemoryBackend", () => {
+  let backend: MemoryBackend;
+
+  beforeEach(() => {
+    backend = new MemoryBackend();
+    backend.seed("users", [
+      { id: "1", name: "Alice", status: "active" },
+      { id: "2", name: "Bob", status: "inactive" },
+      { id: "3", name: "Charlie", status: "active" },
+    ]);
+  });
+
+  describe("list", () => {
+    it("should list collections at root", async () => {
+      const result = await backend.list("/");
+      expect(result).toEqual(["users/"]);
+    });
+
+    it("should list record ids in a collection", async () => {
+      const result = await backend.list("/users");
+      expect(result).toEqual(["1.json", "2.json", "3.json"]);
+    });
+
+    it("should return empty for unknown collection", async () => {
+      const result = await backend.list("/products");
+      expect(result).toEqual([]);
+    });
+  });
+
+  describe("read", () => {
+    it("should read a single record", async () => {
+      const result = await backend.read("/users/1.json");
+      expect(result).toEqual({ id: "1", name: "Alice", status: "active" });
+    });
+
+    it("should read all records in a collection", async () => {
+      const result = (await backend.read("/users")) as unknown[];
+      expect(result).toHaveLength(3);
+    });
+
+    it("should read _schema", async () => {
+      const result = (await backend.read("/users/_schema")) as {
+        collection: string;
+        fields: unknown[];
+      };
+      expect(result.collection).toBe("users");
+      expect(result.fields).toBeDefined();
+    });
+
+    it("should read _count", async () => {
+      const result = (await backend.read("/users/_count")) as { count: number };
+      expect(result.count).toBe(3);
+    });
+
+    it("should throw NotFoundError for missing record", async () => {
+      await expect(backend.read("/users/999.json")).rejects.toThrow(
+        NotFoundError,
+      );
+    });
+  });
+
+  describe("write", () => {
+    it("should create a new record", async () => {
+      const result = await backend.write("/users/", {
+        name: "Dave",
+        status: "active",
+      });
+      expect(result.id).toBeDefined();
+
+      const record = (await backend.read(`/users/${result.id}.json`)) as {
+        name: string;
+      };
+      expect(record.name).toBe("Dave");
+    });
+
+    it("should update an existing record", async () => {
+      await backend.write("/users/1.json", { name: "Alice Updated" });
+      const record = (await backend.read("/users/1.json")) as { name: string };
+      expect(record.name).toBe("Alice Updated");
+    });
+
+    it("should throw NotFoundError when updating non-existent record", async () => {
+      await expect(
+        backend.write("/users/999.json", { name: "Ghost" }),
+      ).rejects.toThrow(NotFoundError);
+    });
+  });
+
+  describe("remove", () => {
+    it("should delete a record", async () => {
+      await backend.remove("/users/1.json");
+      const list = await backend.list("/users");
+      expect(list).not.toContain("1.json");
+    });
+
+    it("should throw NotFoundError for missing record", async () => {
+      await expect(backend.remove("/users/999.json")).rejects.toThrow(
+        NotFoundError,
+      );
+    });
+  });
+
+  describe("search", () => {
+    it("should find records matching pattern", async () => {
+      const results = (await backend.search("/users", "active")) as {
+        name: string;
+      }[];
+      // Alice and Charlie are active, but Bob has "inactive" which also contains "active"
+      expect(results.length).toBeGreaterThanOrEqual(2);
+    });
+
+    it("should return empty for no matches", async () => {
+      const results = await backend.search("/users", "zzz_no_match");
+      expect(results).toEqual([]);
+    });
+  });
+});

package/test/mount.test.ts

@@ -0,0 +1,94 @@
+import { describe, it, expect } from "vitest";
+import { MountResolver } from "../src/mount.js";
+import { MemoryBackend } from "../src/backends/memory.js";
+
+function createMockBackend() {
+  return new MemoryBackend();
+}
+
+describe("MountResolver", () => {
+  it("should resolve a path to the correct mount", () => {
+    const resolver = new MountResolver();
+    const backend = createMockBackend();
+    resolver.add({ path: "/db", backend });
+
+    const result = resolver.resolve("/db/users/42.json");
+    expect(result).not.toBeNull();
+    expect(result!.mount.path).toBe("/db");
+    expect(result!.relativePath).toBe("/users/42.json");
+  });
+
+  it("should return null for unmatched paths", () => {
+    const resolver = new MountResolver();
+    resolver.add({ path: "/db", backend: createMockBackend() });
+
+    const result = resolver.resolve("/api/weather");
+    expect(result).toBeNull();
+  });
+
+  it("should match the most specific mount", () => {
+    const resolver = new MountResolver();
+    const dbBackend = createMockBackend();
+    const kvBackend = createMockBackend();
+    resolver.add({ path: "/db", backend: dbBackend });
+    resolver.add({ path: "/db/cache", backend: kvBackend });
+
+    const result = resolver.resolve("/db/cache/key1");
+    expect(result!.mount.backend).toBe(kvBackend);
+    expect(result!.relativePath).toBe("/key1");
+  });
+
+  it("should check read permissions", () => {
+    const resolver = new MountResolver();
+    const mount = {
+      path: "/db",
+      backend: createMockBackend(),
+      permissions: { read: ["premium"], write: ["admin"] },
+    };
+    resolver.add(mount);
+
+    const denied = resolver.checkPermission(mount, "read", ["agent"]);
+    expect(denied).not.toBeNull();
+    expect(denied!.code).toBe("PERMISSION_DENIED");
+
+    const allowed = resolver.checkPermission(mount, "read", ["premium"]);
+    expect(allowed).toBeNull();
+  });
+
+  it("should check write permissions", () => {
+    const resolver = new MountResolver();
+    const mount = {
+      path: "/db",
+      backend: createMockBackend(),
+      permissions: { read: ["agent"], write: ["admin"] },
+    };
+    resolver.add(mount);
+
+    const denied = resolver.checkPermission(mount, "write", ["agent"]);
+    expect(denied).not.toBeNull();
+
+    const allowed = resolver.checkPermission(mount, "write", ["admin"]);
+    expect(allowed).toBeNull();
+  });
+
+  it("should allow all if no permissions defined", () => {
+    const resolver = new MountResolver();
+    const mount = { path: "/db", backend: createMockBackend() };
+    resolver.add(mount);
+
+    const result = resolver.checkPermission(mount, "write", ["anyone"]);
+    expect(result).toBeNull();
+  });
+
+  it("should list all mount paths", () => {
+    const resolver = new MountResolver();
+    resolver.add({ path: "/db", backend: createMockBackend() });
+    resolver.add({ path: "/kv", backend: createMockBackend() });
+    resolver.add({ path: "/queue", backend: createMockBackend() });
+
+    const paths = resolver.listMounts();
+    expect(paths).toContain("/db");
+    expect(paths).toContain("/kv");
+    expect(paths).toContain("/queue");
+  });
+});

package/test/parser.test.ts

@@ -0,0 +1,100 @@
+import { describe, it, expect } from "vitest";
+import { parseCommand } from "../src/parser.js";
+import type { FsCommand } from "../src/types.js";
+
+describe("parseCommand", () => {
+  it("should parse ls command", () => {
+    const result = parseCommand("ls /db/users/");
+    expect(result.ok).toBe(true);
+    expect(result.data).toEqual({ op: "ls", path: "/db/users/" });
+  });
+
+  it("should parse cat command", () => {
+    const result = parseCommand("cat /db/users/42.json");
+    expect(result.ok).toBe(true);
+    expect(result.data).toEqual({ op: "cat", path: "/db/users/42.json" });
+  });
+
+  it("should parse rm command", () => {
+    const result = parseCommand("rm /db/users/42.json");
+    expect(result.ok).toBe(true);
+    expect(result.data).toEqual({ op: "rm", path: "/db/users/42.json" });
+  });
+
+  it("should parse write command with JSON data", () => {
+    const result = parseCommand('write /db/users/ \'{"name":"Alice"}\'');
+    expect(result.ok).toBe(true);
+    const cmd = result.data as FsCommand;
+    expect(cmd.op).toBe("write");
+    expect(cmd.path).toBe("/db/users/");
+    expect(cmd.data).toEqual({ name: "Alice" });
+  });
+
+  it("should parse write command without quotes around JSON", () => {
+    const result = parseCommand('write /db/users/ {"name":"Bob"}');
+    expect(result.ok).toBe(true);
+    const cmd = result.data as FsCommand;
+    expect(cmd.data).toEqual({ name: "Bob" });
+  });
+
+  it("should parse grep command with quoted pattern", () => {
+    const result = parseCommand('grep "active" /db/users/');
+    expect(result.ok).toBe(true);
+    const cmd = result.data as FsCommand;
+    expect(cmd.op).toBe("grep");
+    expect(cmd.pattern).toBe("active");
+    expect(cmd.path).toBe("/db/users/");
+  });
+
+  it("should parse grep command with unquoted pattern", () => {
+    const result = parseCommand("grep active /db/users/");
+    expect(result.ok).toBe(true);
+    const cmd = result.data as FsCommand;
+    expect(cmd.pattern).toBe("active");
+  });
+
+  it("should strip nk prefix", () => {
+    const result = parseCommand("nk ls /db/users/");
+    expect(result.ok).toBe(true);
+    expect(result.data).toEqual({ op: "ls", path: "/db/users/" });
+  });
+
+  it("should reject unknown operations", () => {
+    const result = parseCommand("exec /bin/sh");
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error.code).toBe("PARSE_ERROR");
+    }
+  });
+
+  it("should reject path traversal", () => {
+    const result = parseCommand("cat /../../etc/passwd");
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error.code).toBe("PARSE_ERROR");
+    }
+  });
+
+  it("should reject missing path", () => {
+    const result = parseCommand("ls");
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error.code).toBe("PARSE_ERROR");
+    }
+  });
+
+  it("should reject invalid JSON in write", () => {
+    const result = parseCommand("write /db/users/ not-json");
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error.code).toBe("PARSE_ERROR");
+    }
+  });
+
+  it("should handle paths with query params", () => {
+    const result = parseCommand("ls /db/users/?sort=name");
+    expect(result.ok).toBe(true);
+    const cmd = result.data as FsCommand;
+    expect(cmd.path).toBe("/db/users/?sort=name");
+  });
+});