@nkmc/agent-fs 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,96 @@
+import { F as FsResult, A as AgentContext, M as Mount, a as FsError, b as FsBackend, c as FsCommand } from './rpc-D1IHpjF_.cjs';
+export { d as AccessRole, e as FsOp, H as HttpAuth, f as HttpBackend, g as HttpBackendConfig, h as HttpEndpoint, i as HttpResource, J as JsonRpcTransport, j as JsonRpcTransportConfig, P as PaginationConfig, R as RpcBackend, k as RpcBackendConfig, l as RpcCallContext, m as RpcError, n as RpcMethod, o as RpcResource, p as RpcTransport } from './rpc-D1IHpjF_.cjs';
+import * as node_http from 'node:http';
+import { IncomingMessage, ServerResponse } from 'node:http';
+
+/**
+ * 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
+ */
+declare function parseCommand(input: string): FsResult;
+
+interface ResolvedMount {
+    mount: Mount;
+    /** The path relative to the mount point (e.g. "/users/42.json") */
+    relativePath: string;
+}
+declare class MountResolver {
+    private mounts;
+    /** 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;
+    /** Resolve a virtual path to a mount and its relative path */
+    resolve(virtualPath: string): ResolvedMount | null;
+    /** Async resolve: tries sync resolve first, then calls onMiss if set. */
+    resolveAsync(virtualPath: string, agent?: AgentContext): Promise<ResolvedMount | null>;
+    /** Check if a role has permission for an operation on a mount */
+    checkPermission(mount: Mount, op: "read" | "write", roles: string[]): FsError | null;
+    /** List all registered mount paths (used by "ls /") */
+    listMounts(): string[];
+    /** Get the backend for a mount path */
+    getBackend(mountPath: string): FsBackend | undefined;
+}
+
+interface AgentFsOptions {
+    mounts: Mount[];
+    /** Called when a path doesn't match any static mount. Return true if you added a new mount. */
+    onMiss?: (path: string, addMount: (mount: Mount) => void, agent?: AgentContext) => Promise<boolean>;
+    /** Called on "ls /" to include dynamically-known domains. */
+    listDomains?: () => Promise<string[]>;
+    /** Called on "grep /" to search across registered services. */
+    searchDomains?: (query: string) => Promise<unknown[]>;
+    /** Called on "grep pattern /domain/" to search endpoint metadata within a single domain. */
+    searchEndpoints?: (domain: string, query: string) => Promise<unknown[]>;
+}
+/**
+ * The core engine: takes a raw command string, parses it,
+ * routes to the correct backend, and returns a result.
+ */
+declare class AgentFs {
+    private resolver;
+    private _listDomains?;
+    private _searchDomains?;
+    private _searchEndpoints?;
+    constructor(options: AgentFsOptions);
+    /** Execute a raw command string like "ls /db/users/" */
+    execute(input: string, roles?: string[], agent?: AgentContext): Promise<FsResult>;
+    /** Execute a pre-parsed FsCommand */
+    executeCommand(cmd: FsCommand, roles?: string[], agent?: AgentContext): Promise<FsResult>;
+}
+
+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/" }
+ */
+declare function createAgentFsServer(options: ServerOptions): {
+    server: node_http.Server<typeof IncomingMessage, typeof ServerResponse>;
+    listen: () => Promise<void>;
+    close: () => Promise<void>;
+    port: number;
+};
+
+declare const VERSION = "0.1.0";
+
+export { AgentContext, AgentFs, type AgentFsOptions, FsBackend, FsCommand, FsError, FsResult, Mount, MountResolver, type ResolvedMount, type ServerOptions, VERSION, createAgentFsServer, parseCommand };

package/dist/index.d.ts

@@ -0,0 +1,96 @@
+import { F as FsResult, A as AgentContext, M as Mount, a as FsError, b as FsBackend, c as FsCommand } from './rpc-D1IHpjF_.js';
+export { d as AccessRole, e as FsOp, H as HttpAuth, f as HttpBackend, g as HttpBackendConfig, h as HttpEndpoint, i as HttpResource, J as JsonRpcTransport, j as JsonRpcTransportConfig, P as PaginationConfig, R as RpcBackend, k as RpcBackendConfig, l as RpcCallContext, m as RpcError, n as RpcMethod, o as RpcResource, p as RpcTransport } from './rpc-D1IHpjF_.js';
+import * as node_http from 'node:http';
+import { IncomingMessage, ServerResponse } from 'node:http';
+
+/**
+ * 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
+ */
+declare function parseCommand(input: string): FsResult;
+
+interface ResolvedMount {
+    mount: Mount;
+    /** The path relative to the mount point (e.g. "/users/42.json") */
+    relativePath: string;
+}
+declare class MountResolver {
+    private mounts;
+    /** 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;
+    /** Resolve a virtual path to a mount and its relative path */
+    resolve(virtualPath: string): ResolvedMount | null;
+    /** Async resolve: tries sync resolve first, then calls onMiss if set. */
+    resolveAsync(virtualPath: string, agent?: AgentContext): Promise<ResolvedMount | null>;
+    /** Check if a role has permission for an operation on a mount */
+    checkPermission(mount: Mount, op: "read" | "write", roles: string[]): FsError | null;
+    /** List all registered mount paths (used by "ls /") */
+    listMounts(): string[];
+    /** Get the backend for a mount path */
+    getBackend(mountPath: string): FsBackend | undefined;
+}
+
+interface AgentFsOptions {
+    mounts: Mount[];
+    /** Called when a path doesn't match any static mount. Return true if you added a new mount. */
+    onMiss?: (path: string, addMount: (mount: Mount) => void, agent?: AgentContext) => Promise<boolean>;
+    /** Called on "ls /" to include dynamically-known domains. */
+    listDomains?: () => Promise<string[]>;
+    /** Called on "grep /" to search across registered services. */
+    searchDomains?: (query: string) => Promise<unknown[]>;
+    /** Called on "grep pattern /domain/" to search endpoint metadata within a single domain. */
+    searchEndpoints?: (domain: string, query: string) => Promise<unknown[]>;
+}
+/**
+ * The core engine: takes a raw command string, parses it,
+ * routes to the correct backend, and returns a result.
+ */
+declare class AgentFs {
+    private resolver;
+    private _listDomains?;
+    private _searchDomains?;
+    private _searchEndpoints?;
+    constructor(options: AgentFsOptions);
+    /** Execute a raw command string like "ls /db/users/" */
+    execute(input: string, roles?: string[], agent?: AgentContext): Promise<FsResult>;
+    /** Execute a pre-parsed FsCommand */
+    executeCommand(cmd: FsCommand, roles?: string[], agent?: AgentContext): Promise<FsResult>;
+}
+
+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/" }
+ */
+declare function createAgentFsServer(options: ServerOptions): {
+    server: node_http.Server<typeof IncomingMessage, typeof ServerResponse>;
+    listen: () => Promise<void>;
+    close: () => Promise<void>;
+    port: number;
+};
+
+declare const VERSION = "0.1.0";
+
+export { AgentContext, AgentFs, type AgentFsOptions, FsBackend, FsCommand, FsError, FsResult, Mount, MountResolver, type ResolvedMount, type ServerOptions, VERSION, createAgentFsServer, parseCommand };

package/dist/index.js

@@ -0,0 +1,419 @@
+import {
+  HttpBackend,
+  JsonRpcTransport,
+  NotFoundError,
+  RpcBackend,
+  RpcError
+} from "./chunk-7LIZT7L3.js";
+
+// src/parser.ts
+var VALID_OPS = /* @__PURE__ */ new Set(["ls", "cat", "write", "rm", "grep"]);
+function parseCommand(input) {
+  const trimmed = input.trim();
+  const normalized = trimmed.startsWith("nk ") ? trimmed.slice(3).trim() : trimmed;
+  const spaceIdx = normalized.indexOf(" ");
+  if (spaceIdx === -1) {
+    return {
+      ok: false,
+      error: {
+        code: "PARSE_ERROR",
+        message: `Missing path: "${input}"`
+      }
+    };
+  }
+  const op = normalized.slice(0, spaceIdx);
+  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);
+  }
+  const path = normalizePath(rest);
+  if (!path) {
+    return {
+      ok: false,
+      error: { code: "PARSE_ERROR", message: `Invalid path: "${rest}"` }
+    };
+  }
+  return { ok: true, data: { op, path } };
+}
+function parseGrep(rest, raw) {
+  let pattern;
+  let pathPart;
+  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 } };
+}
+function parseWrite(rest, raw) {
+  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();
+  if (dataStr.startsWith("'") && dataStr.endsWith("'") || dataStr.startsWith('"') && dataStr.endsWith('"')) {
+    dataStr = dataStr.slice(1, -1);
+  }
+  let data;
+  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 } };
+}
+function normalizePath(raw) {
+  if (!raw.startsWith("/")) return null;
+  if (raw.includes("..")) return null;
+  const cleaned = raw.replace(/\/+/g, "/");
+  return cleaned;
+}
+
+// src/mount.ts
+var MountResolver = class {
+  mounts = [];
+  /** Optional async callback invoked when resolve() finds no matching mount.
+   *  Should return true if a new mount was added. */
+  onMiss;
+  /** Register a mount point */
+  add(mount) {
+    const normalized = mount.path.replace(/\/+$/, "") || "/";
+    this.mounts.push({ ...mount, path: normalized });
+    this.mounts.sort((a, b) => b.path.length - a.path.length);
+  }
+  /** Resolve a virtual path to a mount and its relative path */
+  resolve(virtualPath) {
+    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, agent) {
+    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, op, roles) {
+    const allowed = mount.permissions?.[op];
+    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() {
+    return this.mounts.map((m) => m.path);
+  }
+  /** Get the backend for a mount path */
+  getBackend(mountPath) {
+    const mount = this.mounts.find((m) => m.path === mountPath);
+    return mount?.backend;
+  }
+};
+
+// src/agent-fs.ts
+var AgentFs = class {
+  resolver;
+  _listDomains;
+  _searchDomains;
+  _searchEndpoints;
+  constructor(options) {
+    this.resolver = new MountResolver();
+    for (const mount of options.mounts) {
+      this.resolver.add(mount);
+    }
+    if (options.onMiss) {
+      const addMount = (mount) => this.resolver.add(mount);
+      this.resolver.onMiss = (path, agent) => options.onMiss(path, addMount, agent);
+    }
+    this._listDomains = options.listDomains;
+    this._searchDomains = options.searchDomains;
+    this._searchEndpoints = options.searchEndpoints;
+  }
+  /** Execute a raw command string like "ls /db/users/" */
+  async execute(input, roles = ["agent"], agent) {
+    const parsed = parseCommand(input);
+    if (!parsed.ok) return parsed;
+    const cmd = parsed.data;
+    return this.executeCommand(cmd, roles, agent);
+  }
+  /** Execute a pre-parsed FsCommand */
+  async executeCommand(cmd, roles = ["agent"], agent) {
+    if (cmd.path === "/" && cmd.op === "ls") {
+      const staticEntries = this.resolver.listMounts().map((p) => p.slice(1) + "/");
+      if (this._listDomains) {
+        const dynamicDomains = await this._listDomains();
+        const dynamicEntries = dynamicDomains.map((d) => d + "/");
+        const merged = [.../* @__PURE__ */ new Set([...staticEntries, ...dynamicEntries])];
+        return { ok: true, data: merged };
+      }
+      return { ok: true, data: staticEntries };
+    }
+    if (cmd.path === "/" && cmd.op === "grep" && this._searchDomains) {
+      const results = await this._searchDomains(cmd.pattern);
+      return { ok: true, data: results };
+    }
+    if (cmd.op === "grep" && this._searchEndpoints) {
+      const segments = cmd.path.split("/").filter(Boolean);
+      if (segments.length === 1) {
+        const domain = segments[0];
+        const results = await this._searchEndpoints(domain, cmd.pattern);
+        return { ok: true, data: results };
+      }
+    }
+    const resolved = await this.resolver.resolveAsync(cmd.path, agent);
+    if (!resolved) {
+      return {
+        ok: false,
+        error: { code: "NO_MOUNT", message: `No mount for path: ${cmd.path}` }
+      };
+    }
+    const permType = cmd.op === "write" || cmd.op === "rm" ? "write" : "read";
+    const permError = this.resolver.checkPermission(
+      resolved.mount,
+      permType,
+      roles
+    );
+    if (permError) {
+      return { ok: false, error: permError };
+    }
+    const backend = resolved.mount.backend;
+    const relPath = resolved.relativePath;
+    try {
+      switch (cmd.op) {
+        case "ls": {
+          const entries = await backend.list(relPath);
+          return { ok: true, data: entries };
+        }
+        case "cat": {
+          const data = await backend.read(relPath);
+          return { ok: true, data };
+        }
+        case "write": {
+          const result = await backend.write(relPath, cmd.data);
+          return { ok: true, data: result };
+        }
+        case "rm": {
+          await backend.remove(relPath);
+          return { ok: true, data: { deleted: cmd.path } };
+        }
+        case "grep": {
+          const results = await backend.search(relPath, cmd.pattern);
+          return { ok: true, data: results };
+        }
+      }
+    } catch (err) {
+      if (err instanceof NotFoundError) {
+        return {
+          ok: false,
+          error: { code: "NOT_FOUND", message: err.message }
+        };
+      }
+      return {
+        ok: false,
+        error: {
+          code: "BACKEND_ERROR",
+          message: err instanceof Error ? err.message : String(err)
+        }
+      };
+    }
+  }
+};
+
+// src/server.ts
+import { createServer } from "http";
+function createAgentFsServer(options) {
+  const { agentFs, port = 3071 } = options;
+  const server = createServer(async (req, res) => {
+    try {
+      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"}`);
+      if (url.pathname === "/execute" && req.method === "POST") {
+        const body = await readBody(req);
+        const { command, roles } = body;
+        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;
+      }
+      if (url.pathname.startsWith("/fs")) {
+        const virtualPath = url.pathname.slice(3) || "/";
+        const query = url.searchParams.get("q");
+        let op;
+        let data;
+        let pattern;
+        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((resolve) => {
+      server.listen(port, () => resolve());
+    }),
+    close: () => new Promise((resolve, reject) => {
+      server.close((err) => err ? reject(err) : resolve());
+    }),
+    port
+  };
+}
+async function readBody(req) {
+  return new Promise((resolve, reject) => {
+    const chunks = [];
+    req.on("data", (chunk) => 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, status, data) {
+  res.writeHead(status, { "Content-Type": "application/json" });
+  res.end(JSON.stringify(data));
+}
+function errorToStatus(code) {
+  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;
+  }
+}
+
+// src/index.ts
+var VERSION = "0.1.0";
+export {
+  AgentFs,
+  HttpBackend,
+  JsonRpcTransport,
+  MountResolver,
+  RpcBackend,
+  RpcError,
+  VERSION,
+  createAgentFsServer,
+  parseCommand
+};