@happyvertical/files 0.74.8

package/AGENT.md

@@ -0,0 +1,33 @@
+# @happyvertical/files
+
+<!-- BEGIN AGENT:GENERATED -->
+## Purpose
+File system utilities for local and remote file operations
+
+## Package Map
+- Package: `@happyvertical/files`
+- Hierarchy path: `@happyvertical/sdk > packages > files`
+- Workspace position: `11 of 30` local packages
+- Internal dependencies: `@happyvertical/utils`
+- Internal dependents: `@happyvertical/documents`, `@happyvertical/sdk-mcp`
+- Knowledge graph files: `AGENT.md`, `metadata.json`, `ecosystem-manifest.json`
+
+## Build & Test
+```bash
+pnpm --filter @happyvertical/files build
+pnpm --filter @happyvertical/files test
+pnpm --filter @happyvertical/files clean
+```
+
+## Agent Correction Loops
+- If module resolution or export errors mention a workspace dependency, build the dependency first (`pnpm --filter @happyvertical/utils build`) and then rerun `pnpm --filter @happyvertical/files build`.
+- If tests or exports fail after API, type, or bundle changes, run `pnpm --filter @happyvertical/files clean` followed by `pnpm --filter @happyvertical/files build` and `pnpm --filter @happyvertical/files test`.
+- If failures span multiple packages or Turborepo ordering looks wrong, run `pnpm build` and `pnpm typecheck` from the repo root before retrying package-scoped commands.
+
+## Ecosystem Relationships
+- Provides: File system utilities for local and remote file operations
+- Implements: none
+- Requires: @happyvertical/utils, @aws-sdk/client-s3, google-auth-library, googleapis
+- Stability: stable (Primary package surface is described as implemented and production-oriented.)
+<!-- END AGENT:GENERATED -->
+

package/LICENSE

@@ -0,0 +1,7 @@
+Copyright <2025> <Happy Vertical Corporation>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,136 @@
+# @happyvertical/files
+
+Unified filesystem interface for the HAVE SDK. Provides a consistent API across local filesystem (Node.js `fs/promises`) and Google Drive, with rate-limited fetch utilities and legacy compatibility helpers.
+
+## Installation
+
+```bash
+pnpm add @happyvertical/files
+```
+
+> Published to public npm. Depends on `@happyvertical/utils`.
+
+## Usage
+
+### Factory Function
+
+```typescript
+import { getFilesystem } from '@happyvertical/files';
+
+// Local filesystem (default)
+const fs = await getFilesystem({ type: 'local', basePath: '/app/data' });
+
+await fs.write('output/result.txt', 'Hello, world!');
+const content = await fs.read('config.json');
+const exists = await fs.exists('config.json');
+
+// List files with filtering
+const files = await fs.list('.', { filter: /\.json$/, detailed: true });
+for (const file of files) {
+  console.log(`${file.name}: ${file.size} bytes, ${file.mimeType}`);
+}
+```
+
+### Google Drive
+
+```typescript
+import { getFilesystem } from '@happyvertical/files';
+
+const fs = await getFilesystem({
+  type: 'gdrive',
+  clientId: 'xxx',
+  clientSecret: 'yyy',
+  refreshToken: 'zzz',
+});
+
+await fs.write('documents/readme.txt', 'Hello from Drive');
+const content = await fs.read('documents/readme.txt');
+```
+
+Supports OAuth2, service account keys, and short-lived access tokens. Google Docs native formats are automatically exported (Docs → text, Sheets → CSV, etc.).
+
+### File Operations
+
+```typescript
+await fs.copy('source.txt', 'backup/source-copy.txt');
+await fs.move('temp.txt', 'archive/temp.txt');
+await fs.createDirectory('secure-data', { mode: 0o700 });
+await fs.delete('temporary-file.txt');
+
+const stats = await fs.getStats('document.pdf');
+console.log(`${stats.size} bytes, modified ${stats.mtime}`);
+```
+
+### Fetch Utilities
+
+Rate-limited HTTP fetch helpers for downloading remote content:
+
+```typescript
+import { fetchText, fetchJSON, fetchBuffer, fetchToFile, addRateLimit } from '@happyvertical/files';
+
+// Set per-domain rate limits
+addRateLimit('api.github.com', 30, 60000);
+
+const html = await fetchText('https://example.com');
+const data = await fetchJSON('https://api.example.com/data');
+const buf = await fetchBuffer('https://example.com/image.png');
+await fetchToFile('https://example.com/file.zip', './downloads/file.zip');
+```
+
+### Error Handling
+
+```typescript
+import { FileNotFoundError, PermissionError, DirectoryNotEmptyError } from '@happyvertical/files';
+
+try {
+  await fs.read('missing.txt');
+} catch (error) {
+  if (error instanceof FileNotFoundError) {
+    console.error('Not found:', error.path);
+  } else if (error instanceof PermissionError) {
+    console.error('Permission denied:', error.path);
+  }
+}
+```
+
+### Legacy Functions
+
+Standalone functions from the original API, still exported for backward compatibility:
+
+```typescript
+import { isFile, isDirectory, ensureDirectoryExists, download, listFiles } from '@happyvertical/files';
+
+const fileStats = isFile('/path/to/file.txt'); // synchronous
+const isDir = isDirectory('/path/to/dir');     // synchronous
+await ensureDirectoryExists('/path/to/new/dir');
+await download('https://example.com/file.pdf', './file.pdf');
+const files = await listFiles('/path/to/dir', { match: /\.json$/ });
+```
+
+## Providers
+
+| Provider | Status | Options |
+|----------|--------|---------|
+| Local | Implemented | `basePath?` |
+| Google Drive | Implemented | `clientId`, `clientSecret`, `refreshToken` (or `serviceAccountKey` / `accessToken`) |
+| S3 | Types only | `region`, `bucket`, `accessKeyId?`, `secretAccessKey?` |
+| WebDAV | Types only | `baseUrl`, `username`, `password` |
+
+## API Overview
+
+**Factory**: `getFilesystem(options)`, `registerProvider(type, factory)`, `getAvailableProviders()`, `isProviderAvailable(type)`, `getProviderInfo(type)`
+
+**Provider classes**: `LocalFilesystemProvider`, `GoogleDriveProvider`
+
+**Interface methods**: `exists`, `read`, `write`, `delete`, `copy`, `move`, `createDirectory`, `list`, `getStats`, `getMimeType`, `upload`, `download`, `downloadWithCache`, `cache.get/set/clear`, `getCapabilities`
+
+**Fetch**: `fetchText`, `fetchJSON`, `fetchBuffer`, `fetchToFile`, `addRateLimit`, `getRateLimit`
+
+**Errors**: `FilesystemError`, `FileNotFoundError`, `PermissionError`, `DirectoryNotEmptyError`, `InvalidPathError`
+
+**Legacy**: `isFile`, `isDirectory`, `ensureDirectoryExists`, `download`, `upload`, `downloadFileWithCache`, `listFiles`, `getCached`, `setCached`, `getMimeType`
+
+## Dependencies
+
+- `@happyvertical/utils` — temp directory management
+- `googleapis` / `google-auth-library` — Google Drive provider

package/dist/cli/claude-context.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=claude-context.d.ts.map

package/dist/cli/claude-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"claude-context.d.ts","sourceRoot":"","sources":["../../src/cli/claude-context.ts"],"names":[],"mappings":""}

package/dist/cli/claude-context.js

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+import { existsSync, mkdirSync, copyFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+const Dirname = dirname(fileURLToPath(import.meta.url));
+const pkgRoot = join(Dirname, "../..");
+const targetDir = join(process.cwd(), ".claude");
+if (!existsSync(targetDir)) {
+  mkdirSync(targetDir, { recursive: true });
+}
+const pkgName = "files";
+const agentMdSrc = existsSync(join(pkgRoot, "AGENT.md")) ? join(pkgRoot, "AGENT.md") : join(pkgRoot, "CLAUDE.md");
+const metaSrc = existsSync(join(pkgRoot, "metadata.json")) ? join(pkgRoot, "metadata.json") : join(pkgRoot, ".claude-meta.json");
+if (existsSync(agentMdSrc)) {
+  copyFileSync(agentMdSrc, join(targetDir, `have-${pkgName}.md`));
+}
+if (existsSync(metaSrc)) {
+  copyFileSync(metaSrc, join(targetDir, `have-${pkgName}.meta.json`));
+}
+console.log(`✓ Installed @happyvertical/${pkgName} context to .claude/`);
+//# sourceMappingURL=claude-context.js.map

package/dist/cli/claude-context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"claude-context.js","sources":["../../src/cli/claude-context.ts"],"sourcesContent":["#!/usr/bin/env node\n/**\n * CLI script to install agent context for @happyvertical/files\n * Run the published context installer binary for this package.\n */\nimport { copyFileSync, existsSync, mkdirSync } from 'node:fs';\nimport { dirname, join } from 'node:path';\nimport { fileURLToPath } from 'node:url';\n\nconst Dirname = dirname(fileURLToPath(import.meta.url));\nconst pkgRoot = join(Dirname, '../..');\nconst targetDir = join(process.cwd(), '.claude');\n\nif (!existsSync(targetDir)) {\n  mkdirSync(targetDir, { recursive: true });\n}\n\nconst pkgName = 'files';\nconst agentMdSrc = existsSync(join(pkgRoot, 'AGENT.md'))\n  ? join(pkgRoot, 'AGENT.md')\n  : join(pkgRoot, 'CLAUDE.md');\nconst metaSrc = existsSync(join(pkgRoot, 'metadata.json'))\n  ? join(pkgRoot, 'metadata.json')\n  : join(pkgRoot, '.claude-meta.json');\n\nif (existsSync(agentMdSrc)) {\n  copyFileSync(agentMdSrc, join(targetDir, `have-${pkgName}.md`));\n}\n\nif (existsSync(metaSrc)) {\n  copyFileSync(metaSrc, join(targetDir, `have-${pkgName}.meta.json`));\n}\n\nconsole.log(`✓ Installed @happyvertical/${pkgName} context to .claude/`);\n"],"names":[],"mappings":";;;;AASA,MAAM,UAAU,QAAQ,cAAc,YAAY,GAAG,CAAC;AACtD,MAAM,UAAU,KAAK,SAAS,OAAO;AACrC,MAAM,YAAY,KAAK,QAAQ,IAAA,GAAO,SAAS;AAE/C,IAAI,CAAC,WAAW,SAAS,GAAG;AAC1B,YAAU,WAAW,EAAE,WAAW,KAAA,CAAM;AAC1C;AAEA,MAAM,UAAU;AAChB,MAAM,aAAa,WAAW,KAAK,SAAS,UAAU,CAAC,IACnD,KAAK,SAAS,UAAU,IACxB,KAAK,SAAS,WAAW;AAC7B,MAAM,UAAU,WAAW,KAAK,SAAS,eAAe,CAAC,IACrD,KAAK,SAAS,eAAe,IAC7B,KAAK,SAAS,mBAAmB;AAErC,IAAI,WAAW,UAAU,GAAG;AAC1B,eAAa,YAAY,KAAK,WAAW,QAAQ,OAAO,KAAK,CAAC;AAChE;AAEA,IAAI,WAAW,OAAO,GAAG;AACvB,eAAa,SAAS,KAAK,WAAW,QAAQ,OAAO,YAAY,CAAC;AACpE;AAEA,QAAQ,IAAI,8BAA8B,OAAO,sBAAsB;"}

package/dist/factory.d.ts

@@ -0,0 +1,30 @@
+import { FilesystemInterface, GetFilesystemOptions } from './shared/types';
+/**
+ * Register a filesystem provider
+ */
+export declare function registerProvider(type: string, factory: () => Promise<any>): void;
+/**
+ * Get list of available provider types
+ */
+export declare function getAvailableProviders(): string[];
+/**
+ * Main factory function to create filesystem instances
+ */
+export declare function getFilesystem(options?: GetFilesystemOptions): Promise<FilesystemInterface>;
+/**
+ * Initialize providers by registering them
+ */
+export declare function initializeProviders(): Promise<void>;
+/**
+ * Check if a provider is available
+ */
+export declare function isProviderAvailable(type: string): boolean;
+/**
+ * Get provider information
+ */
+export declare function getProviderInfo(type: string): {
+    available: boolean;
+    description: string;
+    requiredOptions: string[];
+};
+//# sourceMappingURL=factory.d.ts.map

package/dist/factory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"factory.d.ts","sourceRoot":"","sources":["../src/factory.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,mBAAmB,EACxB,KAAK,oBAAoB,EAI1B,MAAM,gBAAgB,CAAC;AAOxB;;GAEG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,OAAO,CAAC,GAAG,CAAC,GAC1B,IAAI,CAEN;AAED;;GAEG;AACH,wBAAgB,qBAAqB,IAAI,MAAM,EAAE,CAEhD;AAoGD;;GAEG;AACH,wBAAsB,aAAa,CACjC,OAAO,GAAE,oBAAyB,GACjC,OAAO,CAAC,mBAAmB,CAAC,CA4B9B;AAED;;GAEG;AACH,wBAAsB,mBAAmB,IAAI,OAAO,CAAC,IAAI,CAAC,CAgBzD;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEzD;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG;IAC7C,SAAS,EAAE,OAAO,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,eAAe,EAAE,MAAM,EAAE,CAAC;CAC3B,CAuBA"}

package/dist/fetch.d.ts

@@ -0,0 +1,142 @@
+export interface FetchToFileOptions extends RequestInit {
+    /** Optional timeout in milliseconds */
+    timeout?: number;
+    /** Optional transport ceiling in bytes */
+    maxBytes?: number;
+}
+export interface WriteResponseToFileOptions {
+    /** Optional transport ceiling in bytes */
+    maxBytes?: number;
+}
+/**
+ * Sets rate limit configuration for a specific domain
+ *
+ * Configures custom rate limiting for a specific domain. This allows you to
+ * set different limits for different services based on their API requirements.
+ *
+ * @param domain - Domain to set limits for (e.g., 'api.github.com')
+ * @param limit - Maximum number of requests per interval
+ * @param interval - Interval in milliseconds (time window for the limit)
+ *
+ * @example
+ * ```typescript
+ * // Set GitHub API to 30 requests per minute
+ * await addRateLimit('api.github.com', 30, 60000);
+ *
+ * // Set custom API to 10 requests per 5 seconds
+ * await addRateLimit('my-api.example.com', 10, 5000);
+ * ```
+ */
+export declare function addRateLimit(domain: string, limit: number, interval: number): Promise<void>;
+/**
+ * Gets rate limit configuration for a specific domain
+ *
+ * Retrieves the current rate limiting configuration for a domain.
+ * If no specific configuration exists, returns the default configuration.
+ *
+ * @param domain - Domain to get limits for
+ * @returns Promise resolving to rate limit configuration with limit and interval properties
+ *
+ * @example
+ * ```typescript
+ * const config = await getRateLimit('api.github.com');
+ * console.log(`GitHub API: ${config.limit} requests per ${config.interval}ms`);
+ * ```
+ */
+export declare function getRateLimit(domain: string): Promise<{
+    limit: number;
+    interval: number;
+}>;
+/**
+ * Fetches a URL and returns the response as text with automatic rate limiting
+ *
+ * Convenience function that performs a rate-limited fetch and returns the
+ * response body as a text string. Ideal for fetching HTML, CSS, plain text,
+ * or other text-based content.
+ *
+ * @param url - URL to fetch
+ * @returns Promise resolving to the response body as a string
+ * @throws {Error} If the fetch fails or response is not ok
+ *
+ * @example
+ * ```typescript
+ * const html = await fetchText('https://example.com');
+ * console.log('Page content:', html);
+ *
+ * const readme = await fetchText('https://raw.githubusercontent.com/user/repo/main/README.md');
+ * ```
+ */
+export declare function fetchText(url: string): Promise<string>;
+/**
+ * Fetches a URL and returns the response as parsed JSON with automatic rate limiting
+ *
+ * Convenience function that performs a rate-limited fetch and parses the
+ * response body as JSON. Perfect for consuming REST APIs and JSON endpoints.
+ *
+ * @param url - URL to fetch
+ * @returns Promise resolving to the parsed JSON response (any type)
+ * @throws {Error} If the fetch fails, response is not ok, or JSON parsing fails
+ *
+ * @example
+ * ```typescript
+ * const data = await fetchJSON('https://api.github.com/user');
+ * console.log('User data:', data);
+ *
+ * const config = await fetchJSON('https://example.com/api/config');
+ * ```
+ */
+export declare function fetchJSON(url: string): Promise<any>;
+/**
+ * Fetches a URL and returns the response as a Buffer with automatic rate limiting
+ *
+ * Convenience function that performs a rate-limited fetch and returns the
+ * response body as a Buffer. Ideal for fetching binary data like images,
+ * documents, or other non-text content.
+ *
+ * @param url - URL to fetch
+ * @returns Promise resolving to the response body as a Buffer
+ * @throws {Error} If the fetch fails or response is not ok
+ *
+ * @example
+ * ```typescript
+ * const imageBuffer = await fetchBuffer('https://example.com/image.png');
+ * await fs.writeFile('downloaded-image.png', imageBuffer);
+ *
+ * const pdfBuffer = await fetchBuffer('https://example.com/document.pdf');
+ * ```
+ */
+export declare function fetchBuffer(url: string): Promise<Buffer>;
+/**
+ * Fetches a URL and saves the response directly to a file with automatic rate limiting
+ *
+ * Convenience function that performs a rate-limited fetch and writes the
+ * response body directly to a local file. Efficient for downloading files
+ * without loading the entire content into memory.
+ *
+ * @param url - URL to fetch
+ * @param filepath - Local file path where the content should be saved
+ * @returns Promise that resolves when the file is saved successfully
+ * @throws {Error} If the fetch fails, response is not ok, or file write fails
+ *
+ * @example
+ * ```typescript
+ * await fetchToFile('https://example.com/large-file.zip', './downloads/file.zip');
+ * console.log('File downloaded successfully');
+ *
+ * await fetchToFile('https://api.example.com/report.pdf', './reports/daily.pdf');
+ * ```
+ */
+export declare function fetchToFile(url: string, filepath: string, options?: FetchToFileOptions): Promise<void>;
+/**
+ * Streams an existing fetch `Response` to disk.
+ *
+ * The response body is written to a temp file in the destination directory,
+ * optional `maxBytes` enforcement is applied while streaming, existing file
+ * permissions/ownership are preserved when possible, and the temp file is then
+ * atomically renamed into place on success.
+ *
+ * This helper is transport-only: callers are responsible for validating
+ * `response.ok`, headers, and content before persisting it.
+ */
+export declare function writeResponseToFile(response: Response, filepath: string, options?: WriteResponseToFileOptions): Promise<void>;
+//# sourceMappingURL=fetch.d.ts.map

package/dist/fetch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fetch.d.ts","sourceRoot":"","sources":["../src/fetch.ts"],"names":[],"mappings":"AAiBA,MAAM,WAAW,kBAAmB,SAAQ,WAAW;IACrD,uCAAuC;IACvC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,0CAA0C;IAC1C,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,0BAA0B;IACzC,0CAA0C;IAC1C,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AA8ND;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,YAAY,CAChC,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,MAAM,iBAGjB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,YAAY,CAChC,MAAM,EAAE,MAAM,GACb,OAAO,CAAC;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,CAM9C;AA+CD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAI5D;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,CAIzD;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAI9D;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,WAAW,CAC/B,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,kBAAuB,GAC/B,OAAO,CAAC,IAAI,CAAC,CAWf;AAmDD;;;;;;;;;;GAUG;AACH,wBAAsB,mBAAmB,CACvC,QAAQ,EAAE,QAAQ,EAClB,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,0BAA+B,GACvC,OAAO,CAAC,IAAI,CAAC,CAGf"}

package/dist/filesystem-local.d.ts

@@ -0,0 +1,82 @@
+import { FilesystemAdapter, FilesystemAdapterOptions } from './filesystem';
+/**
+ * Adapter for interacting with the local filesystem
+ */
+export declare class LocalFilesystemAdapter extends FilesystemAdapter {
+    /**
+     * Cache directory path
+     */
+    protected cacheDir: string;
+    /**
+     * Type identifier for this adapter
+     */
+    type: string;
+    /**
+     * Configuration options
+     */
+    protected options: FilesystemAdapterOptions;
+    /**
+     * Creates a new LocalFilesystemAdapter instance
+     *
+     * @param options - Configuration options
+     */
+    constructor(options: FilesystemAdapterOptions);
+    /**
+     * Creates a LocalFilesystemAdapter from a URL
+     *
+     * @param url - URL to create adapter from
+     * @returns Promise resolving to a LocalFilesystemAdapter
+     */
+    static createFromUrl(_url: string): Promise<void>;
+    /**
+     * Factory method to create a LocalFilesystemAdapter
+     *
+     * @param options - Configuration options
+     * @returns Promise resolving to an initialized LocalFilesystemAdapter
+     */
+    static create(options: FilesystemAdapterOptions): Promise<LocalFilesystemAdapter>;
+    /**
+     * Checks if a file or directory exists in the local filesystem
+     *
+     * @param path - Path to check
+     * @returns Promise resolving to boolean indicating existence
+     */
+    exists(_path: string): Promise<boolean>;
+    /**
+     * Reads a file's contents from the local filesystem
+     *
+     * @param path - Path to the file
+     * @returns Promise resolving to the file contents as a string
+     */
+    read(_path: string): Promise<string>;
+    /**
+     * Writes content to a file in the local filesystem
+     *
+     * @param path - Path to the file
+     * @param content - Content to write
+     * @returns Promise that resolves when the write is complete
+     */
+    write(_path: string, _content: string): Promise<void>;
+    /**
+     * Deletes a file or directory from the local filesystem
+     *
+     * @param path - Path to delete
+     * @returns Promise that resolves when the deletion is complete
+     */
+    delete(_path: string): Promise<void>;
+    /**
+     * Lists files in a directory in the local filesystem
+     *
+     * @param path - Directory path to list
+     * @returns Promise resolving to an array of file names
+     */
+    list(_path: string): Promise<never[]>;
+    /**
+     * Gets the MIME type for a file based on its extension
+     *
+     * @param path - Path to the file
+     * @returns Promise resolving to the MIME type string
+     */
+    mimeType(path: string): Promise<string>;
+}
+//# sourceMappingURL=filesystem-local.d.ts.map

package/dist/filesystem-local.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"filesystem-local.d.ts","sourceRoot":"","sources":["../src/filesystem-local.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,KAAK,wBAAwB,EAAE,MAAM,cAAc,CAAC;AAGhF;;GAEG;AACH,qBAAa,sBAAuB,SAAQ,iBAAiB;IAC3D;;OAEG;IACH,SAAS,CAAC,QAAQ,EAAE,MAAM,CAAC;IAE3B;;OAEG;IACI,IAAI,EAAE,MAAM,CAAC;IAEpB;;OAEG;IACH,SAAS,CAAC,OAAO,EAAE,wBAAwB,CAAC;IAE5C;;;;OAIG;gBACS,OAAO,EAAE,wBAAwB;IAO7C;;;;;OAKG;WACU,aAAa,CAAC,IAAI,EAAE,MAAM;IAEvC;;;;;OAKG;WACU,MAAM,CAAC,OAAO,EAAE,wBAAwB;IAKrD;;;;;OAKG;IACG,MAAM,CAAC,KAAK,EAAE,MAAM;IAI1B;;;;;OAKG;IACG,IAAI,CAAC,KAAK,EAAE,MAAM;IAIxB;;;;;;OAMG;IACG,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM;IAI3C;;;;;OAKG;IACG,MAAM,CAAC,KAAK,EAAE,MAAM;IAI1B;;;;;OAKG;IACG,IAAI,CAAC,KAAK,EAAE,MAAM;IAIxB;;;;;OAKG;IACG,QAAQ,CAAC,IAAI,EAAE,MAAM;CAI5B"}

package/dist/filesystem.d.ts

@@ -0,0 +1,155 @@
+/**
+ * Interface defining the required methods for a filesystem adapter
+ */
+export interface FilesystemAdapterInterface {
+    /**
+     * Checks if a file or directory exists
+     *
+     * @param path - Path to check
+     * @returns Promise resolving to boolean indicating existence
+     */
+    exists(path: string): Promise<boolean>;
+    /**
+     * Reads a file's contents
+     *
+     * @param path - Path to the file
+     * @returns Promise resolving to the file contents as a string
+     */
+    read(path: string): Promise<string>;
+    /**
+     * Writes content to a file
+     *
+     * @param path - Path to the file
+     * @param content - Content to write
+     * @returns Promise that resolves when the write is complete
+     */
+    write(path: string, content: string): Promise<void>;
+    /**
+     * Deletes a file or directory
+     *
+     * @param path - Path to delete
+     * @returns Promise that resolves when the deletion is complete
+     */
+    delete(path: string): Promise<void>;
+    /**
+     * Lists files in a directory
+     *
+     * @param path - Directory path to list
+     * @returns Promise resolving to an array of file names
+     */
+    list(path: string): Promise<string[]>;
+    /**
+     * Gets the MIME type for a file
+     *
+     * @param path - Path to the file
+     * @returns Promise resolving to the MIME type string
+     */
+    mimeType(path: string): Promise<string>;
+}
+/**
+ * Configuration options for filesystem adapters
+ */
+export interface FilesystemAdapterOptions {
+    /**
+     * Type of filesystem adapter
+     */
+    type?: string;
+    /**
+     * Directory to use for caching
+     */
+    cacheDir?: string;
+}
+/**
+ * Base class for filesystem adapters providing common functionality
+ */
+export declare class FilesystemAdapter {
+    /**
+     * Configuration options
+     */
+    protected options: FilesystemAdapterOptions;
+    /**
+     * Cache directory path
+     */
+    protected cacheDir: string;
+    /**
+     * Creates a new FilesystemAdapter instance
+     *
+     * @param options - Configuration options
+     */
+    constructor(options: FilesystemAdapterOptions);
+    /**
+     * Factory method to create and initialize a FilesystemAdapter
+     *
+     * @param options - Configuration options
+     * @returns Promise resolving to an initialized FilesystemAdapter
+     */
+    static create<T extends FilesystemAdapterOptions>(options: T): Promise<FilesystemAdapter>;
+    /**
+     * Initializes the adapter by creating the cache directory
+     */
+    protected initialize(): Promise<void>;
+    /**
+     * Downloads a file from a URL
+     *
+     * @param url - URL to download from
+     * @param options - Download options
+     * @param options.force - Whether to force download even if cached
+     * @returns Promise resolving to the path of the downloaded file
+     */
+    download(_url: string, _options?: {
+        force: boolean;
+    }): Promise<string>;
+    /**
+     * Checks if a file or directory exists
+     *
+     * @param path - Path to check
+     * @returns Promise resolving to boolean indicating existence
+     */
+    exists(_path: string): Promise<boolean>;
+    /**
+     * Reads a file's contents
+     *
+     * @param path - Path to the file
+     * @returns Promise resolving to the file contents as a string
+     */
+    read(_path: string): Promise<string>;
+    /**
+     * Writes content to a file
+     *
+     * @param path - Path to the file
+     * @param content - Content to write
+     * @returns Promise that resolves when the write is complete
+     */
+    write(_path: string, _content: string): Promise<void>;
+    /**
+     * Deletes a file or directory
+     *
+     * @param path - Path to delete
+     * @returns Promise that resolves when the deletion is complete
+     */
+    delete(_path: string): Promise<void>;
+    /**
+     * Lists files in a directory
+     *
+     * @param path - Directory path to list
+     * @returns Promise resolving to an array of file names
+     */
+    list(_path: string): Promise<string[]>;
+    /**
+     * Gets data from cache if available and not expired
+     *
+     * @param file - Cache file identifier
+     * @param expiry - Cache expiry time in milliseconds
+     * @returns Promise resolving to the cached data or undefined if not found/expired
+     */
+    getCached(file: string, expiry?: number): Promise<string | undefined>;
+    /**
+     * Sets data in cache
+     *
+     * @param file - Cache file identifier
+     * @param data - Data to cache
+     * @returns Promise that resolves when the data is cached
+     */
+    setCached(file: string, data: string): Promise<void>;
+}
+//# sourceMappingURL=filesystem.d.ts.map

package/dist/filesystem.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"filesystem.d.ts","sourceRoot":"","sources":["../src/filesystem.ts"],"names":[],"mappings":"AAIA;;GAEG;AACH,MAAM,WAAW,0BAA0B;IACzC;;;;;OAKG;IACH,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAEvC;;;;;OAKG;IACH,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAEpC;;;;;;OAMG;IACH,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEpD;;;;;OAKG;IACH,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEpC;;;;;OAKG;IACH,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IAEtC;;;;;OAKG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CACzC;AAED;;GAEG;AACH,MAAM,WAAW,wBAAwB;IACvC;;OAEG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,qBAAa,iBAAiB;IAC5B;;OAEG;IACH,SAAS,CAAC,OAAO,EAAE,wBAAwB,CAAC;IAE5C;;OAEG;IACH,SAAS,CAAC,QAAQ,EAAE,MAAM,CAAC;IAE3B;;;;OAIG;gBACS,OAAO,EAAE,wBAAwB;IAK7C;;;;;OAKG;WACU,MAAM,CAAC,CAAC,SAAS,wBAAwB,EACpD,OAAO,EAAE,CAAC,GACT,OAAO,CAAC,iBAAiB,CAAC;IAM7B;;OAEG;cACa,UAAU;IAI1B;;;;;;;OAOG;IACG,QAAQ,CACZ,IAAI,EAAE,MAAM,EACZ,QAAQ,GAAE;QACR,KAAK,EAAE,OAAO,CAAC;KAGhB,GACA,OAAO,CAAC,MAAM,CAAC;IAIlB;;;;;OAKG;IACG,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAK7C;;;;;OAKG;IACG,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAK1C;;;;;;OAMG;IACG,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAI3D;;;;;OAKG;IACG,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAI1C;;;;;OAKG;IACG,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAK5C;;;;;;OAMG;IACG,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,SAAS;IAI7C;;;;;;OAMG;IACG,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM;CAG3C"}