@nkmc/agent-fs 0.1.0

package/src/mount.ts

@@ -0,0 +1,84 @@
+import type { AgentContext, FsBackend, FsError, Mount } from "./types.js";
+
+export interface ResolvedMount {
+  mount: Mount;
+  /** The path relative to the mount point (e.g. "/users/42.json") */
+  relativePath: string;
+}
+
+export class MountResolver {
+  private mounts: Mount[] = [];
+
+  /** Optional async callback invoked when resolve() finds no matching mount.
+   *  Should return true if a new mount was added. */
+  onMiss?: (path: string, agent?: AgentContext) => Promise<boolean>;
+
+  /** Register a mount point */
+  add(mount: Mount): void {
+    // Ensure path starts with / and has no trailing slash
+    const normalized = mount.path.replace(/\/+$/, "") || "/";
+    this.mounts.push({ ...mount, path: normalized });
+    // Sort by path length descending so longer (more specific) mounts match first
+    this.mounts.sort((a, b) => b.path.length - a.path.length);
+  }
+
+  /** Resolve a virtual path to a mount and its relative path */
+  resolve(virtualPath: string): ResolvedMount | null {
+    for (const mount of this.mounts) {
+      if (
+        virtualPath === mount.path ||
+        virtualPath.startsWith(mount.path + "/")
+      ) {
+        const relativePath = virtualPath.slice(mount.path.length) || "/";
+        return { mount, relativePath };
+      }
+    }
+    return null;
+  }
+
+  /** Async resolve: tries sync resolve first, then calls onMiss if set. */
+  async resolveAsync(virtualPath: string, agent?: AgentContext): Promise<ResolvedMount | null> {
+    const result = this.resolve(virtualPath);
+    if (result) return result;
+
+    if (this.onMiss) {
+      const added = await this.onMiss(virtualPath, agent);
+      if (added) {
+        return this.resolve(virtualPath);
+      }
+    }
+
+    return null;
+  }
+
+  /** Check if a role has permission for an operation on a mount */
+  checkPermission(
+    mount: Mount,
+    op: "read" | "write",
+    roles: string[],
+  ): FsError | null {
+    const allowed = mount.permissions?.[op];
+    // No permissions defined = open access
+    if (!allowed) return null;
+
+    const hasRole = roles.some((r) => allowed.includes(r));
+    if (!hasRole) {
+      return {
+        code: "PERMISSION_DENIED",
+        message: `Requires one of [${allowed.join(", ")}] for ${op} on ${mount.path}`,
+      };
+    }
+    return null;
+  }
+
+  /** List all registered mount paths (used by "ls /") */
+  listMounts(): string[] {
+    return this.mounts.map((m) => m.path);
+  }
+
+  /** Get the backend for a mount path */
+  getBackend(mountPath: string): FsBackend | undefined {
+    const mount = this.mounts.find((m) => m.path === mountPath);
+    return mount?.backend;
+  }
+}

package/src/parser.ts

@@ -0,0 +1,162 @@
+import type { FsCommand, FsOp, FsResult } from "./types.js";
+
+const VALID_OPS = new Set<FsOp>(["ls", "cat", "write", "rm", "grep"]);
+
+/**
+ * Parse a raw command string into a structured FsCommand.
+ *
+ * Accepted formats:
+ *   ls /path
+ *   cat /path
+ *   write /path '{"key":"value"}'
+ *   write /path {"key":"value"}
+ *   rm /path
+ *   grep pattern /path
+ */
+export function parseCommand(input: string): FsResult {
+  const trimmed = input.trim();
+
+  // Strip optional "nk " prefix
+  const normalized = trimmed.startsWith("nk ")
+    ? trimmed.slice(3).trim()
+    : trimmed;
+
+  // Split into tokens: op, then the rest
+  const spaceIdx = normalized.indexOf(" ");
+  if (spaceIdx === -1) {
+    return {
+      ok: false,
+      error: {
+        code: "PARSE_ERROR",
+        message: `Missing path: "${input}"`,
+      },
+    };
+  }
+
+  const op = normalized.slice(0, spaceIdx) as FsOp;
+  if (!VALID_OPS.has(op)) {
+    return {
+      ok: false,
+      error: {
+        code: "PARSE_ERROR",
+        message: `Unknown operation: "${op}". Valid: ls, cat, write, rm, grep`,
+      },
+    };
+  }
+
+  const rest = normalized.slice(spaceIdx + 1).trim();
+
+  if (op === "grep") {
+    return parseGrep(rest, input);
+  }
+
+  if (op === "write") {
+    return parseWrite(rest, input);
+  }
+
+  // ls, cat, rm — just need a path
+  const path = normalizePath(rest);
+  if (!path) {
+    return {
+      ok: false,
+      error: { code: "PARSE_ERROR", message: `Invalid path: "${rest}"` },
+    };
+  }
+
+  return { ok: true, data: { op, path } satisfies FsCommand };
+}
+
+function parseGrep(rest: string, raw: string): FsResult {
+  // grep "pattern" /path  OR  grep pattern /path
+  let pattern: string;
+  let pathPart: string;
+
+  if (rest.startsWith('"') || rest.startsWith("'")) {
+    const quote = rest[0];
+    const endQuote = rest.indexOf(quote, 1);
+    if (endQuote === -1) {
+      return {
+        ok: false,
+        error: { code: "PARSE_ERROR", message: `Unterminated quote in: "${raw}"` },
+      };
+    }
+    pattern = rest.slice(1, endQuote);
+    pathPart = rest.slice(endQuote + 1).trim();
+  } else {
+    const spaceIdx = rest.indexOf(" ");
+    if (spaceIdx === -1) {
+      return {
+        ok: false,
+        error: { code: "PARSE_ERROR", message: `grep requires pattern and path: "${raw}"` },
+      };
+    }
+    pattern = rest.slice(0, spaceIdx);
+    pathPart = rest.slice(spaceIdx + 1).trim();
+  }
+
+  const path = normalizePath(pathPart);
+  if (!path) {
+    return {
+      ok: false,
+      error: { code: "PARSE_ERROR", message: `Invalid path: "${pathPart}"` },
+    };
+  }
+
+  return { ok: true, data: { op: "grep", path, pattern } satisfies FsCommand };
+}
+
+function parseWrite(rest: string, raw: string): FsResult {
+  // write /path '{"key":"value"}'  OR  write /path {"key":"value"}
+  // Find where path ends and data begins
+  const pathMatch = rest.match(/^(\/\S+)\s+(.+)$/s);
+  if (!pathMatch) {
+    return {
+      ok: false,
+      error: { code: "PARSE_ERROR", message: `write requires path and data: "${raw}"` },
+    };
+  }
+
+  const path = normalizePath(pathMatch[1]);
+  if (!path) {
+    return {
+      ok: false,
+      error: { code: "PARSE_ERROR", message: `Invalid path: "${pathMatch[1]}"` },
+    };
+  }
+
+  let dataStr = pathMatch[2].trim();
+
+  // Strip surrounding quotes if present
+  if (
+    (dataStr.startsWith("'") && dataStr.endsWith("'")) ||
+    (dataStr.startsWith('"') && dataStr.endsWith('"'))
+  ) {
+    dataStr = dataStr.slice(1, -1);
+  }
+
+  let data: unknown;
+  try {
+    data = JSON.parse(dataStr);
+  } catch {
+    return {
+      ok: false,
+      error: { code: "PARSE_ERROR", message: `Invalid JSON data: ${dataStr}` },
+    };
+  }
+
+  return { ok: true, data: { op: "write", path, data } satisfies FsCommand };
+}
+
+/** Normalize and validate a path. Returns null if invalid. */
+function normalizePath(raw: string): string | null {
+  if (!raw.startsWith("/")) return null;
+
+  // Reject path traversal
+  if (raw.includes("..")) return null;
+
+  // Remove trailing .json for internal routing (keep it for the user-facing path)
+  // Collapse double slashes
+  const cleaned = raw.replace(/\/+/g, "/");
+
+  return cleaned;
+}

package/src/server.ts

@@ -0,0 +1,158 @@
+import { createServer, type IncomingMessage, type ServerResponse } from "node:http";
+import type { AgentFs } from "./agent-fs.js";
+import type { FsOp } from "./types.js";
+
+export interface ServerOptions {
+  agentFs: AgentFs;
+  port?: number;
+}
+
+/**
+ * HTTP server that exposes the AgentFs as a REST API.
+ *
+ * Route mapping:
+ *   GET    /fs/*         → ls (if path ends with /) or cat
+ *   GET    /fs/*?q=xxx   → grep
+ *   POST   /fs/*         → write
+ *   PUT    /fs/*         → write
+ *   DELETE /fs/*         → rm
+ *
+ * Also accepts raw command strings via:
+ *   POST /execute  body: { command: "ls /db/users/" }
+ */
+export function createAgentFsServer(options: ServerOptions) {
+  const { agentFs, port = 3071 } = options;
+
+  const server = createServer(async (req, res) => {
+    try {
+      // CORS
+      res.setHeader("Access-Control-Allow-Origin", "*");
+      res.setHeader("Access-Control-Allow-Methods", "GET, POST, PUT, DELETE, OPTIONS");
+      res.setHeader("Access-Control-Allow-Headers", "Content-Type, Authorization");
+
+      if (req.method === "OPTIONS") {
+        res.writeHead(204);
+        res.end();
+        return;
+      }
+
+      const url = new URL(req.url ?? "/", `http://${req.headers.host ?? "localhost"}`);
+
+      // POST /execute — raw command execution
+      if (url.pathname === "/execute" && req.method === "POST") {
+        const body = await readBody(req);
+        const { command, roles } = body as { command: string; roles?: string[] };
+
+        if (!command || typeof command !== "string") {
+          sendJson(res, 400, { error: "Missing 'command' field" });
+          return;
+        }
+
+        const result = await agentFs.execute(command, roles);
+        const status = result.ok ? 200 : errorToStatus(result.error.code);
+        sendJson(res, status, result);
+        return;
+      }
+
+      // /fs/* — REST-style access
+      if (url.pathname.startsWith("/fs")) {
+        const virtualPath = url.pathname.slice(3) || "/"; // Remove "/fs" prefix
+        const query = url.searchParams.get("q");
+
+        let op: FsOp;
+        let data: unknown | undefined;
+        let pattern: string | undefined;
+
+        switch (req.method) {
+          case "GET":
+            if (query) {
+              op = "grep";
+              pattern = query;
+            } else if (virtualPath.endsWith("/")) {
+              op = "ls";
+            } else {
+              op = "cat";
+            }
+            break;
+          case "POST":
+          case "PUT":
+            op = "write";
+            data = await readBody(req);
+            break;
+          case "DELETE":
+            op = "rm";
+            break;
+          default:
+            sendJson(res, 405, { error: "Method not allowed" });
+            return;
+        }
+
+        const result = await agentFs.executeCommand(
+          { op, path: virtualPath, data, pattern },
+        );
+        const status = result.ok ? 200 : errorToStatus(result.error.code);
+        sendJson(res, status, result);
+        return;
+      }
+
+      sendJson(res, 404, { error: "Not found. Use /fs/* or /execute" });
+    } catch (err) {
+      sendJson(res, 500, {
+        error: err instanceof Error ? err.message : "Internal server error",
+      });
+    }
+  });
+
+  return {
+    server,
+    listen: () =>
+      new Promise<void>((resolve) => {
+        server.listen(port, () => resolve());
+      }),
+    close: () =>
+      new Promise<void>((resolve, reject) => {
+        server.close((err) => (err ? reject(err) : resolve()));
+      }),
+    port,
+  };
+}
+
+async function readBody(req: IncomingMessage): Promise<unknown> {
+  return new Promise((resolve, reject) => {
+    const chunks: Buffer[] = [];
+    req.on("data", (chunk: Buffer) => chunks.push(chunk));
+    req.on("end", () => {
+      const raw = Buffer.concat(chunks).toString("utf-8");
+      if (!raw) {
+        resolve({});
+        return;
+      }
+      try {
+        resolve(JSON.parse(raw));
+      } catch {
+        reject(new Error("Invalid JSON body"));
+      }
+    });
+    req.on("error", reject);
+  });
+}
+
+function sendJson(res: ServerResponse, status: number, data: unknown): void {
+  res.writeHead(status, { "Content-Type": "application/json" });
+  res.end(JSON.stringify(data));
+}
+
+function errorToStatus(code: string): number {
+  switch (code) {
+    case "PARSE_ERROR":
+    case "INVALID_PATH":
+      return 400;
+    case "PERMISSION_DENIED":
+      return 403;
+    case "NOT_FOUND":
+    case "NO_MOUNT":
+      return 404;
+    default:
+      return 500;
+  }
+}

package/src/testing.ts

@@ -0,0 +1,3 @@
+export { MemoryBackend } from "./backends/memory.js";
+export { HttpBackend } from "./backends/http.js";
+export { RpcBackend } from "./backends/rpc.js";

package/src/types.ts

@@ -0,0 +1,52 @@
+/** The 5 filesystem operations */
+export type FsOp = "ls" | "cat" | "write" | "rm" | "grep";
+
+/** A parsed command from the LLM */
+export interface FsCommand {
+  op: FsOp;
+  path: string;
+  data?: unknown;
+  pattern?: string;
+}
+
+/** Result of a filesystem operation */
+export type FsResult =
+  | { ok: true; data: unknown }
+  | { ok: false; error: FsError };
+
+/** Error types */
+export type FsError =
+  | { code: "PARSE_ERROR"; message: string }
+  | { code: "INVALID_PATH"; message: string }
+  | { code: "NOT_FOUND"; message: string }
+  | { code: "PERMISSION_DENIED"; message: string }
+  | { code: "NO_MOUNT"; message: string }
+  | { code: "BACKEND_ERROR"; message: string };
+
+/** Agent identity context passed through the call chain */
+export interface AgentContext {
+  id: string;
+  roles: string[];
+}
+
+/** Access role for permissions */
+export type AccessRole = "public" | "agent" | "premium" | "admin" | string;
+
+/** Mount point configuration — maps a virtual path to a backend */
+export interface Mount {
+  path: string;
+  backend: FsBackend;
+  permissions?: {
+    read?: AccessRole[];
+    write?: AccessRole[];
+  };
+}
+
+/** The interface every backend must implement */
+export interface FsBackend {
+  list(path: string): Promise<string[]>;
+  read(path: string): Promise<unknown>;
+  write(path: string, data: unknown): Promise<{ id: string }>;
+  remove(path: string): Promise<void>;
+  search(path: string, pattern: string): Promise<unknown[]>;
+}