@happyvertical/files 0.74.8

package/dist/index.js

@@ -0,0 +1,2719 @@
+import { randomUUID } from "node:crypto";
+import { createWriteStream, existsSync, statSync, constants } from "node:fs";
+import { rename, rm, lstat, realpath, writeFile, stat, chmod, chown, mkdir, readFile, readdir, access, rmdir, unlink, copyFile } from "node:fs/promises";
+import * as path from "node:path";
+import { join, dirname, basename, resolve, isAbsolute, relative, sep, extname } from "node:path";
+import { Readable, Transform } from "node:stream";
+import { pipeline } from "node:stream/promises";
+import { getTempDirectory } from "@happyvertical/utils";
+import { URL as URL$1 } from "node:url";
+import { S3Client, ListObjectsV2Command, HeadObjectCommand, GetObjectCommand, PutObjectCommand, DeleteObjectCommand, CopyObjectCommand } from "@aws-sdk/client-s3";
+function createTempFilePath(filepath) {
+  return join(
+    dirname(filepath),
+    `.${basename(filepath)}.${randomUUID()}.download`
+  );
+}
+function isErrnoException(error) {
+  return error instanceof Error && "code" in error;
+}
+async function resolveDestinationPath(filepath) {
+  try {
+    const destinationStats = await lstat(filepath);
+    if (!destinationStats.isSymbolicLink()) {
+      return filepath;
+    }
+    return await realpath(filepath);
+  } catch (error) {
+    if (isErrnoException(error) && error.code === "ENOENT") {
+      return filepath;
+    }
+    throw error;
+  }
+}
+async function preserveExistingDestinationMetadata(sourcePath, tempFilepath) {
+  try {
+    const sourceStats = await stat(sourcePath);
+    await chmod(tempFilepath, sourceStats.mode);
+    try {
+      await chown(tempFilepath, sourceStats.uid, sourceStats.gid);
+    } catch (error) {
+      if (!isErrnoException(error) || !["EPERM", "EINVAL", "ENOSYS", "EROFS"].includes(error.code ?? "")) {
+        throw error;
+      }
+    }
+  } catch (error) {
+    if (!(isErrnoException(error) && error.code === "ENOENT")) {
+      throw error;
+    }
+  }
+}
+class MaxBytesTransform extends Transform {
+  constructor(maxBytes) {
+    super();
+    this.maxBytes = maxBytes;
+  }
+  totalBytes = 0;
+  _transform(chunk, _encoding, callback) {
+    this.totalBytes += chunk.byteLength;
+    if (this.totalBytes > this.maxBytes) {
+      callback(
+        new Error(
+          `Downloaded content exceeded maxBytes (${this.totalBytes} > ${this.maxBytes})`
+        )
+      );
+      return;
+    }
+    callback(null, chunk);
+  }
+}
+class RateLimiter {
+  /**
+   * Map of domains to their rate limit configurations
+   * Each domain tracks: lastRequest time, request limit, interval, and current queue size
+   */
+  domains = /* @__PURE__ */ new Map();
+  /**
+   * Default maximum number of requests per interval
+   * Applied to domains that don't have specific limits configured
+   */
+  defaultLimit = 6;
+  /**
+   * Default interval in milliseconds (500ms)
+   * Time window for the request limit enforcement
+   */
+  defaultInterval = 500;
+  getDefaultDomainConfig() {
+    const config = this.domains.get("default");
+    if (!config) {
+      throw new Error("Default domain rate limit configuration is missing");
+    }
+    return config;
+  }
+  /**
+   * Creates a new RateLimiter with default settings
+   * Initializes with a 'default' domain configuration used as fallback
+   */
+  constructor() {
+    this.domains.set("default", {
+      lastRequest: 0,
+      limit: this.defaultLimit,
+      interval: this.defaultInterval,
+      queue: 0
+    });
+  }
+  /**
+   * Extracts the domain from a URL for rate limiting purposes
+   *
+   * @param url - URL to extract domain from
+   * @returns Domain string (hostname) or 'default' if the URL is invalid
+   *
+   * @internal
+   */
+  getDomain(url) {
+    try {
+      return new URL(url).hostname;
+    } catch {
+      return "default";
+    }
+  }
+  /**
+   * Waits until the next request can be made according to rate limits
+   *
+   * This method implements the core rate limiting logic. It checks if the
+   * current request would exceed the domain's rate limit and delays if necessary.
+   *
+   * @param url - URL to check rate limits for (domain extracted automatically)
+   * @returns Promise that resolves when the request can proceed safely
+   *
+   * @internal
+   */
+  async waitForNext(url) {
+    const domain = this.getDomain(url);
+    const now = Date.now();
+    const domainConfig = this.domains.get(domain) || this.getDefaultDomainConfig();
+    if (domainConfig.queue >= domainConfig.limit) {
+      const timeToWait = Math.max(
+        0,
+        domainConfig.lastRequest + domainConfig.interval - now
+      );
+      if (timeToWait > 0) {
+        await new Promise((resolve2) => setTimeout(resolve2, timeToWait));
+      }
+      domainConfig.queue = 0;
+    }
+    domainConfig.lastRequest = now;
+    domainConfig.queue++;
+  }
+  /**
+   * Sets rate limit for a specific domain
+   *
+   * @param domain - Domain to set limits for
+   * @param limit - Maximum number of requests per interval
+   * @param interval - Interval in milliseconds
+   */
+  setDomainLimit(domain, limit, interval) {
+    this.domains.set(domain, {
+      lastRequest: 0,
+      limit,
+      interval,
+      queue: 0
+    });
+  }
+  /**
+   * Gets rate limit configuration for a domain
+   *
+   * @param domain - Domain to get limits for
+   * @returns Rate limit configuration
+   */
+  getDomainLimit(domain) {
+    return this.domains.get(domain) || this.getDefaultDomainConfig();
+  }
+}
+const rateLimiter = new RateLimiter();
+async function addRateLimit(domain, limit, interval) {
+  rateLimiter.setDomainLimit(domain, limit, interval);
+}
+async function getRateLimit(domain) {
+  const config = rateLimiter.getDomainLimit(domain);
+  return {
+    limit: config.limit,
+    interval: config.interval
+  };
+}
+async function rateLimitedFetch(url, options) {
+  await rateLimiter.waitForNext(url);
+  return fetch(url, options);
+}
+function buildFetchSignal(timeout, signal) {
+  if (timeout == null) {
+    return signal ?? void 0;
+  }
+  const timeoutSignal = AbortSignal.timeout(timeout);
+  if (!signal) {
+    return timeoutSignal;
+  }
+  return AbortSignal.any([signal, timeoutSignal]);
+}
+function assertOkResponse(response, url) {
+  if (!response.ok) {
+    throw new Error(
+      `Failed to fetch ${url}: ${response.status} ${response.statusText}`
+    );
+  }
+}
+async function fetchText(url) {
+  const response = await rateLimitedFetch(url);
+  assertOkResponse(response, url);
+  return response.text();
+}
+async function fetchJSON(url) {
+  const response = await rateLimitedFetch(url);
+  assertOkResponse(response, url);
+  return response.json();
+}
+async function fetchBuffer(url) {
+  const response = await rateLimitedFetch(url);
+  assertOkResponse(response, url);
+  return Buffer.from(await response.arrayBuffer());
+}
+async function fetchToFile(url, filepath, options = {}) {
+  const { timeout, maxBytes, signal, ...requestInit } = options;
+  const destinationPath = await resolveDestinationPath(filepath);
+  const response = await rateLimitedFetch(url, {
+    ...requestInit,
+    signal: buildFetchSignal(timeout, signal)
+  });
+  assertOkResponse(response, url);
+  await writeResponseToResolvedPath(response, destinationPath, { maxBytes });
+}
+async function writeResponseBodyToTempFile(response, tempFilepath, options = {}) {
+  const { maxBytes } = options;
+  if (!response.body) {
+    const buffer = Buffer.from(await response.arrayBuffer());
+    if (maxBytes != null && buffer.byteLength > maxBytes) {
+      throw new Error(
+        `Downloaded content exceeded maxBytes (${buffer.byteLength} > ${maxBytes})`
+      );
+    }
+    await writeFile(tempFilepath, buffer);
+    return;
+  }
+  const source = Readable.fromWeb(
+    response.body
+  );
+  const destination = createWriteStream(tempFilepath);
+  if (maxBytes != null) {
+    await pipeline(source, new MaxBytesTransform(maxBytes), destination);
+  } else {
+    await pipeline(source, destination);
+  }
+}
+async function writeResponseToResolvedPath(response, destinationPath, options = {}) {
+  const tempFilepath = createTempFilePath(destinationPath);
+  try {
+    await writeResponseBodyToTempFile(response, tempFilepath, options);
+    await preserveExistingDestinationMetadata(destinationPath, tempFilepath);
+    await rename(tempFilepath, destinationPath);
+  } catch (error) {
+    await rm(tempFilepath, { force: true }).catch(() => {
+    });
+    throw error;
+  }
+}
+async function writeResponseToFile(response, filepath, options = {}) {
+  const destinationPath = await resolveDestinationPath(filepath);
+  await writeResponseToResolvedPath(response, destinationPath, options);
+}
+class FilesystemAdapter {
+  /**
+   * Configuration options
+   */
+  options;
+  /**
+   * Cache directory path
+   */
+  cacheDir;
+  /**
+   * Creates a new FilesystemAdapter instance
+   *
+   * @param options - Configuration options
+   */
+  constructor(options) {
+    this.options = options;
+    this.cacheDir = options.cacheDir || getTempDirectory("cache");
+  }
+  /**
+   * Factory method to create and initialize a FilesystemAdapter
+   *
+   * @param options - Configuration options
+   * @returns Promise resolving to an initialized FilesystemAdapter
+   */
+  static async create(options) {
+    const fs = new FilesystemAdapter(options);
+    await fs.initialize();
+    return fs;
+  }
+  /**
+   * Initializes the adapter by creating the cache directory
+   */
+  async initialize() {
+    await mkdir(this.cacheDir, { recursive: true });
+  }
+  /**
+   * 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
+   */
+  async download(_url, _options = {
+    force: false
+  }) {
+    return "";
+  }
+  /**
+   * Checks if a file or directory exists
+   *
+   * @param path - Path to check
+   * @returns Promise resolving to boolean indicating existence
+   */
+  async exists(_path) {
+    return false;
+  }
+  /**
+   * Reads a file's contents
+   *
+   * @param path - Path to the file
+   * @returns Promise resolving to the file contents as a string
+   */
+  async read(_path) {
+    return "";
+  }
+  /**
+   * 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
+   */
+  async write(_path, _content) {
+  }
+  /**
+   * Deletes a file or directory
+   *
+   * @param path - Path to delete
+   * @returns Promise that resolves when the deletion is complete
+   */
+  async delete(_path) {
+  }
+  /**
+   * Lists files in a directory
+   *
+   * @param path - Directory path to list
+   * @returns Promise resolving to an array of file names
+   */
+  async list(_path) {
+    return [];
+  }
+  /**
+   * 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
+   */
+  async getCached(file, expiry = 3e5) {
+    return getCached(file, expiry);
+  }
+  /**
+   * Sets data in cache
+   *
+   * @param file - Cache file identifier
+   * @param data - Data to cache
+   * @returns Promise that resolves when the data is cached
+   */
+  async setCached(file, data) {
+    return setCached(file, data);
+  }
+}
+const TMP_DIR = path.resolve(getTempDirectory("kissd"));
+const isFile = (file) => {
+  try {
+    const fileStat = statSync(file);
+    return fileStat.isDirectory() ? false : fileStat;
+  } catch {
+    return false;
+  }
+};
+const isDirectory = (dir) => {
+  try {
+    const dirStat = statSync(dir);
+    if (dirStat.isDirectory()) return true;
+    throw new Error(`${dir} exists but isn't a directory`);
+  } catch (error) {
+    if (error instanceof Error && error.message.includes("ENOENT")) {
+      return false;
+    }
+    throw error;
+  }
+};
+const ensureDirectoryExists = async (dir) => {
+  if (!isDirectory(dir)) {
+    console.log(`Creating directory: ${dir}`);
+    await mkdir(dir, { recursive: true });
+  }
+};
+const upload = async (url, data) => {
+  try {
+    const response = await fetch(url, {
+      method: "PUT",
+      body: Buffer.isBuffer(data) ? new Uint8Array(data) : data,
+      headers: { "Content-Type": "application/octet-stream" }
+    });
+    if (!response.ok) {
+      throw new Error(`unexpected response ${response.statusText}`);
+    }
+    return response;
+  } catch (error) {
+    const err = error;
+    console.error(`Error uploading data to ${url}
+Error: ${err.message}`);
+    throw error;
+  }
+};
+async function download(url, filepath) {
+  try {
+    const response = await fetch(url);
+    if (!response.ok) {
+      throw new Error(`Unexpected response ${response.statusText}`);
+    }
+    const fileStream = createWriteStream(filepath);
+    return new Promise((resolve2, reject) => {
+      fileStream.on("error", reject);
+      fileStream.on("finish", resolve2);
+      response.body?.pipeTo(
+        new WritableStream({
+          write(chunk) {
+            fileStream.write(Buffer.from(chunk));
+          },
+          close() {
+            fileStream.end();
+          },
+          abort(reason) {
+            fileStream.destroy();
+            reject(reason);
+          }
+        })
+      ).catch(reject);
+    });
+  } catch (error) {
+    const err = error;
+    console.error("Error downloading file:", err);
+    throw error;
+  }
+}
+const downloadFileWithCache = async (url, targetPath = null) => {
+  const parsedUrl = new URL$1(url);
+  console.log(targetPath);
+  const downloadPath = targetPath || `${TMP_DIR}/downloads/${parsedUrl.hostname}${parsedUrl.pathname}`;
+  console.log("downloadPath", downloadPath);
+  if (!isFile(downloadPath)) {
+    await ensureDirectoryExists(dirname(downloadPath));
+    await download(url, downloadPath);
+  }
+  return downloadPath;
+};
+const listFiles = async (dirPath, options = { match: /.*/ }) => {
+  const entries = await readdir(dirPath, { withFileTypes: true });
+  const files = entries.filter((entry) => entry.isFile()).map((entry) => entry.name);
+  return options.match ? files.filter((item) => options.match?.test(item)) : files;
+};
+async function getCached(file, expiry = 3e5) {
+  const cacheFile = path.resolve(TMP_DIR, file);
+  const cached = existsSync(cacheFile);
+  if (cached) {
+    const stats = statSync(cacheFile);
+    const modTime = new Date(stats.mtime);
+    const now = /* @__PURE__ */ new Date();
+    const isExpired = expiry && now.getTime() - modTime.getTime() > expiry;
+    if (!isExpired) {
+      return await readFile(cacheFile, "utf8");
+    }
+  }
+}
+async function setCached(file, data) {
+  const cacheFile = path.resolve(TMP_DIR, file);
+  await ensureDirectoryExists(path.dirname(cacheFile));
+  await writeFile(cacheFile, data);
+}
+const mimeTypes = {
+  ".html": "text/html",
+  ".js": "application/javascript",
+  ".json": "application/json",
+  ".css": "text/css",
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".gif": "image/gif",
+  ".txt": "text/plain",
+  ".doc": "application/msword",
+  ".docx": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+  ".xls": "application/vnd.ms-excel",
+  ".xlsx": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+  ".pdf": "application/pdf",
+  ".xml": "application/xml",
+  ".zip": "application/zip",
+  ".rar": "application/x-rar-compressed",
+  ".mp3": "audio/mpeg",
+  ".mp4": "video/mp4",
+  ".avi": "video/x-msvideo",
+  ".mov": "video/quicktime"
+  // Add more mappings as needed
+};
+function getMimeType(fileOrUrl) {
+  const urlPattern = /^[a-zA-Z][a-zA-Z\d+\-.]*:\/\//;
+  let extension;
+  if (urlPattern.test(fileOrUrl)) {
+    const url = new URL$1(fileOrUrl);
+    extension = path.extname(url.pathname);
+  } else {
+    extension = path.extname(fileOrUrl);
+  }
+  return mimeTypes[extension.toLowerCase()] || "application/octet-stream";
+}
+class FilesystemError extends Error {
+  constructor(message, code, path2, provider) {
+    super(message);
+    this.code = code;
+    this.path = path2;
+    this.provider = provider;
+    this.name = "FilesystemError";
+  }
+}
+class FileNotFoundError extends FilesystemError {
+  constructor(path2, provider) {
+    super(`File not found: ${path2}`, "ENOENT", path2, provider);
+    this.name = "FileNotFoundError";
+  }
+}
+class PermissionError extends FilesystemError {
+  constructor(path2, provider) {
+    super(`Permission denied: ${path2}`, "EACCES", path2, provider);
+    this.name = "PermissionError";
+  }
+}
+class DirectoryNotEmptyError extends FilesystemError {
+  constructor(path2, provider) {
+    super(`Directory not empty: ${path2}`, "ENOTEMPTY", path2, provider);
+    this.name = "DirectoryNotEmptyError";
+  }
+}
+class InvalidPathError extends FilesystemError {
+  constructor(path2, provider) {
+    super(`Invalid path: ${path2}`, "EINVAL", path2, provider);
+    this.name = "InvalidPathError";
+  }
+}
+class BaseFilesystemProvider {
+  basePath;
+  applyBasePath;
+  cacheDir;
+  createMissing;
+  providerType;
+  constructor(options = {}) {
+    this.basePath = options.basePath || "";
+    this.applyBasePath = options.applyBasePath ?? true;
+    this.cacheDir = options.cacheDir || this.getDefaultCacheDir();
+    this.createMissing = options.createMissing ?? true;
+    this.providerType = this.constructor.name.toLowerCase().replace("filesystemprovider", "");
+  }
+  /**
+   * Get default cache directory for the current context
+   */
+  getDefaultCacheDir() {
+    try {
+      const { getTempDirectory: getTempDirectory2 } = require("@happyvertical/utils");
+      return getTempDirectory2("files-cache");
+    } catch {
+      if (process?.versions?.node) {
+        try {
+          const { tmpdir } = require("node:os");
+          const { join: join2 } = require("node:path");
+          return join2(tmpdir(), "have-sdk", "files-cache");
+        } catch {
+          return "./tmp/have-sdk/files-cache";
+        }
+      }
+      return "./tmp/have-sdk/files-cache";
+    }
+  }
+  /**
+   * Throw error for unsupported operations
+   */
+  throwUnsupported(operation) {
+    throw new FilesystemError(
+      `Operation '${operation}' not supported by ${this.providerType} provider`,
+      "ENOTSUP",
+      void 0,
+      this.providerType
+    );
+  }
+  /**
+   * Normalize path by removing leading/trailing slashes and resolving relative paths
+   */
+  normalizePath(path2) {
+    if (!path2) return "";
+    let normalized = path2.startsWith("/") ? path2.slice(1) : path2;
+    if (this.applyBasePath && this.basePath) {
+      normalized = this.joinPaths(this.basePath, normalized);
+    }
+    return normalized;
+  }
+  /**
+   * Universal path joining function that works in both Node.js and browser
+   */
+  joinPaths(...paths) {
+    return paths.filter((p) => p && p.length > 0).map((p) => p.replace(/^\/+|\/+$/g, "")).join("/");
+  }
+  /**
+   * Validate that a path is safe (no directory traversal)
+   */
+  validatePath(path2) {
+    if (!path2) {
+      throw new FilesystemError("Path cannot be empty", "EINVAL", path2);
+    }
+    if (path2.includes("..") || path2.includes("~")) {
+      throw new FilesystemError(
+        "Path contains invalid characters (directory traversal)",
+        "EINVAL",
+        path2
+      );
+    }
+  }
+  /**
+   * Get cache key for a given path
+   */
+  getCacheKey(path2) {
+    return `${this.constructor.name}-${path2}`;
+  }
+  /**
+   * Provider methods with default implementations (may be overridden)
+   */
+  async upload(_localPath, _remotePath, _options = {}) {
+    this.throwUnsupported("upload");
+  }
+  async download(_remotePath, _localPath, _options = {}) {
+    this.throwUnsupported("download");
+  }
+  async downloadWithCache(remotePath, options = {}) {
+    const cacheKey = this.getCacheKey(remotePath);
+    if (!options.force) {
+      const cached = await this.cache.get(cacheKey, options.expiry);
+      if (cached) {
+        return cached;
+      }
+    }
+    const localPath = await this.download(remotePath, void 0, options);
+    await this.cache.set(cacheKey, localPath);
+    return localPath;
+  }
+  /**
+   * Cache implementation - providers can override for their specific storage
+   */
+  cache = {
+    get: async (_key, _expiry) => {
+      this.throwUnsupported("cache.get");
+    },
+    set: async (_key, _data) => {
+      this.throwUnsupported("cache.set");
+    },
+    clear: async (_key) => {
+      this.throwUnsupported("cache.clear");
+    }
+  };
+  // Legacy method implementations - providers can override or use default ENOTSUP errors
+  /**
+   * Check if a path is a file (legacy)
+   */
+  async isFile(file) {
+    try {
+      const stats = await this.getStats(file);
+      return stats.isFile ? stats : false;
+    } catch {
+      return false;
+    }
+  }
+  /**
+   * Check if a path is a directory (legacy)
+   */
+  async isDirectory(dir) {
+    try {
+      const stats = await this.getStats(dir);
+      return stats.isDirectory;
+    } catch {
+      return false;
+    }
+  }
+  /**
+   * Create a directory if it doesn't exist (legacy)
+   */
+  async ensureDirectoryExists(dir) {
+    if (!await this.isDirectory(dir)) {
+      await this.createDirectory(dir, { recursive: true });
+    }
+  }
+  /**
+   * Upload data to a URL using PUT method (legacy)
+   */
+  async uploadToUrl(_url, _data) {
+    this.throwUnsupported("uploadToUrl");
+  }
+  /**
+   * Download a file from a URL and save it to a local file (legacy)
+   */
+  async downloadFromUrl(_url, _filepath) {
+    this.throwUnsupported("downloadFromUrl");
+  }
+  /**
+   * Download a file with caching support (legacy)
+   */
+  async downloadFileWithCache(_url, _targetPath) {
+    this.throwUnsupported("downloadFileWithCache");
+  }
+  /**
+   * List files in a directory with optional filtering (legacy)
+   */
+  async listFiles(dirPath, options = { match: /.*/ }) {
+    const files = await this.list(dirPath);
+    const fileNames = files.filter((file) => !file.isDirectory).map((file) => file.name);
+    return options.match ? fileNames.filter((name) => options.match?.test(name)) : fileNames;
+  }
+  /**
+   * Get data from cache if available and not expired (legacy)
+   */
+  async getCached(file, expiry = 3e5) {
+    return await this.cache.get(file, expiry);
+  }
+  /**
+   * Set data in cache (legacy)
+   */
+  async setCached(file, data) {
+    await this.cache.set(file, data);
+  }
+}
+class LocalFilesystemProvider extends BaseFilesystemProvider {
+  rootPath;
+  constructor(options = {}) {
+    super({ ...options, applyBasePath: false });
+    this.rootPath = options.basePath ? resolve(options.basePath) : process.cwd();
+  }
+  /**
+   * Resolve a relative path to an absolute path within the root directory
+   *
+   * This method validates the path, normalizes it, and resolves it relative to
+   * the configured root path. It ensures path safety by preventing directory
+   * traversal attacks.
+   *
+   * @param path - Relative path to resolve
+   * @returns Absolute path within the root directory
+   * @throws {FilesystemError} When path is invalid or contains directory traversal
+   *
+   * @internal
+   */
+  resolvePath(path2) {
+    this.validatePath(path2);
+    const normalized = this.normalizePath(path2);
+    return join(this.rootPath, normalized);
+  }
+  resolveCachePath(path2) {
+    this.validatePath(path2);
+    if (isAbsolute(path2)) {
+      throw new InvalidPathError(path2, this.providerType);
+    }
+    const normalized = this.normalizePath(path2);
+    const cacheRoot = resolve(this.cacheDir);
+    const cachePath = resolve(cacheRoot, normalized);
+    const relativePath = relative(cacheRoot, cachePath);
+    if (!relativePath || relativePath === ".." || relativePath.startsWith(`..${sep}`)) {
+      throw new InvalidPathError(path2, this.providerType);
+    }
+    return cachePath;
+  }
+  /**
+   * Check if a file or directory exists at the specified path
+   *
+   * Uses Node.js fs.access() to check for file existence without reading
+   * the file contents. This is more efficient than trying to read or stat
+   * the file when only existence needs to be verified.
+   *
+   * @param path - Path to check for existence
+   * @returns Promise resolving to true if the path exists, false otherwise
+   *
+   * @example
+   * ```typescript
+   * const exists = await fs.exists('config.json');
+   * if (exists) {
+   *   console.log('Config file found');
+   * }
+   * ```
+   */
+  async exists(path2) {
+    try {
+      const resolvedPath = this.resolvePath(path2);
+      await access(resolvedPath, constants.F_OK);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  /**
+   * Read file contents as string or Buffer
+   *
+   * Reads the entire contents of a file into memory. For large files, consider
+   * using streaming approaches to avoid memory issues.
+   *
+   * @param path - Path to the file to read
+   * @param options - Read options including encoding and raw mode
+   * @param options.encoding - Text encoding for string output (default: 'utf8')
+   * @param options.raw - If true, returns Buffer instead of string
+   * @returns Promise resolving to file contents as string or Buffer
+   * @throws {FileNotFoundError} When the file doesn't exist
+   * @throws {PermissionError} When read access is denied
+   * @throws {FilesystemError} For other filesystem errors
+   *
+   * @example
+   * ```typescript
+   * // Read as UTF-8 string (default)
+   * const text = await fs.read('document.txt');
+   *
+   * // Read as Buffer for binary data
+   * const buffer = await fs.read('image.png', { raw: true });
+   *
+   * // Read with specific encoding
+   * const latin1Text = await fs.read('legacy.txt', { encoding: 'latin1' });
+   * ```
+   */
+  async read(path2, options = {}) {
+    try {
+      const resolvedPath = this.resolvePath(path2);
+      if (options.raw) {
+        return await readFile(resolvedPath);
+      }
+      return await readFile(resolvedPath, options.encoding || "utf8");
+    } catch (error) {
+      if (error.code === "ENOENT") {
+        throw new FileNotFoundError(path2, "local");
+      }
+      if (error.code === "EACCES") {
+        throw new PermissionError(path2, "local");
+      }
+      throw new FilesystemError(
+        `Failed to read file: ${error.message}`,
+        error.code || "UNKNOWN",
+        path2,
+        "local"
+      );
+    }
+  }
+  /**
+   * Write content to a file
+   *
+   * Creates or overwrites a file with the provided content. Can automatically
+   * create parent directories if they don't exist. Supports both string and
+   * binary data.
+   *
+   * @param path - Path where the file should be written
+   * @param content - Content to write (string or Buffer)
+   * @param options - Write options
+   * @param options.encoding - Text encoding for string content
+   * @param options.mode - File permissions (e.g., 0o644)
+   * @param options.createParents - Whether to create parent directories (default: true)
+   * @returns Promise that resolves when the file is written
+   * @throws {FileNotFoundError} When parent directory doesn't exist and createParents is false
+   * @throws {PermissionError} When write access is denied
+   * @throws {FilesystemError} For other filesystem errors
+   *
+   * @example
+   * ```typescript
+   * // Write text file
+   * await fs.write('config.json', JSON.stringify({ key: 'value' }));
+   *
+   * // Write binary data
+   * const imageBuffer = await someImageProcessing();
+   * await fs.write('output.png', imageBuffer);
+   *
+   * // Write with specific permissions
+   * await fs.write('secret.txt', 'sensitive data', { mode: 0o600 });
+   *
+   * // Write without creating parent directories
+   * await fs.write('existing/dir/file.txt', 'content', { createParents: false });
+   * ```
+   */
+  async write(path2, content, options = {}) {
+    try {
+      const resolvedPath = this.resolvePath(path2);
+      if (options.createParents ?? this.createMissing) {
+        await mkdir(dirname(resolvedPath), { recursive: true });
+      }
+      await writeFile(resolvedPath, content, {
+        encoding: options.encoding,
+        mode: options.mode
+      });
+    } catch (error) {
+      if (error.code === "ENOENT") {
+        throw new FileNotFoundError(dirname(path2), "local");
+      }
+      if (error.code === "EACCES") {
+        throw new PermissionError(path2, "local");
+      }
+      throw new FilesystemError(
+        `Failed to write file: ${error.message}`,
+        error.code || "UNKNOWN",
+        path2,
+        "local"
+      );
+    }
+  }
+  /**
+   * Delete a file or empty directory
+   *
+   * Removes a file or directory from the filesystem. For directories, they must
+   * be empty. Use recursive deletion utilities for non-empty directories.
+   *
+   * @param path - Path to the file or directory to delete
+   * @returns Promise that resolves when the item is deleted
+   * @throws {FileNotFoundError} When the file or directory doesn't exist
+   * @throws {PermissionError} When delete access is denied
+   * @throws {DirectoryNotEmptyError} When trying to delete a non-empty directory
+   * @throws {FilesystemError} For other filesystem errors
+   *
+   * @example
+   * ```typescript
+   * // Delete a file
+   * await fs.delete('temp.txt');
+   *
+   * // Delete an empty directory
+   * await fs.delete('empty-dir/');
+   * ```
+   */
+  async delete(path2) {
+    try {
+      const resolvedPath = this.resolvePath(path2);
+      const stats = await stat(resolvedPath);
+      if (stats.isDirectory()) {
+        await rmdir(resolvedPath);
+      } else {
+        await unlink(resolvedPath);
+      }
+    } catch (error) {
+      if (error.code === "ENOENT") {
+        throw new FileNotFoundError(path2, "local");
+      }
+      if (error.code === "EACCES") {
+        throw new PermissionError(path2, "local");
+      }
+      if (error.code === "ENOTEMPTY") {
+        throw new DirectoryNotEmptyError(path2, "local");
+      }
+      throw new FilesystemError(
+        `Failed to delete: ${error.message}`,
+        error.code || "UNKNOWN",
+        path2,
+        "local"
+      );
+    }
+  }
+  /**
+   * Copy a file from source to destination
+   *
+   * Creates an exact copy of a file at the destination path. Will create
+   * parent directories if they don't exist and createMissing is enabled.
+   * The operation preserves file contents but not necessarily all metadata.
+   *
+   * @param sourcePath - Path to the source file
+   * @param destPath - Path where the copy should be created
+   * @returns Promise that resolves when the file is copied
+   * @throws {FileNotFoundError} When the source file doesn't exist
+   * @throws {PermissionError} When read/write access is denied
+   * @throws {FilesystemError} For other filesystem errors
+   *
+   * @example
+   * ```typescript
+   * // Copy a file
+   * await fs.copy('original.txt', 'backup.txt');
+   *
+   * // Copy to a different directory
+   * await fs.copy('data.json', 'backup/data-copy.json');
+   * ```
+   */
+  async copy(sourcePath, destPath) {
+    try {
+      const resolvedSource = this.resolvePath(sourcePath);
+      const resolvedDest = this.resolvePath(destPath);
+      if (this.createMissing) {
+        await mkdir(dirname(resolvedDest), { recursive: true });
+      }
+      await copyFile(resolvedSource, resolvedDest);
+    } catch (error) {
+      if (error.code === "ENOENT") {
+        throw new FileNotFoundError(sourcePath, "local");
+      }
+      if (error.code === "EACCES") {
+        throw new PermissionError(sourcePath, "local");
+      }
+      throw new FilesystemError(
+        `Failed to copy: ${error.message}`,
+        error.code || "UNKNOWN",
+        sourcePath,
+        "local"
+      );
+    }
+  }
+  /**
+   * Move/rename a file from source to destination
+   *
+   * Moves a file to a new location, effectively combining copy and delete
+   * operations. This is atomic on most filesystems when moving within the
+   * same filesystem. Will create parent directories if they don't exist.
+   *
+   * @param sourcePath - Path to the source file
+   * @param destPath - Path where the file should be moved
+   * @returns Promise that resolves when the file is moved
+   * @throws {FileNotFoundError} When the source file doesn't exist
+   * @throws {PermissionError} When move access is denied
+   * @throws {FilesystemError} For other filesystem errors
+   *
+   * @example
+   * ```typescript
+   * // Rename a file
+   * await fs.move('old-name.txt', 'new-name.txt');
+   *
+   * // Move to a different directory
+   * await fs.move('temp.txt', 'archive/temp.txt');
+   * ```
+   */
+  async move(sourcePath, destPath) {
+    try {
+      const resolvedSource = this.resolvePath(sourcePath);
+      const resolvedDest = this.resolvePath(destPath);
+      if (this.createMissing) {
+        await mkdir(dirname(resolvedDest), { recursive: true });
+      }
+      await rename(resolvedSource, resolvedDest);
+    } catch (error) {
+      if (error.code === "ENOENT") {
+        throw new FileNotFoundError(sourcePath, "local");
+      }
+      if (error.code === "EACCES") {
+        throw new PermissionError(sourcePath, "local");
+      }
+      throw new FilesystemError(
+        `Failed to move: ${error.message}`,
+        error.code || "UNKNOWN",
+        sourcePath,
+        "local"
+      );
+    }
+  }
+  /**
+   * Create a directory at the specified path
+   *
+   * Creates a new directory with optional recursive creation of parent
+   * directories. Supports setting directory permissions.
+   *
+   * @param path - Path where the directory should be created
+   * @param options - Directory creation options
+   * @param options.recursive - Whether to create parent directories (default: true)
+   * @param options.mode - Directory permissions (e.g., 0o755)
+   * @returns Promise that resolves when the directory is created
+   * @throws {PermissionError} When create access is denied
+   * @throws {FilesystemError} For other filesystem errors
+   *
+   * @example
+   * ```typescript
+   * // Create directory with parents
+   * await fs.createDirectory('path/to/new/dir');
+   *
+   * // Create directory with specific permissions
+   * await fs.createDirectory('private-dir', { mode: 0o700 });
+   *
+   * // Create directory without parent creation
+   * await fs.createDirectory('existing-parent/new-dir', { recursive: false });
+   * ```
+   */
+  async createDirectory(path2, options = {}) {
+    try {
+      const resolvedPath = this.resolvePath(path2);
+      await mkdir(resolvedPath, {
+        recursive: options.recursive ?? true,
+        mode: options.mode
+      });
+    } catch (error) {
+      if (error.code === "EACCES") {
+        throw new PermissionError(path2, "local");
+      }
+      throw new FilesystemError(
+        `Failed to create directory: ${error.message}`,
+        error.code || "UNKNOWN",
+        path2,
+        "local"
+      );
+    }
+  }
+  /**
+   * List the contents of a directory
+   *
+   * Returns an array of FileInfo objects describing each item in the directory.
+   * Supports filtering, recursive listing, and detailed metadata retrieval.
+   *
+   * @param path - Path to the directory to list
+   * @param options - Listing options
+   * @param options.recursive - Whether to include subdirectories recursively
+   * @param options.filter - RegExp or string pattern to filter file names
+   * @param options.detailed - Whether to include MIME types and extended metadata
+   * @returns Promise resolving to array of FileInfo objects
+   * @throws {FileNotFoundError} When the directory doesn't exist
+   * @throws {PermissionError} When read access is denied
+   * @throws {FilesystemError} For other filesystem errors
+   *
+   * @example
+   * ```typescript
+   * // List all files and directories
+   * const items = await fs.list('/path/to/dir');
+   * items.forEach(item => {
+   *   console.log(`${item.name} (${item.isDirectory ? 'dir' : 'file'})`);
+   * });
+   *
+   * // List only text files
+   * const textFiles = await fs.list('/documents', { filter: /\.txt$/ });
+   *
+   * // Recursive listing with detailed info
+   * const allFiles = await fs.list('/project', {
+   *   recursive: true,
+   *   detailed: true
+   * });
+   * ```
+   */
+  async list(path2, options = {}) {
+    try {
+      const resolvedPath = this.resolvePath(path2);
+      const entries = await readdir(resolvedPath, { withFileTypes: true });
+      const results = [];
+      for (const entry of entries) {
+        const fullPath = join(resolvedPath, entry.name);
+        const relativePath = join(path2, entry.name);
+        if (options.filter) {
+          const filterPattern = typeof options.filter === "string" ? new RegExp(options.filter) : options.filter;
+          if (!filterPattern.test(entry.name)) {
+            continue;
+          }
+        }
+        const stats = await stat(fullPath);
+        const fileInfo = {
+          name: entry.name,
+          path: relativePath,
+          size: stats.size,
+          isDirectory: entry.isDirectory(),
+          lastModified: stats.mtime,
+          extension: entry.isFile() ? extname(entry.name).slice(1) : void 0
+        };
+        if (options.detailed) {
+          fileInfo.mimeType = await this.getMimeType(relativePath);
+        }
+        results.push(fileInfo);
+        if (options.recursive && entry.isDirectory()) {
+          const subResults = await this.list(relativePath, options);
+          results.push(...subResults);
+        }
+      }
+      return results;
+    } catch (error) {
+      if (error.code === "ENOENT") {
+        throw new FileNotFoundError(path2, "local");
+      }
+      if (error.code === "EACCES") {
+        throw new PermissionError(path2, "local");
+      }
+      throw new FilesystemError(
+        `Failed to list directory: ${error.message}`,
+        error.code || "UNKNOWN",
+        path2,
+        "local"
+      );
+    }
+  }
+  /**
+   * Get detailed file or directory statistics
+   *
+   * Returns comprehensive metadata about a file or directory including size,
+   * timestamps, permissions, and ownership information.
+   *
+   * @param path - Path to the file or directory
+   * @returns Promise resolving to FileStats object with detailed metadata
+   * @throws {FileNotFoundError} When the path doesn't exist
+   * @throws {PermissionError} When stat access is denied
+   * @throws {FilesystemError} For other filesystem errors
+   *
+   * @example
+   * ```typescript
+   * const stats = await fs.getStats('document.pdf');
+   * console.log(`Size: ${stats.size} bytes`);
+   * console.log(`Modified: ${stats.mtime}`);
+   * console.log(`Is file: ${stats.isFile}`);
+   * console.log(`Permissions: ${stats.mode.toString(8)}`);
+   * ```
+   */
+  async getStats(path2) {
+    try {
+      const resolvedPath = this.resolvePath(path2);
+      const stats = await stat(resolvedPath);
+      return {
+        size: stats.size,
+        isDirectory: stats.isDirectory(),
+        isFile: stats.isFile(),
+        birthtime: stats.birthtime,
+        atime: stats.atime,
+        mtime: stats.mtime,
+        ctime: stats.ctime,
+        mode: stats.mode,
+        uid: stats.uid,
+        gid: stats.gid
+      };
+    } catch (error) {
+      if (error.code === "ENOENT") {
+        throw new FileNotFoundError(path2, "local");
+      }
+      if (error.code === "EACCES") {
+        throw new PermissionError(path2, "local");
+      }
+      throw new FilesystemError(
+        `Failed to get stats: ${error.message}`,
+        error.code || "UNKNOWN",
+        path2,
+        "local"
+      );
+    }
+  }
+  /**
+   * Get the MIME type for a file based on its extension
+   *
+   * Determines the MIME type by examining the file extension. Returns a
+   * standard MIME type string that can be used for content-type headers
+   * or file type detection.
+   *
+   * @param path - Path to the file
+   * @returns Promise resolving to MIME type string (e.g., 'text/plain', 'image/png')
+   *
+   * @example
+   * ```typescript
+   * const mimeType = await fs.getMimeType('document.pdf');
+   * console.log(mimeType); // 'application/pdf'
+   *
+   * const imageMime = await fs.getMimeType('photo.jpg');
+   * console.log(imageMime); // 'image/jpeg'
+   * ```
+   */
+  async getMimeType(path2) {
+    const mimeTypes2 = {
+      ".html": "text/html",
+      ".js": "application/javascript",
+      ".json": "application/json",
+      ".css": "text/css",
+      ".png": "image/png",
+      ".jpg": "image/jpeg",
+      ".jpeg": "image/jpeg",
+      ".gif": "image/gif",
+      ".txt": "text/plain",
+      ".doc": "application/msword",
+      ".docx": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+      ".xls": "application/vnd.ms-excel",
+      ".xlsx": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+      ".pdf": "application/pdf",
+      ".xml": "application/xml",
+      ".zip": "application/zip",
+      ".rar": "application/x-rar-compressed",
+      ".mp3": "audio/mpeg",
+      ".mp4": "video/mp4",
+      ".avi": "video/x-msvideo",
+      ".mov": "video/quicktime"
+    };
+    const extension = extname(path2).toLowerCase();
+    return mimeTypes2[extension] || "application/octet-stream";
+  }
+  /**
+   * Upload data to a URL using PUT method (legacy)
+   */
+  async uploadToUrl(url, data) {
+    try {
+      const response = await fetch(url, {
+        method: "PUT",
+        body: Buffer.isBuffer(data) ? new Uint8Array(data) : data,
+        headers: { "Content-Type": "application/octet-stream" }
+      });
+      if (!response.ok) {
+        throw new Error(`unexpected response ${response.statusText}`);
+      }
+      return response;
+    } catch (error) {
+      const err = error;
+      console.error(`Error uploading data to ${url}
+Error: ${err.message}`);
+      throw error;
+    }
+  }
+  /**
+   * Download a file from a URL and save it to a local file (legacy)
+   */
+  async downloadFromUrl(url, filepath) {
+    try {
+      const response = await fetch(url);
+      if (!response.ok) {
+        throw new Error(`Unexpected response ${response.statusText}`);
+      }
+      const fileStream = createWriteStream(this.resolvePath(filepath));
+      return new Promise((resolve2, reject) => {
+        fileStream.on("error", reject);
+        fileStream.on("finish", resolve2);
+        response.body?.pipeTo(
+          new WritableStream({
+            write(chunk) {
+              fileStream.write(Buffer.from(chunk));
+            },
+            close() {
+              fileStream.end();
+            },
+            abort(reason) {
+              fileStream.destroy();
+              reject(reason);
+            }
+          })
+        ).catch(reject);
+      });
+    } catch (error) {
+      const err = error;
+      console.error("Error downloading file:", err);
+      throw error;
+    }
+  }
+  /**
+   * Download a file with caching support (legacy)
+   */
+  async downloadFileWithCache(url, targetPath = null) {
+    const parsedUrl = new URL$1(url);
+    const downloadPath = targetPath || join(
+      getTempDirectory("downloads"),
+      parsedUrl.hostname + parsedUrl.pathname
+    );
+    if (!existsSync(downloadPath)) {
+      await mkdir(dirname(downloadPath), { recursive: true });
+      await this.downloadFromUrl(url, downloadPath);
+    }
+    return downloadPath;
+  }
+  /**
+   * Get data from cache if available and not expired (legacy)
+   */
+  async getCached(file, expiry = 3e5) {
+    const cacheFile = this.resolveCachePath(file);
+    const cached = existsSync(cacheFile);
+    if (cached) {
+      const stats = statSync(cacheFile);
+      const modTime = new Date(stats.mtime);
+      const now = /* @__PURE__ */ new Date();
+      const isExpired = expiry && now.getTime() - modTime.getTime() > expiry;
+      if (!isExpired) {
+        return await readFile(cacheFile, "utf8");
+      }
+    }
+    return void 0;
+  }
+  /**
+   * Set data in cache (legacy)
+   */
+  async setCached(file, data) {
+    const cacheFile = this.resolveCachePath(file);
+    await mkdir(dirname(cacheFile), { recursive: true });
+    await writeFile(cacheFile, data);
+  }
+  /**
+   * Cache implementation using file system
+   */
+  cache = {
+    get: async (key, expiry) => {
+      return await this.getCached(key, expiry);
+    },
+    set: async (key, data) => {
+      await this.setCached(key, data);
+    },
+    clear: async (key) => {
+      if (key) {
+        const cacheFile = this.resolveCachePath(key);
+        try {
+          await unlink(cacheFile);
+        } catch {
+        }
+      } else {
+        try {
+          await rmdir(this.cacheDir, { recursive: true });
+        } catch {
+        }
+      }
+    }
+  };
+  /**
+   * Get provider capabilities
+   */
+  async getCapabilities() {
+    return {
+      streaming: true,
+      atomicOperations: true,
+      versioning: false,
+      sharing: false,
+      realTimeSync: false,
+      offlineCapable: true,
+      supportedOperations: [
+        "exists",
+        "read",
+        "write",
+        "delete",
+        "copy",
+        "move",
+        "createDirectory",
+        "list",
+        "getStats",
+        "getMimeType",
+        "upload",
+        "download",
+        "downloadWithCache",
+        "isFile",
+        "isDirectory",
+        "ensureDirectoryExists",
+        "uploadToUrl",
+        "downloadFromUrl",
+        "downloadFileWithCache",
+        "listFiles",
+        "getCached",
+        "setCached"
+      ]
+    };
+  }
+}
+const local = /* @__PURE__ */ Object.freeze(/* @__PURE__ */ Object.defineProperty({
+  __proto__: null,
+  LocalFilesystemProvider
+}, Symbol.toStringTag, { value: "Module" }));
+const MIME_TYPES$1 = {
+  ".html": "text/html",
+  ".js": "application/javascript",
+  ".json": "application/json",
+  ".css": "text/css",
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".gif": "image/gif",
+  ".svg": "image/svg+xml",
+  ".txt": "text/plain",
+  ".md": "text/markdown",
+  ".csv": "text/csv",
+  ".doc": "application/msword",
+  ".docx": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+  ".xls": "application/vnd.ms-excel",
+  ".xlsx": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+  ".ppt": "application/vnd.ms-powerpoint",
+  ".pptx": "application/vnd.openxmlformats-officedocument.presentationml.presentation",
+  ".pdf": "application/pdf",
+  ".xml": "application/xml",
+  ".zip": "application/zip",
+  ".mp3": "audio/mpeg",
+  ".mp4": "video/mp4"
+};
+const GOOGLE_EXPORT_MIMES = {
+  "application/vnd.google-apps.document": "text/plain",
+  "application/vnd.google-apps.spreadsheet": "text/csv",
+  "application/vnd.google-apps.presentation": "application/pdf",
+  "application/vnd.google-apps.drawing": "image/png"
+};
+class GoogleDriveProvider extends BaseFilesystemProvider {
+  constructor(options) {
+    super(options);
+    this.options = options;
+    this.rootFolderId = options.folderId || "root";
+    this.pathCacheTTL = options.pathCacheTTL ?? 3e5;
+    this.pageSize = options.pageSize ?? 100;
+  }
+  drive;
+  rootFolderId;
+  pathCache = /* @__PURE__ */ new Map();
+  pathCacheTTL;
+  pageSize;
+  /**
+   * Lazily initialize the Google Drive client on first use
+   */
+  async getDrive() {
+    if (this.drive) return this.drive;
+    const { google } = await import("googleapis");
+    let auth;
+    if (this.options.serviceAccountKey) {
+      const { GoogleAuth } = await import("google-auth-library");
+      const key = JSON.parse(this.options.serviceAccountKey);
+      auth = new GoogleAuth({
+        credentials: key,
+        scopes: this.options.scopes || [
+          "https://www.googleapis.com/auth/drive"
+        ]
+      });
+    } else if (this.options.clientId && this.options.clientSecret && this.options.refreshToken) {
+      const oauth2 = new google.auth.OAuth2(
+        this.options.clientId,
+        this.options.clientSecret
+      );
+      oauth2.setCredentials({
+        refresh_token: this.options.refreshToken,
+        access_token: this.options.accessToken
+      });
+      auth = oauth2;
+    } else if (this.options.accessToken) {
+      const oauth2 = new google.auth.OAuth2();
+      oauth2.setCredentials({ access_token: this.options.accessToken });
+      auth = oauth2;
+    } else {
+      throw new FilesystemError(
+        "Google Drive provider requires OAuth2 credentials, a serviceAccountKey, or an accessToken",
+        "EINVAL",
+        void 0,
+        "gdrive"
+      );
+    }
+    this.drive = google.drive({ version: "v3", auth });
+    return this.drive;
+  }
+  // ---------------------------------------------------------------------------
+  // Path ↔ File-ID resolution
+  // ---------------------------------------------------------------------------
+  /**
+   * Resolve a hierarchical path like "folder/sub/file.txt" to a Drive file ID
+   * by walking each segment. Results are cached with a configurable TTL.
+   */
+  async resolvePathToId(path2) {
+    const normalized = this.normalizePath(path2);
+    if (!normalized || normalized === ".") return this.rootFolderId;
+    const cached = this.pathCache.get(normalized);
+    if (cached && Date.now() - cached.ts < this.pathCacheTTL) {
+      return cached.id;
+    }
+    const segments = normalized.split("/").filter(Boolean);
+    let parentId = this.rootFolderId;
+    for (const segment of segments) {
+      const drive = await this.getDrive();
+      const q = `'${parentId}' in parents and name = '${segment.replace(/'/g, "\\'")}' and trashed = false`;
+      const res = await this.wrapApiCall(
+        () => drive.files.list({
+          q,
+          fields: "files(id, name)",
+          pageSize: 1
+        }),
+        path2
+      );
+      if (!res.data.files || res.data.files.length === 0) {
+        return null;
+      }
+      parentId = res.data.files[0].id;
+    }
+    this.pathCache.set(normalized, { id: parentId, ts: Date.now() });
+    return parentId;
+  }
+  /**
+   * Resolve a path to an ID, throwing FileNotFoundError if it doesn't exist
+   */
+  async requireId(path2) {
+    const id = await this.resolvePathToId(path2);
+    if (!id) throw new FileNotFoundError(path2, "gdrive");
+    return id;
+  }
+  /**
+   * Ensure all parent folders exist for a given path, creating them if needed.
+   * Returns the parent folder ID and the final segment name.
+   */
+  async ensureParents(path2) {
+    const normalized = this.normalizePath(path2);
+    const segments = normalized.split("/").filter(Boolean);
+    const name = segments.pop();
+    let parentId = this.rootFolderId;
+    let currentPath = "";
+    for (const segment of segments) {
+      currentPath = currentPath ? `${currentPath}/${segment}` : segment;
+      const existingId = await this.resolvePathToId(currentPath);
+      if (existingId) {
+        parentId = existingId;
+        continue;
+      }
+      const drive = await this.getDrive();
+      const res = await this.wrapApiCall(
+        () => drive.files.create({
+          requestBody: {
+            name: segment,
+            mimeType: "application/vnd.google-apps.folder",
+            parents: [parentId]
+          },
+          fields: "id"
+        }),
+        path2
+      );
+      parentId = res.data.id;
+      this.pathCache.set(currentPath, { id: parentId, ts: Date.now() });
+    }
+    return { parentId, name };
+  }
+  /**
+   * Invalidate cache entries that are prefixed by the given path
+   */
+  invalidateCache(path2) {
+    const normalized = this.normalizePath(path2);
+    for (const key of this.pathCache.keys()) {
+      if (key === normalized || key.startsWith(normalized + "/")) {
+        this.pathCache.delete(key);
+      }
+    }
+  }
+  // ---------------------------------------------------------------------------
+  // API error mapping
+  // ---------------------------------------------------------------------------
+  /**
+   * Wrap a Drive API call and map HTTP errors to typed filesystem errors
+   */
+  async wrapApiCall(fn, path2) {
+    try {
+      return await fn();
+    } catch (error) {
+      const status = error?.code ?? error?.response?.status;
+      if (status === 404) {
+        throw new FileNotFoundError(path2, "gdrive");
+      }
+      if (status === 403) {
+        throw new PermissionError(path2, "gdrive");
+      }
+      if (status === 401) {
+        throw new FilesystemError(
+          `Authentication failed: ${error.message}`,
+          "EACCES",
+          path2,
+          "gdrive"
+        );
+      }
+      if (status === 429) {
+        throw new FilesystemError(
+          `Rate limited: ${error.message}`,
+          "EAGAIN",
+          path2,
+          "gdrive"
+        );
+      }
+      throw new FilesystemError(
+        `Google Drive API error: ${error.message}`,
+        error.code?.toString() || "UNKNOWN",
+        path2,
+        "gdrive"
+      );
+    }
+  }
+  // ---------------------------------------------------------------------------
+  // FilesystemInterface implementation
+  // ---------------------------------------------------------------------------
+  /** Checks whether a non-trashed file or folder exists at the given path. */
+  async exists(path2) {
+    const id = await this.resolvePathToId(path2);
+    return id !== null;
+  }
+  /**
+   * Read a file from Google Drive. Google Docs native types (Document,
+   * Spreadsheet, Presentation, Drawing) are automatically exported to a
+   * portable format (plain text, CSV, PDF, PNG respectively).
+   */
+  async read(path2, options = {}) {
+    const fileId = await this.requireId(path2);
+    const drive = await this.getDrive();
+    const meta = await this.wrapApiCall(
+      () => drive.files.get({ fileId, fields: "mimeType" }),
+      path2
+    );
+    const mimeType = meta.data.mimeType;
+    const exportMime = GOOGLE_EXPORT_MIMES[mimeType];
+    let data;
+    if (exportMime) {
+      const res = await this.wrapApiCall(
+        () => drive.files.export(
+          { fileId, mimeType: exportMime },
+          { responseType: "arraybuffer" }
+        ),
+        path2
+      );
+      data = Buffer.from(res.data);
+    } else {
+      const res = await this.wrapApiCall(
+        () => drive.files.get(
+          { fileId, alt: "media" },
+          { responseType: "arraybuffer" }
+        ),
+        path2
+      );
+      data = Buffer.from(res.data);
+    }
+    if (options.raw) {
+      return data;
+    }
+    return data.toString(options.encoding || "utf8");
+  }
+  /** Write content to Drive. Updates the file in-place if it already exists, otherwise creates it. */
+  async write(path2, content, options = {}) {
+    const body = Buffer.isBuffer(content) ? content : Buffer.from(content);
+    const ext = extname(path2).toLowerCase();
+    const contentMime = MIME_TYPES$1[ext] || "application/octet-stream";
+    const existingId = await this.resolvePathToId(path2);
+    const drive = await this.getDrive();
+    if (existingId && existingId !== this.rootFolderId) {
+      await this.wrapApiCall(
+        () => drive.files.update({
+          fileId: existingId,
+          media: { mimeType: contentMime, body }
+        }),
+        path2
+      );
+    } else {
+      if (options.createParents ?? this.createMissing) {
+        const { parentId, name } = await this.ensureParents(path2);
+        await this.wrapApiCall(
+          () => drive.files.create({
+            requestBody: {
+              name,
+              parents: [parentId]
+            },
+            media: { mimeType: contentMime, body },
+            fields: "id"
+          }),
+          path2
+        );
+      } else {
+        const parentPath = dirname(this.normalizePath(path2));
+        const parentId = parentPath === "." || parentPath === "" ? this.rootFolderId : await this.requireId(parentPath);
+        const name = basename(path2);
+        await this.wrapApiCall(
+          () => drive.files.create({
+            requestBody: {
+              name,
+              parents: [parentId]
+            },
+            media: { mimeType: contentMime, body },
+            fields: "id"
+          }),
+          path2
+        );
+      }
+    }
+    this.invalidateCache(path2);
+  }
+  /** Moves the file to the Drive trash rather than permanently deleting it. */
+  async delete(path2) {
+    const fileId = await this.requireId(path2);
+    const drive = await this.getDrive();
+    await this.wrapApiCall(
+      () => drive.files.update({
+        fileId,
+        requestBody: { trashed: true }
+      }),
+      path2
+    );
+    this.invalidateCache(path2);
+  }
+  async copy(sourcePath, destPath) {
+    const sourceId = await this.requireId(sourcePath);
+    const drive = await this.getDrive();
+    const { parentId, name } = await this.ensureParents(destPath);
+    await this.wrapApiCall(
+      () => drive.files.copy({
+        fileId: sourceId,
+        requestBody: {
+          name,
+          parents: [parentId]
+        },
+        fields: "id"
+      }),
+      sourcePath
+    );
+    this.invalidateCache(destPath);
+  }
+  /** Moves a file by updating its parent references (single API call, not copy+delete). */
+  async move(sourcePath, destPath) {
+    const sourceId = await this.requireId(sourcePath);
+    const drive = await this.getDrive();
+    const fileMeta = await this.wrapApiCall(
+      () => drive.files.get({ fileId: sourceId, fields: "parents" }),
+      sourcePath
+    );
+    const previousParents = (fileMeta.data.parents || []).join(",");
+    const { parentId, name } = await this.ensureParents(destPath);
+    await this.wrapApiCall(
+      () => drive.files.update({
+        fileId: sourceId,
+        addParents: parentId,
+        removeParents: previousParents,
+        requestBody: { name },
+        fields: "id, parents"
+      }),
+      sourcePath
+    );
+    this.invalidateCache(sourcePath);
+    this.invalidateCache(destPath);
+  }
+  async createDirectory(path2, options = {}) {
+    const normalized = this.normalizePath(path2);
+    const segments = normalized.split("/").filter(Boolean);
+    if (options.recursive ?? true) {
+      let currentPath = "";
+      for (const segment of segments) {
+        currentPath = currentPath ? `${currentPath}/${segment}` : segment;
+        const existingId = await this.resolvePathToId(currentPath);
+        if (!existingId) {
+          const parentPath = dirname(currentPath);
+          const parentId = parentPath === "." || parentPath === "" ? this.rootFolderId : await this.requireId(parentPath);
+          const drive = await this.getDrive();
+          const res = await this.wrapApiCall(
+            () => drive.files.create({
+              requestBody: {
+                name: segment,
+                mimeType: "application/vnd.google-apps.folder",
+                parents: [parentId]
+              },
+              fields: "id"
+            }),
+            path2
+          );
+          this.pathCache.set(currentPath, {
+            id: res.data.id,
+            ts: Date.now()
+          });
+        }
+      }
+    } else {
+      const parentPath = dirname(normalized);
+      const parentId = parentPath === "." || parentPath === "" ? this.rootFolderId : await this.requireId(parentPath);
+      const name = segments[segments.length - 1];
+      const drive = await this.getDrive();
+      const res = await this.wrapApiCall(
+        () => drive.files.create({
+          requestBody: {
+            name,
+            mimeType: "application/vnd.google-apps.folder",
+            parents: [parentId]
+          },
+          fields: "id"
+        }),
+        path2
+      );
+      this.pathCache.set(normalized, { id: res.data.id, ts: Date.now() });
+    }
+  }
+  /** Lists non-trashed children of a folder, with optional pagination via {@link GoogleDriveOptions.pageSize}. */
+  async list(path2, options = {}) {
+    const folderId = !path2 || path2 === "." || path2 === "/" ? this.rootFolderId : await this.requireId(path2);
+    const drive = await this.getDrive();
+    const results = [];
+    let pageToken;
+    do {
+      const res = await this.wrapApiCall(
+        () => drive.files.list({
+          q: `'${folderId}' in parents and trashed = false`,
+          fields: "nextPageToken, files(id, name, mimeType, size, modifiedTime)",
+          pageSize: this.pageSize,
+          pageToken
+        }),
+        path2
+      );
+      const files = res.data.files || [];
+      for (const file of files) {
+        const isDir = file.mimeType === "application/vnd.google-apps.folder";
+        const name = file.name;
+        const filePath = path2 && path2 !== "." && path2 !== "/" ? `${this.normalizePath(path2)}/${name}` : name;
+        if (options.filter) {
+          const filterPattern = typeof options.filter === "string" ? new RegExp(options.filter) : options.filter;
+          if (!filterPattern.test(name)) continue;
+        }
+        const ext = isDir ? void 0 : extname(name).slice(1) || void 0;
+        const fileInfo = {
+          name,
+          path: filePath,
+          size: Number(file.size || 0),
+          isDirectory: isDir,
+          lastModified: new Date(file.modifiedTime),
+          extension: ext
+        };
+        if (options.detailed) {
+          fileInfo.mimeType = file.mimeType;
+        }
+        results.push(fileInfo);
+        this.pathCache.set(filePath, { id: file.id, ts: Date.now() });
+        if (options.recursive && isDir) {
+          const subResults = await this.list(filePath, options);
+          results.push(...subResults);
+        }
+      }
+      pageToken = res.data.nextPageToken ?? void 0;
+    } while (pageToken);
+    return results;
+  }
+  /** Returns file metadata. Mode is synthetic (0o755 for folders, 0o644 for files); uid/gid are always 0. */
+  async getStats(path2) {
+    const fileId = await this.requireId(path2);
+    const drive = await this.getDrive();
+    const res = await this.wrapApiCall(
+      () => drive.files.get({
+        fileId,
+        fields: "id, name, mimeType, size, createdTime, modifiedTime"
+      }),
+      path2
+    );
+    const file = res.data;
+    const isDir = file.mimeType === "application/vnd.google-apps.folder";
+    const modifiedTime = new Date(file.modifiedTime);
+    const createdTime = new Date(file.createdTime);
+    return {
+      size: Number(file.size || 0),
+      isDirectory: isDir,
+      isFile: !isDir,
+      birthtime: createdTime,
+      atime: modifiedTime,
+      mtime: modifiedTime,
+      ctime: modifiedTime,
+      mode: isDir ? 493 : 420,
+      uid: 0,
+      gid: 0
+    };
+  }
+  async getMimeType(path2) {
+    const ext = extname(path2).toLowerCase();
+    return MIME_TYPES$1[ext] || "application/octet-stream";
+  }
+  async upload(localPath, remotePath, _options = {}) {
+    const content = await readFile(localPath);
+    await this.write(remotePath, content);
+  }
+  /** Downloads a file from Drive to the local filesystem, defaulting to the provider's cache directory. */
+  async download(remotePath, localPath, _options = {}) {
+    const content = await this.read(remotePath, { raw: true });
+    const target = localPath || join(this.cacheDir, this.normalizePath(remotePath));
+    await mkdir(dirname(target), { recursive: true });
+    await writeFile(target, content);
+    return target;
+  }
+  async getCapabilities() {
+    return {
+      streaming: false,
+      atomicOperations: false,
+      versioning: true,
+      sharing: true,
+      realTimeSync: true,
+      offlineCapable: false,
+      maxFileSize: 5 * 1024 * 1024 * 1024 * 1024,
+      // 5 TB
+      supportedOperations: [
+        "exists",
+        "read",
+        "write",
+        "delete",
+        "copy",
+        "move",
+        "createDirectory",
+        "list",
+        "getStats",
+        "getMimeType",
+        "upload",
+        "download"
+      ]
+    };
+  }
+}
+const gdrive = /* @__PURE__ */ Object.freeze(/* @__PURE__ */ Object.defineProperty({
+  __proto__: null,
+  GoogleDriveProvider
+}, Symbol.toStringTag, { value: "Module" }));
+const MIME_TYPES = {
+  ".txt": "text/plain",
+  ".json": "application/json",
+  ".csv": "text/csv",
+  ".svg": "image/svg+xml",
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".webp": "image/webp",
+  ".pdf": "application/pdf",
+  ".mp4": "video/mp4",
+  ".webm": "video/webm"
+};
+function toDate(value) {
+  return value instanceof Date ? value : /* @__PURE__ */ new Date();
+}
+function toCopySource(bucket, key) {
+  return `${bucket}/${key.split("/").map((segment) => encodeURIComponent(segment)).join("/")}`;
+}
+class S3FilesystemProvider extends BaseFilesystemProvider {
+  constructor(options) {
+    super(options);
+    this.options = options;
+    this.bucket = options.bucket;
+    this.client = new S3Client({
+      region: options.region,
+      endpoint: options.endpoint,
+      forcePathStyle: options.forcePathStyle,
+      credentials: options.accessKeyId && options.secretAccessKey ? {
+        accessKeyId: options.accessKeyId,
+        secretAccessKey: options.secretAccessKey
+      } : void 0
+    });
+  }
+  client;
+  bucket;
+  normalizeS3Path(path2, options = {}) {
+    const normalized = path2 === "." || path2 === "/" ? this.basePath.replace(/^\/+|\/+$/g, "") : this.normalizePath(path2).replace(/^\/+|\/+$/g, "");
+    if (!normalized) {
+      return "";
+    }
+    if (options.preserveTrailingSlash && path2 !== "." && path2 !== "/" && /\/+$/.test(path2)) {
+      return `${normalized}/`;
+    }
+    return normalized;
+  }
+  toDirectoryKey(path2) {
+    const directoryPath = path2.endsWith("/") ? path2 : `${path2}/`;
+    return this.normalizeS3Path(directoryPath, {
+      preserveTrailingSlash: true
+    });
+  }
+  isRootPath(path2) {
+    return path2 === "." || path2 === "/";
+  }
+  toDirectoryStats(lastModified) {
+    const timestamp = toDate(lastModified);
+    return {
+      size: 0,
+      isDirectory: true,
+      isFile: false,
+      birthtime: timestamp,
+      atime: timestamp,
+      mtime: timestamp,
+      ctime: timestamp,
+      mode: 0,
+      uid: 0,
+      gid: 0
+    };
+  }
+  async headDirectoryMarker(path2) {
+    const directoryKey = this.toDirectoryKey(path2);
+    if (!directoryKey) {
+      return null;
+    }
+    try {
+      return await this.head(directoryKey);
+    } catch (error) {
+      if (error instanceof FileNotFoundError) {
+        return null;
+      }
+      throw error;
+    }
+  }
+  async directoryHasChildren(directoryKey) {
+    const listing = await this.client.send(
+      new ListObjectsV2Command({
+        Bucket: this.bucket,
+        Prefix: directoryKey,
+        MaxKeys: 2
+      })
+    );
+    return (listing.Contents || []).some(
+      (entry) => entry.Key && entry.Key !== directoryKey
+    );
+  }
+  getDefaultDownloadTarget(remotePath) {
+    const normalizedRemotePath = this.normalizeS3Path(remotePath, {
+      preserveTrailingSlash: remotePath.endsWith("/")
+    });
+    const segments = normalizedRemotePath.split("/").filter(Boolean);
+    if (!segments.length) {
+      throw new InvalidPathError(remotePath, "s3");
+    }
+    if (segments.some(
+      (segment) => segment === ".." || segment === "~" || segment.startsWith("~") || /^[A-Za-z]:/.test(segment)
+    )) {
+      throw new InvalidPathError(remotePath, "s3");
+    }
+    const baseDir = resolve(this.cacheDir);
+    const target = resolve(baseDir, ...segments);
+    const targetRelativePath = relative(baseDir, target);
+    if (!targetRelativePath || targetRelativePath === ".." || targetRelativePath.startsWith(`..${sep}`)) {
+      throw new InvalidPathError(remotePath, "s3");
+    }
+    return target;
+  }
+  async bodyToBuffer(body) {
+    if (!body) return Buffer.alloc(0);
+    if (Buffer.isBuffer(body)) return body;
+    if (body instanceof Uint8Array) return Buffer.from(body);
+    if (typeof body.transformToByteArray === "function") {
+      const bytes = await body.transformToByteArray();
+      return Buffer.from(bytes);
+    }
+    if (typeof body.getReader === "function") {
+      const reader = body.getReader();
+      const chunks = [];
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        if (value) chunks.push(Buffer.from(value));
+      }
+      return Buffer.concat(chunks);
+    }
+    if (Symbol.asyncIterator in Object(body)) {
+      const chunks = [];
+      for await (const chunk of body) {
+        chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+      }
+      return Buffer.concat(chunks);
+    }
+    return Buffer.from(String(body));
+  }
+  async head(key) {
+    try {
+      return await this.client.send(
+        new HeadObjectCommand({
+          Bucket: this.bucket,
+          Key: key
+        })
+      );
+    } catch (error) {
+      if (error?.$metadata?.httpStatusCode === 404 || error?.name === "NotFound") {
+        throw new FileNotFoundError(key, "s3");
+      }
+      if (error?.$metadata?.httpStatusCode === 403) {
+        throw new PermissionError(key, "s3");
+      }
+      throw new FilesystemError(
+        `Failed to stat S3 object: ${error instanceof Error ? error.message : String(error)}`,
+        error?.name || "UNKNOWN",
+        key,
+        "s3"
+      );
+    }
+  }
+  toFileInfo(key, entry, isDirectory2 = false) {
+    const normalized = key.replace(/\/$/, "");
+    const name = normalized.split("/").pop() || normalized;
+    const extension = isDirectory2 ? void 0 : extname(normalized).replace(/^\./, "");
+    const mimeType = isDirectory2 ? void 0 : MIME_TYPES[extname(normalized).toLowerCase()] || "application/octet-stream";
+    return {
+      name,
+      path: normalized,
+      size: Number(entry.Size || 0),
+      isDirectory: isDirectory2,
+      lastModified: toDate(entry.LastModified),
+      mimeType,
+      extension
+    };
+  }
+  async exists(path2) {
+    if (this.isRootPath(path2)) {
+      return true;
+    }
+    const key = this.normalizeS3Path(path2, {
+      preserveTrailingSlash: path2.endsWith("/")
+    });
+    if (!key) {
+      return true;
+    }
+    try {
+      await this.head(key);
+      return true;
+    } catch (error) {
+      if (error instanceof FileNotFoundError) {
+        const directoryMarker = await this.headDirectoryMarker(path2);
+        if (directoryMarker) {
+          return true;
+        }
+        const listing = await this.client.send(
+          new ListObjectsV2Command({
+            Bucket: this.bucket,
+            Prefix: `${key}/`,
+            MaxKeys: 1
+          })
+        );
+        return Boolean((listing.Contents || []).length);
+      }
+      throw error;
+    }
+  }
+  async read(path2, options = {}) {
+    const key = this.normalizeS3Path(path2, {
+      preserveTrailingSlash: path2.endsWith("/")
+    });
+    try {
+      const response = await this.client.send(
+        new GetObjectCommand({
+          Bucket: this.bucket,
+          Key: key
+        })
+      );
+      const buffer = await this.bodyToBuffer(response.Body);
+      if (options.raw) {
+        return buffer;
+      }
+      return buffer.toString(options.encoding || "utf8");
+    } catch (error) {
+      if (error?.$metadata?.httpStatusCode === 404 || error?.name === "NoSuchKey") {
+        throw new FileNotFoundError(path2, "s3");
+      }
+      if (error?.$metadata?.httpStatusCode === 403) {
+        throw new PermissionError(path2, "s3");
+      }
+      throw new FilesystemError(
+        `Failed to read S3 object: ${error instanceof Error ? error.message : String(error)}`,
+        error?.name || "UNKNOWN",
+        path2,
+        "s3"
+      );
+    }
+  }
+  async write(path2, content, options = {}) {
+    const key = this.normalizeS3Path(path2, {
+      preserveTrailingSlash: path2.endsWith("/")
+    });
+    const body = typeof content === "string" ? Buffer.from(content, options.encoding || "utf8") : content;
+    try {
+      await this.client.send(
+        new PutObjectCommand({
+          Bucket: this.bucket,
+          Key: key,
+          Body: body,
+          ContentType: MIME_TYPES[extname(key).toLowerCase()] || "application/octet-stream"
+        })
+      );
+    } catch (error) {
+      if (error?.$metadata?.httpStatusCode === 403) {
+        throw new PermissionError(path2, "s3");
+      }
+      throw new FilesystemError(
+        `Failed to write S3 object: ${error instanceof Error ? error.message : String(error)}`,
+        error?.name || "UNKNOWN",
+        path2,
+        "s3"
+      );
+    }
+  }
+  async delete(path2) {
+    let key = this.normalizeS3Path(path2, {
+      preserveTrailingSlash: path2.endsWith("/")
+    });
+    try {
+      if (key) {
+        try {
+          const stats = await this.getStats(path2);
+          if (stats.isDirectory) {
+            key = this.toDirectoryKey(path2);
+            if (key && await this.directoryHasChildren(key)) {
+              throw new DirectoryNotEmptyError(path2, "s3");
+            }
+          }
+        } catch (error) {
+          if (!(error instanceof FileNotFoundError)) {
+            throw error;
+          }
+        }
+      }
+      await this.client.send(
+        new DeleteObjectCommand({
+          Bucket: this.bucket,
+          Key: key
+        })
+      );
+    } catch (error) {
+      if (error instanceof FilesystemError) {
+        throw error;
+      }
+      throw new FilesystemError(
+        `Failed to delete S3 object: ${error instanceof Error ? error.message : String(error)}`,
+        error?.name || "UNKNOWN",
+        path2,
+        "s3"
+      );
+    }
+  }
+  async copy(sourcePath, destPath) {
+    const sourceKey = this.normalizeS3Path(sourcePath, {
+      preserveTrailingSlash: sourcePath.endsWith("/")
+    });
+    const destKey = this.normalizeS3Path(destPath, {
+      preserveTrailingSlash: destPath.endsWith("/")
+    });
+    try {
+      await this.client.send(
+        new CopyObjectCommand({
+          Bucket: this.bucket,
+          Key: destKey,
+          CopySource: toCopySource(this.bucket, sourceKey)
+        })
+      );
+    } catch (error) {
+      throw new FilesystemError(
+        `Failed to copy S3 object: ${error instanceof Error ? error.message : String(error)}`,
+        error?.name || "UNKNOWN",
+        destPath,
+        "s3"
+      );
+    }
+  }
+  async move(sourcePath, destPath) {
+    await this.copy(sourcePath, destPath);
+    await this.delete(sourcePath);
+  }
+  async createDirectory(path2, _options = {}) {
+    if (!this.toDirectoryKey(path2)) {
+      return;
+    }
+    const directoryPath = path2.endsWith("/") ? path2 : `${path2}/`;
+    await this.write(directoryPath, Buffer.alloc(0));
+  }
+  async list(path2, options = {}) {
+    const prefix = this.normalizeS3Path(path2, {
+      preserveTrailingSlash: path2.endsWith("/")
+    });
+    const prefixWithSlash = prefix ? `${prefix.replace(/\/+$/, "")}/` : "";
+    const items = [];
+    const seenDirectories = /* @__PURE__ */ new Set();
+    const addDirectory = (key, lastModified) => {
+      const directoryKey = key.endsWith("/") ? key : `${key}/`;
+      const normalized = directoryKey.replace(/\/$/, "");
+      if (!normalized || seenDirectories.has(normalized)) {
+        return;
+      }
+      seenDirectories.add(normalized);
+      items.push(
+        this.toFileInfo(directoryKey, { LastModified: lastModified }, true)
+      );
+    };
+    let continuationToken;
+    do {
+      const response = await this.client.send(
+        new ListObjectsV2Command({
+          Bucket: this.bucket,
+          Prefix: prefixWithSlash,
+          Delimiter: options.recursive ? void 0 : "/",
+          ContinuationToken: continuationToken
+        })
+      );
+      for (const prefixEntry of response.CommonPrefixes || []) {
+        if (prefixEntry.Prefix) {
+          addDirectory(prefixEntry.Prefix);
+        }
+      }
+      for (const entry of response.Contents || []) {
+        if (!entry.Key || entry.Key === prefixWithSlash) continue;
+        const relative2 = prefixWithSlash ? entry.Key.slice(prefixWithSlash.length) : entry.Key;
+        if (entry.Key.endsWith("/")) {
+          addDirectory(entry.Key, entry.LastModified);
+          continue;
+        }
+        if (!options.recursive && relative2.includes("/")) {
+          const directory = relative2.split("/")[0];
+          addDirectory(`${prefixWithSlash}${directory}`, entry.LastModified);
+          continue;
+        }
+        items.push(this.toFileInfo(entry.Key, entry));
+      }
+      continuationToken = response.IsTruncated ? response.NextContinuationToken : void 0;
+    } while (continuationToken);
+    return items.filter((item) => {
+      if (!options.filter) return true;
+      const matcher = typeof options.filter === "string" ? new RegExp(options.filter) : options.filter;
+      return matcher.test(item.name);
+    });
+  }
+  async getStats(path2) {
+    if (this.isRootPath(path2)) {
+      return this.toDirectoryStats();
+    }
+    const key = this.normalizeS3Path(path2, {
+      preserveTrailingSlash: path2.endsWith("/")
+    });
+    if (!key) {
+      return this.toDirectoryStats();
+    }
+    try {
+      const response = await this.head(key);
+      return {
+        size: Number(response.ContentLength || 0),
+        isDirectory: key.endsWith("/"),
+        isFile: !key.endsWith("/"),
+        birthtime: toDate(response.LastModified),
+        atime: toDate(response.LastModified),
+        mtime: toDate(response.LastModified),
+        ctime: toDate(response.LastModified),
+        mode: 0,
+        uid: 0,
+        gid: 0
+      };
+    } catch (error) {
+      if (error instanceof FileNotFoundError) {
+        const directoryMarker = await this.headDirectoryMarker(path2);
+        if (directoryMarker) {
+          return this.toDirectoryStats(directoryMarker.LastModified);
+        }
+        const listing = await this.client.send(
+          new ListObjectsV2Command({
+            Bucket: this.bucket,
+            Prefix: `${key.replace(/\/+$/, "")}/`,
+            MaxKeys: 1
+          })
+        );
+        if ((listing.Contents || []).length) {
+          const [firstEntry] = listing.Contents || [];
+          return this.toDirectoryStats(firstEntry?.LastModified);
+        }
+      }
+      throw error;
+    }
+  }
+  async getMimeType(path2) {
+    const key = this.normalizeS3Path(path2, {
+      preserveTrailingSlash: path2.endsWith("/")
+    });
+    try {
+      const response = await this.head(key);
+      return response.ContentType || MIME_TYPES[extname(key).toLowerCase()] || "application/octet-stream";
+    } catch (error) {
+      if (error instanceof FileNotFoundError) {
+        return MIME_TYPES[extname(key).toLowerCase()] || "application/octet-stream";
+      }
+      throw error;
+    }
+  }
+  async upload(localPath, remotePath, _options = {}) {
+    const { readFile: readFile2 } = await import("node:fs/promises");
+    await this.write(remotePath, await readFile2(localPath));
+  }
+  async download(remotePath, localPath, _options = {}) {
+    const buffer = await this.read(remotePath, { raw: true });
+    const target = localPath || this.getDefaultDownloadTarget(remotePath);
+    await mkdir(dirname(target), { recursive: true });
+    await writeFile(target, buffer);
+    return target;
+  }
+  async getCapabilities() {
+    return {
+      streaming: false,
+      atomicOperations: false,
+      versioning: false,
+      sharing: false,
+      realTimeSync: false,
+      offlineCapable: false,
+      supportedOperations: [
+        "exists",
+        "read",
+        "write",
+        "delete",
+        "copy",
+        "move",
+        "createDirectory",
+        "list",
+        "getStats",
+        "getMimeType",
+        "upload",
+        "download"
+      ]
+    };
+  }
+}
+const s3 = /* @__PURE__ */ Object.freeze(/* @__PURE__ */ Object.defineProperty({
+  __proto__: null,
+  S3FilesystemProvider
+}, Symbol.toStringTag, { value: "Module" }));
+const SECRET_KEY_FRAGMENTS = [
+  "apikey",
+  "api_key",
+  "clientsecret",
+  "client_secret",
+  "credential",
+  "privatekey",
+  "private_key",
+  "secret",
+  "password",
+  "token"
+];
+const EXACT_SECRET_KEYS = /* @__PURE__ */ new Set(["serviceaccountkey", "accesskeyid"]);
+function looksLikeSecret(key) {
+  const normalized = key.toLowerCase();
+  if (EXACT_SECRET_KEYS.has(normalized)) return true;
+  return SECRET_KEY_FRAGMENTS.some((fragment) => normalized.includes(fragment));
+}
+function redactFilesystemConfig(value) {
+  return redactSecrets(value, /* @__PURE__ */ new WeakSet(), /* @__PURE__ */ new WeakMap());
+}
+function redactSecrets(value, inProgress, done) {
+  if (!value || typeof value !== "object") return value;
+  const obj = value;
+  if (done.has(obj)) return done.get(obj);
+  if (inProgress.has(obj)) return "[circular]";
+  inProgress.add(obj);
+  let result;
+  if (Array.isArray(value)) {
+    result = value.map((item) => redactSecrets(item, inProgress, done));
+  } else {
+    result = Object.fromEntries(
+      Object.entries(value).map(([key, item]) => [
+        key,
+        looksLikeSecret(key) ? "[redacted]" : redactSecrets(item, inProgress, done)
+      ])
+    );
+  }
+  inProgress.delete(obj);
+  done.set(obj, result);
+  return result;
+}
+const providers = /* @__PURE__ */ new Map();
+function registerProvider(type, factory2) {
+  providers.set(type, factory2);
+}
+function getAvailableProviders() {
+  return Array.from(providers.keys());
+}
+function validateOptions(options) {
+  if (!options) {
+    throw new FilesystemError("Provider options are required", "EINVAL");
+  }
+  const type = options.type || "local";
+  switch (type) {
+    case "local":
+      break;
+    case "s3": {
+      const s3Opts = options;
+      if (!s3Opts.region) {
+        throw new FilesystemError("S3 provider requires region", "EINVAL");
+      }
+      if (!s3Opts.bucket) {
+        throw new FilesystemError("S3 provider requires bucket", "EINVAL");
+      }
+      break;
+    }
+    case "gdrive": {
+      const gdriveOpts = options;
+      const hasOAuth2 = gdriveOpts.clientId && gdriveOpts.clientSecret && gdriveOpts.refreshToken;
+      const hasServiceAccount = !!gdriveOpts.serviceAccountKey;
+      const hasAccessToken = !!gdriveOpts.accessToken;
+      if (!hasOAuth2 && !hasServiceAccount && !hasAccessToken) {
+        throw new FilesystemError(
+          "Google Drive provider requires OAuth2 credentials (clientId + clientSecret + refreshToken), a serviceAccountKey, or an accessToken",
+          "EINVAL"
+        );
+      }
+      break;
+    }
+    case "webdav": {
+      const webdavOpts = options;
+      if (!webdavOpts.baseUrl) {
+        throw new FilesystemError("WebDAV provider requires baseUrl", "EINVAL");
+      }
+      if (!webdavOpts.username) {
+        throw new FilesystemError(
+          "WebDAV provider requires username",
+          "EINVAL"
+        );
+      }
+      if (!webdavOpts.password) {
+        throw new FilesystemError(
+          "WebDAV provider requires password",
+          "EINVAL"
+        );
+      }
+      break;
+    }
+    case "browser-storage":
+      break;
+    default:
+      throw new FilesystemError(`Unknown provider type: ${type}`, "EINVAL");
+  }
+}
+function detectProviderType(options) {
+  if (options.type) {
+    return options.type;
+  }
+  if ("region" in options && "bucket" in options) {
+    return "s3";
+  }
+  if ("clientId" in options && "clientSecret" in options || "serviceAccountKey" in options || "accessToken" in options) {
+    return "gdrive";
+  }
+  if ("baseUrl" in options && "username" in options) {
+    return "webdav";
+  }
+  if ("databaseName" in options || "storageQuota" in options) {
+    return "browser-storage";
+  }
+  if (typeof globalThis !== "undefined") {
+    if (typeof globalThis.window !== "undefined" && typeof globalThis.indexedDB !== "undefined") {
+      return "browser-storage";
+    }
+    if (globalThis.process?.versions?.node) {
+      return "local";
+    }
+  }
+  return "local";
+}
+async function getFilesystem(options = {}) {
+  validateOptions(options);
+  const type = detectProviderType(options);
+  const providerFactory = providers.get(type);
+  if (!providerFactory) {
+    throw new FilesystemError(
+      `Provider '${type}' is not registered. Available providers: ${getAvailableProviders().join(", ")}`,
+      "ENOTFOUND"
+    );
+  }
+  try {
+    const ProviderClass = await providerFactory();
+    return new ProviderClass(options);
+  } catch (error) {
+    throw new FilesystemError(
+      `Failed to create '${type}' provider: ${error instanceof Error ? error.message : String(error)}`,
+      "ENOENT",
+      void 0,
+      type
+    );
+  }
+}
+async function initializeProviders() {
+  registerProvider("local", async () => {
+    const { LocalFilesystemProvider: LocalFilesystemProvider2 } = await Promise.resolve().then(() => local);
+    return LocalFilesystemProvider2;
+  });
+  registerProvider("s3", async () => {
+    const { S3FilesystemProvider: S3FilesystemProvider2 } = await Promise.resolve().then(() => s3);
+    return S3FilesystemProvider2;
+  });
+  registerProvider("gdrive", async () => {
+    const { GoogleDriveProvider: GoogleDriveProvider2 } = await Promise.resolve().then(() => gdrive);
+    return GoogleDriveProvider2;
+  });
+}
+function isProviderAvailable(type) {
+  return providers.has(type);
+}
+function getProviderInfo(type) {
+  const descriptions = {
+    local: "Local filesystem provider using Node.js fs module",
+    s3: "S3-compatible provider supporting AWS S3, MinIO, and other S3-compatible services",
+    gdrive: "Google Drive provider using Google Drive API v3",
+    webdav: "WebDAV provider supporting Nextcloud, ownCloud, Apache mod_dav, and other WebDAV servers",
+    "browser-storage": "Browser storage provider using IndexedDB for app file management"
+  };
+  const requiredOptions = {
+    local: [],
+    s3: ["region", "bucket"],
+    gdrive: [],
+    webdav: ["baseUrl", "username", "password"],
+    "browser-storage": []
+  };
+  return {
+    available: isProviderAvailable(type),
+    description: descriptions[type] || "Unknown provider",
+    requiredOptions: requiredOptions[type] || []
+  };
+}
+const factory = /* @__PURE__ */ Object.freeze(/* @__PURE__ */ Object.defineProperty({
+  __proto__: null,
+  getAvailableProviders,
+  getFilesystem,
+  getProviderInfo,
+  initializeProviders,
+  isProviderAvailable,
+  registerProvider
+}, Symbol.toStringTag, { value: "Module" }));
+Promise.resolve().then(() => factory).then(({ initializeProviders: initializeProviders2 }) => {
+  initializeProviders2().catch(() => {
+  });
+});
+const PACKAGE_VERSION_INITIALIZED = true;
+export {
+  DirectoryNotEmptyError,
+  FileNotFoundError,
+  FilesystemAdapter,
+  FilesystemError,
+  GoogleDriveProvider,
+  InvalidPathError,
+  LocalFilesystemProvider,
+  PACKAGE_VERSION_INITIALIZED,
+  PermissionError,
+  S3FilesystemProvider,
+  addRateLimit,
+  factory as default,
+  download,
+  downloadFileWithCache,
+  ensureDirectoryExists,
+  fetchBuffer,
+  fetchJSON,
+  fetchText,
+  fetchToFile,
+  getAvailableProviders,
+  getCached,
+  getFilesystem,
+  getMimeType,
+  getProviderInfo,
+  getRateLimit,
+  initializeProviders,
+  isDirectory,
+  isFile,
+  isProviderAvailable,
+  listFiles,
+  redactFilesystemConfig,
+  registerProvider,
+  setCached,
+  upload,
+  writeResponseToFile
+};
+//# sourceMappingURL=index.js.map