mongo.do 0.1.0

package/dist/agentfs/vfs.d.ts

@@ -0,0 +1,249 @@
+/**
+ * AgentFS Virtual Filesystem Implementation
+ *
+ * Virtual filesystem stored in mongo.do collections.
+ * Provides a file-system-like interface backed by MongoDB/mongo.do.
+ *
+ * @module agentfs/vfs
+ *
+ * @example
+ * ```typescript
+ * import { AgentFilesystem } from './vfs'
+ *
+ * const fs = new AgentFilesystem(database)
+ *
+ * // Write and read files
+ * await fs.writeFile('/config.json', '{"key": "value"}')
+ * const content = await fs.readFile('/config.json')
+ *
+ * // Directory operations
+ * await fs.mkdir('/src')
+ * const files = await fs.readdir('/src')
+ *
+ * // Glob pattern matching
+ * const tsFiles = await fs.glob('**\/*.ts')
+ * ```
+ */
+import type { FileSystem, FileStat } from './types';
+/**
+ * Database interface for AgentFilesystem operations.
+ *
+ * This interface abstracts the underlying MongoDB-compatible database,
+ * allowing the filesystem to work with any compatible backend.
+ * Methods take the collection name as the first parameter.
+ */
+export interface AgentFSDatabase {
+    /** Find a single document matching the query */
+    findOne(collection: string, query: Record<string, unknown>): Promise<Record<string, unknown> | null>;
+    /** Find all documents matching the query */
+    find(collection: string, query: Record<string, unknown>): Promise<Record<string, unknown>[]>;
+    /** Insert a new document */
+    insertOne(collection: string, document: Record<string, unknown>): Promise<{
+        insertedId: string;
+    }>;
+    /** Update a single document matching the filter */
+    updateOne(collection: string, filter: Record<string, unknown>, update: {
+        $set?: Record<string, unknown>;
+        $setOnInsert?: Record<string, unknown>;
+    }, options?: {
+        upsert?: boolean;
+    }): Promise<{
+        matchedCount: number;
+        modifiedCount: number;
+        upsertedId?: string;
+    }>;
+    /** Delete a single document matching the filter */
+    deleteOne(collection: string, filter: Record<string, unknown>): Promise<{
+        deletedCount: number;
+    }>;
+    /** Delete all documents matching the filter */
+    deleteMany(collection: string, filter: Record<string, unknown>): Promise<{
+        deletedCount: number;
+    }>;
+}
+/**
+ * AgentFilesystem - Virtual filesystem backed by mongo.do
+ *
+ * Implements the FileSystem interface using a MongoDB-compatible database.
+ * Uses the file path as the document _id for O(1) lookups.
+ *
+ * Features:
+ * - Files and directories with proper POSIX-like semantics
+ * - Implicit parent directory creation
+ * - Path normalization (removes duplicate slashes, resolves . and ..)
+ * - Glob pattern matching for file discovery
+ *
+ * Error codes follow POSIX conventions:
+ * - ENOENT: File or directory does not exist
+ * - EISDIR: Illegal operation on a directory
+ * - ENOTDIR: Not a directory
+ * - EEXIST: File already exists
+ * - ENOTEMPTY: Directory not empty
+ * - EPERM: Operation not permitted
+ *
+ * @example
+ * ```typescript
+ * const fs = new AgentFilesystem(database)
+ *
+ * // Create and read files
+ * await fs.writeFile('/data/config.json', '{}')
+ * const content = await fs.readFile('/data/config.json')
+ *
+ * // Directories are created implicitly
+ * const stat = await fs.stat('/data')
+ * // stat.type === 'directory'
+ * ```
+ */
+export declare class AgentFilesystem implements FileSystem {
+    private db;
+    private collection;
+    /**
+     * Create a new AgentFilesystem instance.
+     *
+     * @param db - Database backend implementing AgentFSDatabase interface
+     */
+    constructor(db: AgentFSDatabase);
+    /**
+     * Normalize a path to ensure consistency.
+     *
+     * Normalization rules:
+     * - Always starts with /
+     * - No duplicate slashes (// becomes /)
+     * - No trailing slash (except for root)
+     * - Resolves . (current directory) components
+     * - Resolves .. (parent directory) components
+     *
+     * @param path - Path to normalize
+     * @returns Normalized absolute path
+     * @internal
+     */
+    private normalizePath;
+    /**
+     * Escape special regex characters in a string.
+     *
+     * @param str - String to escape
+     * @returns String with regex special characters escaped
+     * @internal
+     */
+    private escapeRegex;
+    /**
+     * Read file content at the specified path.
+     *
+     * @param path - Absolute path to the file
+     * @returns Promise resolving to the file content as a string
+     * @throws {Error} ENOENT if file does not exist
+     * @throws {Error} EISDIR if path is a directory
+     */
+    readFile(path: string): Promise<string>;
+    /**
+     * Write content to a file at the specified path.
+     *
+     * Creates parent directories implicitly if they don't exist.
+     * If the file exists, it updates the content and updatedAt timestamp.
+     * If the file doesn't exist, it creates a new file with createdAt set.
+     *
+     * @param path - Absolute path to the file
+     * @param content - Content to write to the file
+     * @throws {Error} EISDIR if path is a directory
+     */
+    writeFile(path: string, content: string): Promise<void>;
+    /**
+     * Create implicit parent directories for a file path.
+     *
+     * Traverses up the path and creates any missing directory entries.
+     *
+     * @param filePath - Absolute path to the file (not the directory)
+     * @internal
+     */
+    private createImplicitDirs;
+    /**
+     * Delete a file at the specified path.
+     *
+     * @param path - Absolute path to the file to delete
+     * @throws {Error} ENOENT if file does not exist
+     * @throws {Error} EISDIR if path is a directory (use rmdir instead)
+     */
+    deleteFile(path: string): Promise<void>;
+    /**
+     * List entries in a directory.
+     *
+     * Returns only direct children (not recursively nested).
+     * Results are sorted alphabetically.
+     *
+     * @param path - Absolute path to the directory
+     * @returns Promise resolving to array of entry names (not full paths)
+     * @throws {Error} ENOENT if directory does not exist
+     * @throws {Error} ENOTDIR if path is a file, not a directory
+     */
+    readdir(path: string): Promise<string[]>;
+    /**
+     * Create a directory at the specified path.
+     *
+     * Creates parent directories implicitly (behaves like mkdir -p).
+     * Idempotent - does not throw if directory already exists.
+     *
+     * @param path - Absolute path to the directory to create
+     * @throws {Error} EEXIST if a file (not directory) already exists at path
+     */
+    mkdir(path: string): Promise<void>;
+    /**
+     * Remove an empty directory at the specified path.
+     *
+     * The directory must be empty (no files or subdirectories).
+     * Cannot remove the root directory.
+     *
+     * @param path - Absolute path to the directory to remove
+     * @throws {Error} ENOENT if directory does not exist
+     * @throws {Error} ENOTDIR if path is a file, not a directory
+     * @throws {Error} ENOTEMPTY if directory contains entries
+     * @throws {Error} EPERM if attempting to remove root directory
+     */
+    rmdir(path: string): Promise<void>;
+    /**
+     * Get file or directory statistics.
+     *
+     * Returns type, size, and timestamps for the entry.
+     * For directories, size is always 0.
+     * Supports implicit directories (directories inferred from file paths).
+     *
+     * @param path - Absolute path to the file or directory
+     * @returns Promise resolving to FileStat with type, size, createdAt, updatedAt
+     * @throws {Error} ENOENT if path does not exist
+     */
+    stat(path: string): Promise<FileStat>;
+    /**
+     * Check if a file or directory exists at the specified path.
+     *
+     * Does not throw errors for non-existent paths.
+     *
+     * @param path - Absolute path to check
+     * @returns Promise resolving to true if path exists, false otherwise
+     */
+    exists(path: string): Promise<boolean>;
+    /**
+     * Find files matching a glob pattern.
+     *
+     * Supports basic glob patterns:
+     * - `*` matches any characters except /
+     * - `**` matches any characters including /
+     * - `?` matches any single character except /
+     *
+     * Returns only files, not directories.
+     * Results are sorted alphabetically.
+     *
+     * @param pattern - Glob pattern to match against file paths
+     * @returns Promise resolving to array of matching file paths
+     *
+     * @example
+     * ```typescript
+     * const tsFiles = await fs.glob('**\/*.ts')
+     * const srcFiles = await fs.glob('/src/*.js')
+     * ```
+     */
+    glob(pattern: string): Promise<string[]>;
+    /**
+     * Convert a glob pattern to a regex string
+     */
+    private globToRegex;
+}
+//# sourceMappingURL=vfs.d.ts.map

package/dist/agentfs/vfs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vfs.d.ts","sourceRoot":"","sources":["../../src/agentfs/vfs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAY,MAAM,SAAS,CAAA;AAE7D;;;;;;GAMG;AACH,MAAM,WAAW,eAAe;IAC9B,gDAAgD;IAChD,OAAO,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC,CAAA;IACpG,4CAA4C;IAC5C,IAAI,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC,CAAA;IAC5F,4BAA4B;IAC5B,SAAS,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC;QAAE,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;IACjG,mDAAmD;IACnD,SAAS,CACP,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,MAAM,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QAAC,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,EAClF,OAAO,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,OAAO,CAAA;KAAE,GAC7B,OAAO,CAAC;QAAE,YAAY,EAAE,MAAM,CAAC;QAAC,aAAa,EAAE,MAAM,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;IAChF,mDAAmD;IACnD,SAAS,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC;QAAE,YAAY,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;IACjG,+CAA+C;IAC/C,UAAU,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC;QAAE,YAAY,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;CACnG;AAeD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,qBAAa,eAAgB,YAAW,UAAU;IAChD,OAAO,CAAC,EAAE,CAAiB;IAC3B,OAAO,CAAC,UAAU,CAAoB;IAEtC;;;;OAIG;gBACS,EAAE,EAAE,eAAe;IAI/B;;;;;;;;;;;;;OAaG;IACH,OAAO,CAAC,aAAa;IAsCrB;;;;;;OAMG;IACH,OAAO,CAAC,WAAW;IAInB;;;;;;;OAOG;IACG,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAgB7C;;;;;;;;;;OAUG;IACG,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAsC7D;;;;;;;OAOG;YACW,kBAAkB;IAuBhC;;;;;;OAMG;IACG,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAgB7C;;;;;;;;;;OAUG;IACG,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAyC9C;;;;;;;;OAQG;IACG,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAsCxC;;;;;;;;;;;OAWG;IACG,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAgCxC;;;;;;;;;;OAUG;IACG,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC;IAkC3C;;;;;;;OAOG;IACG,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAS5C;;;;;;;;;;;;;;;;;;;OAmBG;IACG,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAe9C;;OAEG;IACH,OAAO,CAAC,WAAW;CAqBpB"}