@kb-labs/adapters 0.5.0

package/packages/adapters-fs/src/index.test.ts

@@ -0,0 +1,243 @@
+/**
+ * @module @kb-labs/adapters-fs/__tests__
+ * Unit tests for FilesystemStorageAdapter
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { mkdtemp, rm } from "node:fs/promises";
+import { createAdapter } from "./index.js";
+
+describe("FilesystemStorageAdapter", () => {
+  let tmpDir: string;
+  let storage: ReturnType<typeof createAdapter>;
+
+  beforeEach(async () => {
+    tmpDir = await mkdtemp(join(tmpdir(), "kb-test-fs-"));
+    storage = createAdapter({ baseDir: tmpDir });
+  });
+
+  afterEach(async () => {
+    await rm(tmpDir, { recursive: true, force: true });
+  });
+
+  describe("Basic Operations", () => {
+    it("should write and read a file", async () => {
+      const content = Buffer.from("Hello, World!");
+
+      await storage.write("test.txt", content);
+      const result = await storage.read("test.txt");
+
+      expect(result).toEqual(content);
+      expect(result?.toString()).toBe("Hello, World!");
+    });
+
+    it("should return null when reading nonexistent file", async () => {
+      const result = await storage.read("nonexistent.txt");
+
+      expect(result).toBeNull();
+    });
+
+    it("should write file in nested directory", async () => {
+      const content = Buffer.from("Nested content");
+
+      await storage.write("docs/nested/file.txt", content);
+      const result = await storage.read("docs/nested/file.txt");
+
+      expect(result).toEqual(content);
+    });
+
+    it("should check if file exists", async () => {
+      await storage.write("exists.txt", Buffer.from("test"));
+
+      expect(await storage.exists("exists.txt")).toBe(true);
+      expect(await storage.exists("nonexistent.txt")).toBe(false);
+    });
+
+    it("should delete a file", async () => {
+      await storage.write("to-delete.txt", Buffer.from("test"));
+      expect(await storage.exists("to-delete.txt")).toBe(true);
+
+      await storage.delete("to-delete.txt");
+
+      expect(await storage.exists("to-delete.txt")).toBe(false);
+    });
+
+    it("should not throw when deleting nonexistent file", async () => {
+      await expect(storage.delete("nonexistent.txt")).resolves.not.toThrow();
+    });
+  });
+
+  describe("List Operations", () => {
+    it("should list files with prefix", async () => {
+      await storage.write("docs/file1.txt", Buffer.from("1"));
+      await storage.write("docs/file2.txt", Buffer.from("2"));
+      await storage.write("other/file3.txt", Buffer.from("3"));
+
+      const files = await storage.list("docs/");
+
+      expect(files).toHaveLength(2);
+      expect(files).toContain("docs/file1.txt");
+      expect(files).toContain("docs/file2.txt");
+    });
+
+    it("should return empty array when no files match prefix", async () => {
+      const files = await storage.list("nonexistent/");
+
+      expect(files).toEqual([]);
+    });
+  });
+
+  describe("Security", () => {
+    it("should prevent directory traversal attacks", async () => {
+      await expect(
+        storage.write("../outside.txt", Buffer.from("bad")),
+      ).rejects.toThrow("Path traversal detected");
+    });
+
+    it("should prevent absolute path escaping baseDir", async () => {
+      await expect(
+        storage.write("/etc/passwd", Buffer.from("bad")),
+      ).rejects.toThrow("Path traversal detected");
+    });
+  });
+
+  describe("Extended Methods - stat()", () => {
+    it("should return file metadata", async () => {
+      const content = Buffer.from("Test content");
+      await storage.write("test.txt", content);
+
+      const metadata = await storage.stat("test.txt");
+
+      expect(metadata).not.toBeNull();
+      expect(metadata?.path).toBe("test.txt");
+      expect(metadata?.size).toBe(content.length);
+      expect(metadata?.contentType).toBe("text/plain");
+      expect(metadata?.lastModified).toBeDefined();
+    });
+
+    it("should return null for nonexistent file", async () => {
+      const metadata = await storage.stat("nonexistent.txt");
+
+      expect(metadata).toBeNull();
+    });
+
+    it("should detect content types correctly", async () => {
+      await storage.write("test.json", Buffer.from("{}"));
+      await storage.write("test.md", Buffer.from("# Title"));
+      await storage.write("test.png", Buffer.from("fake-png"));
+
+      expect((await storage.stat("test.json"))?.contentType).toBe(
+        "application/json",
+      );
+      expect((await storage.stat("test.md"))?.contentType).toBe(
+        "text/markdown",
+      );
+      expect((await storage.stat("test.png"))?.contentType).toBe("image/png");
+    });
+
+    it("should return octet-stream for unknown extensions", async () => {
+      await storage.write("test.unknown", Buffer.from("data"));
+
+      const metadata = await storage.stat("test.unknown");
+
+      expect(metadata?.contentType).toBe("application/octet-stream");
+    });
+  });
+
+  describe("Extended Methods - copy()", () => {
+    it("should copy file", async () => {
+      const content = Buffer.from("Original content");
+      await storage.write("source.txt", content);
+
+      await storage.copy("source.txt", "destination.txt");
+
+      const sourceStat = await storage.stat("source.txt");
+      const destStat = await storage.stat("destination.txt");
+
+      expect(sourceStat).not.toBeNull();
+      expect(destStat).not.toBeNull();
+      expect(destStat?.size).toBe(sourceStat?.size);
+
+      const destContent = await storage.read("destination.txt");
+      expect(destContent).toEqual(content);
+    });
+
+    it("should copy to nested directory", async () => {
+      await storage.write("source.txt", Buffer.from("test"));
+
+      await storage.copy("source.txt", "nested/dir/copy.txt");
+
+      expect(await storage.exists("nested/dir/copy.txt")).toBe(true);
+    });
+  });
+
+  describe("Extended Methods - move()", () => {
+    it("should move file", async () => {
+      const content = Buffer.from("Content to move");
+      await storage.write("source.txt", content);
+
+      await storage.move("source.txt", "destination.txt");
+
+      expect(await storage.exists("source.txt")).toBe(false);
+      expect(await storage.exists("destination.txt")).toBe(true);
+
+      const movedContent = await storage.read("destination.txt");
+      expect(movedContent).toEqual(content);
+    });
+
+    it("should move to nested directory", async () => {
+      await storage.write("source.txt", Buffer.from("test"));
+
+      await storage.move("source.txt", "nested/dir/moved.txt");
+
+      expect(await storage.exists("source.txt")).toBe(false);
+      expect(await storage.exists("nested/dir/moved.txt")).toBe(true);
+    });
+
+    it("should overwrite existing file when moving", async () => {
+      await storage.write("source.txt", Buffer.from("new content"));
+      await storage.write("destination.txt", Buffer.from("old content"));
+
+      await storage.move("source.txt", "destination.txt");
+
+      const content = await storage.read("destination.txt");
+      expect(content?.toString()).toBe("new content");
+    });
+  });
+
+  describe("Extended Methods - listWithMetadata()", () => {
+    it("should list files with metadata", async () => {
+      await storage.write("docs/file1.txt", Buffer.from("content1"));
+      await storage.write("docs/file2.md", Buffer.from("content2"));
+
+      const files = await storage.listWithMetadata("docs/");
+
+      expect(files).toHaveLength(2);
+      expect(files[0]!.path).toBeDefined();
+      expect(files[0]!.size).toBeGreaterThan(0);
+      expect(files[0]!.lastModified).toBeDefined();
+      expect(files[0]!.contentType).toBeDefined();
+    });
+
+    it("should return empty array when no files match", async () => {
+      const files = await storage.listWithMetadata("nonexistent/");
+
+      expect(files).toEqual([]);
+    });
+
+    it("should include correct content types", async () => {
+      await storage.write("docs/file.json", Buffer.from("{}"));
+      await storage.write("docs/file.txt", Buffer.from("text"));
+
+      const files = await storage.listWithMetadata("docs/");
+
+      const jsonFile = files.find((f) => f.path.endsWith(".json"));
+      const txtFile = files.find((f) => f.path.endsWith(".txt"));
+
+      expect(jsonFile?.contentType).toBe("application/json");
+      expect(txtFile?.contentType).toBe("text/plain");
+    });
+  });
+});

package/packages/adapters-fs/src/index.ts

@@ -0,0 +1,258 @@
+/**
+ * @module @kb-labs/adapters-fs
+ * Filesystem adapter implementing IStorage interface.
+ *
+ * @example
+ * ```typescript
+ * import { createAdapter } from '@kb-labs/adapters-fs';
+ *
+ * const storage = createAdapter({
+ *   baseDir: '/var/data',
+ * });
+ *
+ * await storage.write('docs/readme.md', Buffer.from('# Hello'));
+ * const content = await storage.read('docs/readme.md');
+ * const files = await storage.list('docs/');
+ * await storage.delete('docs/readme.md');
+ * ```
+ */
+
+import fs from "fs-extra";
+import path from "node:path";
+import fg from "fast-glob";
+import type {
+  IStorage,
+  StorageMetadata,
+} from "@kb-labs/core-platform/adapters";
+
+// Re-export manifest
+export { manifest } from "./manifest.js";
+
+/**
+ * Configuration for filesystem storage adapter.
+ */
+export interface FilesystemStorageConfig {
+  /** Base directory for all file operations (default: process.cwd()) */
+  baseDir?: string;
+}
+
+/**
+ * Filesystem implementation of IStorage interface.
+ */
+export class FilesystemStorageAdapter implements IStorage {
+  private baseDir: string;
+
+  constructor(config: FilesystemStorageConfig = {}) {
+    this.baseDir = config.baseDir ?? process.cwd();
+  }
+
+  /**
+   * Resolve relative path to absolute path within baseDir.
+   */
+  private resolvePath(relativePath: string): string {
+    // Normalize path and ensure it's within baseDir (security)
+    const normalized = path.normalize(relativePath);
+    const absolute = path.isAbsolute(normalized)
+      ? normalized
+      : path.join(this.baseDir, normalized);
+
+    // Ensure path is within baseDir (prevent directory traversal)
+    if (!absolute.startsWith(this.baseDir)) {
+      throw new Error(`Path traversal detected: ${relativePath}`);
+    }
+
+    return absolute;
+  }
+
+  async read(filepath: string): Promise<Buffer | null> {
+    const absolutePath = this.resolvePath(filepath);
+
+    try {
+      return await fs.readFile(absolutePath);
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+        return null;
+      }
+      throw error;
+    }
+  }
+
+  async write(filepath: string, data: Buffer): Promise<void> {
+    const absolutePath = this.resolvePath(filepath);
+
+    // Ensure directory exists
+    await fs.ensureDir(path.dirname(absolutePath));
+
+    await fs.writeFile(absolutePath, data);
+  }
+
+  async delete(filepath: string): Promise<void> {
+    const absolutePath = this.resolvePath(filepath);
+
+    try {
+      await fs.unlink(absolutePath);
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+        // File doesn't exist - that's okay
+        return;
+      }
+      throw error;
+    }
+  }
+
+  async list(prefix: string): Promise<string[]> {
+    // List files with a given prefix in their name
+    const pattern = `${prefix}*`;
+    return fg(pattern, {
+      onlyFiles: true,
+      absolute: false,
+      cwd: this.baseDir,
+    });
+  }
+
+  async exists(filepath: string): Promise<boolean> {
+    const absolutePath = this.resolvePath(filepath);
+
+    try {
+      await fs.access(absolutePath);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  // ============================================================================
+  // EXTENDED METHODS (optional - implements IStorage extended interface)
+  // ============================================================================
+
+  /**
+   * Get file metadata (size, mtime, etc).
+   * Optional method - implements IStorage.stat().
+   */
+  async stat(filepath: string): Promise<StorageMetadata | null> {
+    const absolutePath = this.resolvePath(filepath);
+
+    try {
+      const stats = await fs.stat(absolutePath);
+
+      return {
+        path: filepath,
+        size: stats.size,
+        lastModified: stats.mtime.toISOString(),
+        contentType: this.guessContentType(filepath),
+      };
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+        return null;
+      }
+      throw error;
+    }
+  }
+
+  /**
+   * Copy file within storage.
+   * Optional method - implements IStorage.copy().
+   */
+  async copy(sourcePath: string, destPath: string): Promise<void> {
+    const absoluteSource = this.resolvePath(sourcePath);
+    const absoluteDest = this.resolvePath(destPath);
+
+    // Ensure destination directory exists
+    await fs.ensureDir(path.dirname(absoluteDest));
+
+    await fs.copyFile(absoluteSource, absoluteDest);
+  }
+
+  /**
+   * Move file within storage.
+   * Optional method - implements IStorage.move().
+   */
+  async move(sourcePath: string, destPath: string): Promise<void> {
+    const absoluteSource = this.resolvePath(sourcePath);
+    const absoluteDest = this.resolvePath(destPath);
+
+    // Ensure destination directory exists
+    await fs.ensureDir(path.dirname(absoluteDest));
+
+    await fs.move(absoluteSource, absoluteDest, { overwrite: true });
+  }
+
+  /**
+   * List files with metadata.
+   * Optional method - implements IStorage.listWithMetadata().
+   */
+  async listWithMetadata(prefix: string): Promise<StorageMetadata[]> {
+    // List files with a given prefix in their name
+    const pattern = `${prefix}*`;
+    const files = await fg(pattern, {
+      onlyFiles: true,
+      absolute: true,
+      cwd: this.baseDir,
+      stats: true,
+    });
+
+    const results: StorageMetadata[] = [];
+
+    for (const entry of files) {
+      if (typeof entry === "string") {
+        continue;
+      } // Skip if no stats
+
+      const stats = entry.stats;
+      if (!stats) {
+        continue;
+      }
+
+      // Convert absolute path back to relative
+      const relativePath = path.relative(this.baseDir, entry.path);
+
+      results.push({
+        path: relativePath,
+        size: stats.size,
+        lastModified: stats.mtime.toISOString(),
+        contentType: this.guessContentType(relativePath),
+      });
+    }
+
+    return results;
+  }
+
+  /**
+   * Guess content type from file extension.
+   * Simple implementation - can be extended with mime-types library.
+   */
+  private guessContentType(filepath: string): string {
+    const ext = path.extname(filepath).toLowerCase();
+    const mimeTypes: Record<string, string> = {
+      ".txt": "text/plain",
+      ".md": "text/markdown",
+      ".json": "application/json",
+      ".js": "application/javascript",
+      ".ts": "application/typescript",
+      ".html": "text/html",
+      ".css": "text/css",
+      ".png": "image/png",
+      ".jpg": "image/jpeg",
+      ".jpeg": "image/jpeg",
+      ".gif": "image/gif",
+      ".svg": "image/svg+xml",
+      ".pdf": "application/pdf",
+      ".zip": "application/zip",
+    };
+
+    return mimeTypes[ext] ?? "application/octet-stream";
+  }
+}
+
+/**
+ * Create filesystem storage adapter.
+ * This is the factory function called by initPlatform() when loading adapters.
+ */
+export function createAdapter(
+  config?: FilesystemStorageConfig,
+): FilesystemStorageAdapter {
+  return new FilesystemStorageAdapter(config);
+}
+
+// Default export for direct import
+export default createAdapter;

package/packages/adapters-fs/src/manifest.ts

@@ -0,0 +1,35 @@
+/**
+ * @module @kb-labs/adapters-fs/manifest
+ * Adapter manifest for filesystem storage.
+ */
+
+import type { AdapterManifest } from "@kb-labs/core-platform";
+
+/**
+ * Adapter manifest for filesystem storage.
+ */
+export const manifest: AdapterManifest = {
+  manifestVersion: "1.0.0",
+  id: "fs-storage",
+  name: "Filesystem Storage",
+  version: "1.0.0",
+  description: "Local filesystem storage adapter with path security",
+  author: "KB Labs Team",
+  license: "KBPL-1.1",
+  type: "core",
+  implements: "IStorage",
+  capabilities: {
+    streaming: true,
+    custom: {
+      glob: true,
+      metadata: true,
+    },
+  },
+  configSchema: {
+    baseDir: {
+      type: "string",
+      default: "process.cwd()",
+      description: "Base directory for all file operations",
+    },
+  },
+};