@remodlai/lexiqfs 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,397 @@
+import * as _zenfs_core from '@zenfs/core';
+import { FileSystem, InodeLike, CreationOptions } from '@zenfs/core';
+export * from '@zenfs/core';
+import { Client } from '@libsql/client';
+
+/**
+ * Default mode values for convenience
+ */
+declare const DEFAULT_DIR_MODE: number;
+declare const DEFAULT_FILE_MODE: number;
+/**
+ * Configuration options for LibSQLBackend
+ */
+interface LibSQLBackendOptions {
+    /**
+     * URL for the local embedded replica file
+     * Example: "file:/project.db" or "file:/agent-workspace.db"
+     */
+    url?: string;
+    /**
+     * URL for the remote libsql-server to sync with
+     * Example: "http://libsql-server:8080/v1/namespaces/org-123/project"
+     */
+    syncUrl?: string;
+    /**
+     * Authentication token for remote sync
+     */
+    authToken?: string;
+    /**
+     * Organization ID for multi-tenant isolation
+     */
+    organizationId: string;
+    /**
+     * Agent ID (null for project filesystem, string for agent workspace)
+     */
+    agentId?: string | null;
+    /**
+     * Sync interval in milliseconds (default: 60000 = 1 minute)
+     */
+    syncInterval?: number;
+    /**
+     * Label for this store instance
+     */
+    label?: string;
+    /**
+     * Maximum storage size in bytes (for usage reporting)
+     */
+    maxSize?: number;
+}
+/**
+ * Helper to check if mode indicates a directory
+ */
+declare function isDirectory(mode: number): boolean;
+/**
+ * Helper to check if mode indicates a regular file
+ */
+declare function isFile(mode: number): boolean;
+/**
+ * File system change event type
+ * - 'change': file content modified
+ * - 'rename': file created or deleted (Node.js fs.watch convention)
+ */
+type FSChangeEventType = 'change' | 'rename';
+/**
+ * File system change event payload
+ * Uses path (not inode ID) so watch() can match events to watchers
+ */
+interface FSChangeEvent {
+    eventType: FSChangeEventType;
+    path: string;
+    timestamp: number;
+}
+/**
+ * Callback for file system change events
+ */
+type FSChangeCallback = (event: FSChangeEvent) => void;
+/**
+ * Get current ISO8601 timestamp
+ */
+declare function nowISO(): string;
+
+/**
+ * LibSQLTransaction - Atomic operations for libSQL-backed ZenFS filesystem
+ *
+ * This provides path-based storage where:
+ * - Keys are file paths (strings like '/src/main.ts')
+ * - Values are Uint8Array data (file content)
+ *
+ * Why path-based instead of inode-based?
+ * - libSQL already provides inode-level efficiency (no BLOB copy on UPDATE)
+ * - watch() needs paths, not inode IDs
+ * - Simpler schema, simpler code
+ */
+
+/**
+ * AsyncTransaction base class compatible with ZenFS
+ * Path-based interface for filesystem operations
+ */
+declare abstract class AsyncTransactionBase {
+    protected asyncDone: Promise<unknown>;
+    /**
+     * Run an async operation from sync context
+     */
+    protected async(promise: Promise<unknown>): void;
+    abstract keys(): Promise<Iterable<string>>;
+    abstract get(path: string, offset: number, end?: number): Promise<Uint8Array | undefined>;
+    abstract getSync(path: string, offset: number, end?: number): Uint8Array | undefined;
+    abstract set(path: string, data: Uint8Array, offset: number): Promise<void>;
+    abstract setSync(path: string, data: Uint8Array, offset: number): void;
+    abstract remove(path: string): Promise<void>;
+    abstract removeSync(path: string): void;
+}
+/**
+ * LibSQLTransaction provides atomic operations using libSQL
+ *
+ * Path-based storage where:
+ * - keys are strings (file paths like '/src/main.ts')
+ * - values are Uint8Array (file content)
+ *
+ * We store these in the 'files' table using path as the primary key.
+ */
+declare class LibSQLTransaction extends AsyncTransactionBase {
+    readonly store: LibSQLStore;
+    private readonly client;
+    private readonly organizationId;
+    private readonly agentId;
+    private readonly onCommit?;
+    private cache;
+    private pendingWrites;
+    private pendingDeletes;
+    private committed;
+    constructor(store: LibSQLStore, client: Client, organizationId: string, agentId: string | null, onCommit?: ((events: FSChangeEvent[]) => void) | undefined);
+    /**
+     * Get all keys (file paths) in the store
+     */
+    keys(): Promise<Iterable<string>>;
+    /**
+     * Get data for a file path
+     *
+     * @param path - The file path to look up (e.g., '/src/main.ts')
+     * @param offset - Start offset in the data
+     * @param end - End offset (exclusive), or undefined for rest of data
+     */
+    get(path: string, offset: number, end?: number): Promise<Uint8Array | undefined>;
+    /**
+     * Synchronous get - uses cache only
+     * Throws EAGAIN if data not in cache
+     */
+    getSync(path: string, offset: number, end?: number): Uint8Array | undefined;
+    /**
+     * Set data for a file path
+     *
+     * @param path - The file path (e.g., '/src/main.ts')
+     * @param data - The data to store
+     * @param offset - Offset at which to write (0 for full replacement)
+     */
+    set(path: string, data: Uint8Array, offset: number): Promise<void>;
+    /**
+     * Synchronous set - queues for async write
+     */
+    setSync(path: string, data: Uint8Array, offset: number): void;
+    /**
+     * Remove a file path from the store
+     */
+    remove(path: string): Promise<void>;
+    /**
+     * Synchronous remove - queues for async delete
+     */
+    removeSync(path: string): void;
+    /**
+     * Commit all pending changes to the database
+     */
+    commit(): Promise<void>;
+    /**
+     * Abort - discard pending changes
+     */
+    abort(): void;
+    /**
+     * Slice data according to offset/end
+     */
+    private sliceData;
+    /**
+     * Decode base64 string to Uint8Array
+     */
+    private decodeBase64;
+    /**
+     * Symbol.asyncDispose for using/await using
+     */
+    [Symbol.asyncDispose](): Promise<void>;
+    /**
+     * Symbol.dispose for using
+     */
+    [Symbol.dispose](): void;
+}
+
+/**
+ * LibSQLStore - ZenFS Store implementation backed by libSQL
+ *
+ * This implements the ZenFS Store interface using libSQL as the storage backend.
+ * It supports both local embedded replicas (SQLite WASM) and remote sync to libsql-server.
+ *
+ * Key concepts:
+ * - Store is a path-based interface (path → Uint8Array)
+ * - All operations go through transactions for atomicity
+ * - watch() events use paths (not inode IDs) for easy matching
+ */
+
+/**
+ * Usage information for the store
+ */
+interface UsageInfo {
+    totalSpace: number;
+    freeSpace: number;
+}
+/**
+ * Store flags for optimization hints
+ */
+type StoreFlag = 'partial';
+/**
+ * Store interface compatible with ZenFS
+ */
+interface Store {
+    readonly type?: number;
+    readonly name: string;
+    readonly label?: string;
+    readonly uuid?: string;
+    readonly flags?: readonly StoreFlag[];
+    sync(): Promise<void>;
+    transaction(): LibSQLTransaction;
+    usage?(): UsageInfo;
+}
+/**
+ * LibSQLStore implements the ZenFS Store interface
+ *
+ * Architecture:
+ * - Uses @libsql/client for database operations
+ * - Supports embedded replicas (local SQLite) with remote sync
+ * - All read/write operations go through transactions
+ * - Implements the simple key-value interface expected by StoreFS
+ */
+declare class LibSQLStore implements Store {
+    readonly type = 1819505011;
+    readonly name = "libsqlfs";
+    readonly label?: string;
+    readonly uuid?: string;
+    readonly flags: readonly StoreFlag[];
+    private readonly client;
+    private readonly organizationId;
+    private readonly agentId;
+    private readonly maxSize;
+    private initialized;
+    private eventEmitter;
+    constructor(client: Client, options: LibSQLBackendOptions);
+    /**
+     * Initialize the database schema if needed
+     */
+    initialize(): Promise<void>;
+    /**
+     * Sync the embedded replica with the remote server
+     * For libSQL embedded replicas, this triggers a sync operation
+     */
+    sync(): Promise<void>;
+    /**
+     * Create a new transaction for atomic operations
+     *
+     * ZenFS StoreFS uses transactions for all operations:
+     * - tx.get(id, offset, end) - read data
+     * - tx.set(id, data, offset) - write data
+     * - tx.remove(id) - delete data
+     * - tx.commit() - persist changes
+     */
+    transaction(): LibSQLTransaction;
+    /**
+     * Handle events from committed transactions
+     */
+    private handleCommitEvents;
+    /**
+     * Subscribe to file change events
+     * @returns Unsubscribe function
+     */
+    onFileChange(callback: FSChangeCallback): () => void;
+    /**
+     * Get storage usage information
+     */
+    usage(): UsageInfo;
+    /**
+     * Get the libSQL client (for advanced operations)
+     */
+    getClient(): Client;
+    /**
+     * Get organization ID
+     */
+    getOrganizationId(): string;
+    /**
+     * Get agent ID
+     */
+    getAgentId(): string | null;
+    /**
+     * Check if a root directory exists
+     */
+    hasRoot(): Promise<boolean>;
+    /**
+     * Create root directory if it doesn't exist
+     * Called by StoreFS during initialization
+     */
+    ensureRoot(): Promise<void>;
+    /**
+     * Close the store and release resources
+     */
+    close(): Promise<void>;
+    /**
+     * Text search using FTS5 with fuzzy fallback
+     *
+     * Search strategy:
+     * 1. FTS5 MATCH for fast, indexed word matching
+     * 2. Fuzzy fallback (fuzzy_damlev) for typo tolerance if no results
+     *
+     * @param query - Search query string
+     * @param options - Search options
+     * @returns Array of search matches with line information
+     */
+    textSearch(query: string, options?: {
+        folders?: string[];
+        includes?: string[];
+        excludes?: string[];
+        caseSensitive?: boolean;
+        isRegex?: boolean;
+        resultLimit?: number;
+        fuzzyThreshold?: number;
+    }): Promise<{
+        matches: Array<{
+            path: string;
+            lineNumber: number;
+            lineContent: string;
+            matchStart: number;
+            matchEnd: number;
+        }>;
+        truncated: boolean;
+    }>;
+}
+
+declare const LibSQLFS_base: _zenfs_core.Mixin<typeof FileSystem, _zenfs_core.AsyncMixin>;
+/**
+ * LibSQLFS — ZenFS v2.4.4 FileSystem backed by libSQL path-based storage.
+ *
+ * Extends Async(FileSystem): only async methods implemented here.
+ * Async() provides all *Sync methods via _sync (InMemory instance).
+ * ready() triggers crossCopy which preloads libSQL data into _sync.
+ */
+declare class LibSQLFS extends LibSQLFS_base {
+    _sync: _zenfs_core.StoreFS<_zenfs_core.InMemoryStore>;
+    private client;
+    private organizationId;
+    private agentId;
+    readonly label?: string;
+    constructor(client: Client, options: LibSQLBackendOptions);
+    /**
+     * Initialize schema and seed root directory.
+     * Called before ready(), which triggers Async() crossCopy.
+     */
+    private initialize;
+    /**
+     * Override ready() to run initialize(), then let Async() crossCopy.
+     */
+    ready(): Promise<void>;
+    rename(oldPath: string, newPath: string): Promise<void>;
+    stat(path: string): Promise<InodeLike>;
+    touch(path: string, metadata: Partial<InodeLike>): Promise<void>;
+    createFile(path: string, options: CreationOptions): Promise<InodeLike>;
+    unlink(path: string): Promise<void>;
+    rmdir(path: string): Promise<void>;
+    mkdir(path: string, options: CreationOptions): Promise<InodeLike>;
+    readdir(path: string): Promise<string[]>;
+    link(_target: string, _link: string): Promise<void>;
+    sync(): Promise<void>;
+    read(path: string, buffer: Uint8Array, start: number, end: number): Promise<void>;
+    write(path: string, buffer: Uint8Array, offset: number): Promise<void>;
+}
+/**
+ * Backend interface compatible with ZenFS configure()
+ */
+interface Backend<FS = unknown, TOptions = object> {
+    name: string;
+    options: Record<string, {
+        type: string | readonly string[];
+        required: boolean;
+    }>;
+    create(options: TOptions): FS | Promise<FS>;
+    isAvailable?(config: TOptions): boolean | Promise<boolean>;
+}
+declare const LibSQLBackend: Backend<LibSQLFS, LibSQLBackendOptions>;
+declare function createLibSQLStore(options: LibSQLBackendOptions): Promise<LibSQLStore>;
+declare function forkTemplate(serverUrl: string, templateNamespace: string, targetNamespace: string, authToken?: string): Promise<boolean>;
+declare function namespaceExists(serverUrl: string, namespace: string, authToken?: string): Promise<boolean>;
+declare function createNamespace(serverUrl: string, namespace: string, authToken?: string): Promise<boolean>;
+
+export { AsyncTransactionBase, DEFAULT_DIR_MODE, DEFAULT_FILE_MODE, type FSChangeCallback, type FSChangeEvent, type FSChangeEventType, LibSQLBackend as LibSQL, LibSQLBackend, type LibSQLBackendOptions, LibSQLStore, LibSQLTransaction, createLibSQLStore, createNamespace, forkTemplate, isDirectory, isFile, namespaceExists, nowISO };