@mastra/s3 0.0.0-feat-change-lifecycle-20260212011237

package/dist/index.cjs

@@ -0,0 +1,593 @@
+'use strict';
+
+var clientS3 = require('@aws-sdk/client-s3');
+var workspace = require('@mastra/core/workspace');
+
+// src/filesystem/index.ts
+var MIME_TYPES = {
+  // Text
+  ".txt": "text/plain",
+  ".md": "text/markdown",
+  ".markdown": "text/markdown",
+  ".html": "text/html",
+  ".htm": "text/html",
+  ".css": "text/css",
+  ".csv": "text/csv",
+  ".xml": "text/xml",
+  // Code
+  ".js": "text/javascript",
+  ".mjs": "text/javascript",
+  ".ts": "text/typescript",
+  ".tsx": "text/typescript",
+  ".jsx": "text/javascript",
+  ".json": "application/json",
+  ".yaml": "text/yaml",
+  ".yml": "text/yaml",
+  ".py": "text/x-python",
+  ".rb": "text/x-ruby",
+  ".sh": "text/x-shellscript",
+  ".bash": "text/x-shellscript",
+  // Images
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".gif": "image/gif",
+  ".svg": "image/svg+xml",
+  ".webp": "image/webp",
+  ".ico": "image/x-icon",
+  // Documents
+  ".pdf": "application/pdf",
+  // Archives
+  ".zip": "application/zip",
+  ".gz": "application/gzip",
+  ".tar": "application/x-tar"
+};
+function getMimeType(path) {
+  const ext = path.toLowerCase().match(/\.[^.]+$/)?.[0];
+  return ext ? MIME_TYPES[ext] ?? "application/octet-stream" : "application/octet-stream";
+}
+function isNotFoundError(error) {
+  if (!error || typeof error !== "object" || !("name" in error)) return false;
+  const name = error.name;
+  return name === "NotFound" || name === "NoSuchKey" || name === "404";
+}
+function isAccessDeniedError(error) {
+  if (!error || typeof error !== "object") return false;
+  const err = error;
+  return err.name === "AccessDenied" || err.$metadata?.httpStatusCode === 403;
+}
+function trimSlashes(s) {
+  let start = 0;
+  let end = s.length;
+  while (start < end && s[start] === "/") start++;
+  while (end > start && s[end - 1] === "/") end--;
+  return s.slice(start, end);
+}
+var S3Filesystem = class extends workspace.MastraFilesystem {
+  id;
+  name = "S3Filesystem";
+  provider = "s3";
+  readOnly;
+  status = "pending";
+  // Display metadata for UI
+  displayName;
+  icon = "s3";
+  description;
+  bucket;
+  region;
+  accessKeyId;
+  secretAccessKey;
+  endpoint;
+  forcePathStyle;
+  prefix;
+  _client = null;
+  constructor(options) {
+    super({ ...options, name: "S3Filesystem" });
+    this.id = options.id ?? `s3-fs-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
+    this.bucket = options.bucket;
+    this.region = options.region;
+    this.accessKeyId = options.accessKeyId;
+    this.secretAccessKey = options.secretAccessKey;
+    this.endpoint = options.endpoint;
+    this.forcePathStyle = options.forcePathStyle ?? !!options.endpoint;
+    this.prefix = options.prefix ? trimSlashes(options.prefix) + "/" : "";
+    this.icon = options.icon ?? this.detectIconFromEndpoint(options.endpoint);
+    this.displayName = options.displayName ?? this.getDefaultDisplayName(this.icon);
+    this.description = options.description;
+    this.readOnly = options.readOnly;
+  }
+  /**
+   * Get mount configuration for E2B sandbox.
+   * Returns S3-compatible config that works with s3fs-fuse.
+   */
+  getMountConfig() {
+    const config = {
+      type: "s3",
+      bucket: this.bucket,
+      region: this.region,
+      endpoint: this.endpoint
+    };
+    if (this.accessKeyId && this.secretAccessKey) {
+      config.accessKeyId = this.accessKeyId;
+      config.secretAccessKey = this.secretAccessKey;
+    }
+    if (this.readOnly) {
+      config.readOnly = true;
+    }
+    return config;
+  }
+  /**
+   * Get filesystem info for status reporting.
+   */
+  getInfo() {
+    return {
+      id: this.id,
+      name: this.name,
+      provider: this.provider,
+      status: this.status,
+      error: this.error,
+      readOnly: this.readOnly,
+      icon: this.icon,
+      metadata: {
+        bucket: this.bucket,
+        region: this.region,
+        ...this.endpoint && { endpoint: this.endpoint },
+        ...this.prefix && { prefix: this.prefix }
+      }
+    };
+  }
+  /**
+   * Handle an error, checking for access denied and updating status accordingly.
+   * Returns the error for re-throwing.
+   */
+  handleError(error) {
+    if (isAccessDeniedError(error)) {
+      this.status = "error";
+      this.error = "Access denied - check credentials and bucket permissions";
+    }
+    return error;
+  }
+  /**
+   * Get instructions describing this S3 filesystem.
+   * Used by agents to understand storage semantics.
+   */
+  getInstructions() {
+    const providerName = this.displayName || "S3";
+    const access = this.readOnly ? "Read-only" : "Persistent";
+    return `${providerName} storage in bucket "${this.bucket}". ${access} storage - files are retained across sessions.`;
+  }
+  /**
+   * Detect the appropriate icon based on the S3 endpoint.
+   */
+  detectIconFromEndpoint(endpoint) {
+    if (!endpoint) {
+      return "aws-s3";
+    }
+    let hostname;
+    try {
+      const url = new URL(endpoint);
+      hostname = url.hostname.toLowerCase();
+    } catch {
+      hostname = endpoint.toLowerCase();
+    }
+    if (hostname === "r2.cloudflarestorage.com" || hostname.endsWith(".r2.cloudflarestorage.com") || hostname.endsWith(".cloudflare.com")) {
+      return "r2";
+    }
+    if (hostname === "storage.googleapis.com" || hostname.endsWith(".storage.googleapis.com") || hostname.endsWith(".googleapis.com")) {
+      return "gcs";
+    }
+    if (hostname === "blob.core.windows.net" || hostname.endsWith(".blob.core.windows.net") || hostname.endsWith(".azure.com")) {
+      return "azure";
+    }
+    if (hostname.includes("minio")) {
+      return "minio";
+    }
+    return "s3";
+  }
+  /**
+   * Get a user-friendly display name based on the icon/provider.
+   */
+  getDefaultDisplayName(icon) {
+    switch (icon) {
+      case "aws-s3":
+        return "AWS S3";
+      case "r2":
+      case "cloudflare":
+      case "cloudflare-r2":
+        return "Cloudflare R2";
+      case "gcs":
+      case "google-cloud":
+      case "google-cloud-storage":
+        return "Google Cloud Storage";
+      case "azure":
+      case "azure-blob":
+        return "Azure Blob";
+      case "minio":
+        return "MinIO";
+      case "s3":
+        return "S3";
+      default:
+        return void 0;
+    }
+  }
+  getClient() {
+    if (this._client) return this._client;
+    const hasCredentials = this.accessKeyId && this.secretAccessKey;
+    this._client = new clientS3.S3Client({
+      region: this.region,
+      credentials: hasCredentials ? {
+        accessKeyId: this.accessKeyId,
+        secretAccessKey: this.secretAccessKey
+      } : (
+        // Anonymous access for public buckets - use empty credentials
+        // to prevent SDK from trying to find credentials elsewhere
+        { accessKeyId: "", secretAccessKey: "" }
+      ),
+      endpoint: this.endpoint,
+      forcePathStyle: this.forcePathStyle,
+      // Skip signing for anonymous access (public buckets).
+      // No-op signer passes the request through unsigned. Uses `any` because
+      // the correct type (HttpRequest from @smithy/types) is not a direct dependency.
+      ...hasCredentials ? {} : { signer: { sign: async (request) => request } }
+    });
+    return this._client;
+  }
+  /**
+   * Ensure the filesystem is initialized and return the S3 client.
+   * Uses base class ensureReady() for status management, then returns client.
+   */
+  async getReadyClient() {
+    await this.ensureReady();
+    return this.getClient();
+  }
+  toKey(path) {
+    const cleanPath = path.replace(/^\/+/, "");
+    return this.prefix + cleanPath;
+  }
+  // ---------------------------------------------------------------------------
+  // File Operations
+  // ---------------------------------------------------------------------------
+  async readFile(path, options) {
+    const client = await this.getReadyClient();
+    try {
+      const response = await client.send(
+        new clientS3.GetObjectCommand({
+          Bucket: this.bucket,
+          Key: this.toKey(path)
+        })
+      );
+      const body = await response.Body?.transformToByteArray();
+      if (!body) throw new workspace.FileNotFoundError(path);
+      const buffer = Buffer.from(body);
+      if (options?.encoding) {
+        return buffer.toString(options.encoding);
+      }
+      return buffer;
+    } catch (error) {
+      if (isNotFoundError(error)) {
+        throw new workspace.FileNotFoundError(path);
+      }
+      throw this.handleError(error);
+    }
+  }
+  async writeFile(path, content, options) {
+    const client = await this.getReadyClient();
+    if (options?.overwrite === false && await this.exists(path)) {
+      throw new workspace.FileExistsError(path);
+    }
+    const body = typeof content === "string" ? Buffer.from(content, "utf-8") : Buffer.from(content);
+    const contentType = getMimeType(path);
+    await client.send(
+      new clientS3.PutObjectCommand({
+        Bucket: this.bucket,
+        Key: this.toKey(path),
+        Body: body,
+        ContentType: contentType
+      })
+    );
+  }
+  async appendFile(path, content) {
+    let existing = "";
+    try {
+      existing = await this.readFile(path, { encoding: "utf-8" });
+    } catch (error) {
+      if (error instanceof workspace.FileNotFoundError) ; else {
+        throw error;
+      }
+    }
+    const appendContent = typeof content === "string" ? content : Buffer.from(content).toString("utf-8");
+    await this.writeFile(path, existing + appendContent);
+  }
+  async deleteFile(path, options) {
+    const isDir = await this.isDirectory(path);
+    if (isDir) {
+      await this.rmdir(path, { recursive: true, force: options?.force });
+      return;
+    }
+    const client = await this.getReadyClient();
+    try {
+      await client.send(
+        new clientS3.DeleteObjectCommand({
+          Bucket: this.bucket,
+          Key: this.toKey(path)
+        })
+      );
+    } catch (error) {
+      if (options?.force) return;
+      if (isNotFoundError(error)) {
+        throw new workspace.FileNotFoundError(path);
+      }
+      throw this.handleError(error);
+    }
+  }
+  async copyFile(src, dest, options) {
+    const client = await this.getReadyClient();
+    if (options?.overwrite === false && await this.exists(dest)) {
+      throw new workspace.FileExistsError(dest);
+    }
+    try {
+      await client.send(
+        new clientS3.CopyObjectCommand({
+          Bucket: this.bucket,
+          CopySource: `${this.bucket}/${encodeURIComponent(this.toKey(src)).replace(/%2F/g, "/")}`,
+          Key: this.toKey(dest)
+        })
+      );
+    } catch (error) {
+      if (isNotFoundError(error)) {
+        throw new workspace.FileNotFoundError(src);
+      }
+      throw this.handleError(error);
+    }
+  }
+  async moveFile(src, dest, options) {
+    await this.copyFile(src, dest, options);
+    await this.deleteFile(src, { force: true });
+  }
+  // ---------------------------------------------------------------------------
+  // Directory Operations
+  // ---------------------------------------------------------------------------
+  async mkdir(_path, _options) {
+  }
+  async rmdir(path, options) {
+    if (!options?.recursive) {
+      const entries = await this.readdir(path);
+      if (entries.length > 0) {
+        throw new Error(`Directory not empty: ${path}`);
+      }
+      return;
+    }
+    const client = await this.getReadyClient();
+    const prefix = this.toKey(path).replace(/\/$/, "") + "/";
+    let continuationToken;
+    do {
+      const listResponse = await client.send(
+        new clientS3.ListObjectsV2Command({
+          Bucket: this.bucket,
+          Prefix: prefix,
+          ContinuationToken: continuationToken
+        })
+      );
+      if (listResponse.Contents && listResponse.Contents.length > 0) {
+        const deleteResponse = await client.send(
+          new clientS3.DeleteObjectsCommand({
+            Bucket: this.bucket,
+            Delete: {
+              Objects: listResponse.Contents.filter((obj) => !!obj.Key).map((obj) => ({
+                Key: obj.Key
+              }))
+            }
+          })
+        );
+        if (deleteResponse.Errors && deleteResponse.Errors.length > 0) {
+          throw new Error(`Failed to delete ${deleteResponse.Errors.length} object(s) in ${path}`);
+        }
+      }
+      continuationToken = listResponse.NextContinuationToken;
+    } while (continuationToken);
+  }
+  async readdir(path, options) {
+    const client = await this.getReadyClient();
+    const prefix = this.toKey(path).replace(/\/$/, "");
+    const searchPrefix = prefix ? prefix + "/" : "";
+    const entries = [];
+    const seenDirs = /* @__PURE__ */ new Set();
+    let continuationToken;
+    do {
+      const response = await client.send(
+        new clientS3.ListObjectsV2Command({
+          Bucket: this.bucket,
+          Prefix: searchPrefix,
+          Delimiter: options?.recursive ? void 0 : "/",
+          ContinuationToken: continuationToken
+        })
+      );
+      if (response.Contents) {
+        for (const obj of response.Contents) {
+          const key = obj.Key;
+          if (!key || key === searchPrefix) continue;
+          const relativePath = key.slice(searchPrefix.length);
+          if (!relativePath) continue;
+          if (relativePath.endsWith("/")) {
+            const dirName = relativePath.slice(0, -1);
+            if (!seenDirs.has(dirName)) {
+              seenDirs.add(dirName);
+              entries.push({ name: dirName, type: "directory" });
+            }
+            continue;
+          }
+          const name = options?.recursive ? relativePath : relativePath.split("/")[0];
+          if (!name) continue;
+          if (options?.extension) {
+            const extensions = Array.isArray(options.extension) ? options.extension : [options.extension];
+            if (!extensions.some((ext) => name.endsWith(ext))) {
+              continue;
+            }
+          }
+          entries.push({
+            name,
+            type: "file",
+            size: obj.Size
+          });
+        }
+      }
+      if (response.CommonPrefixes) {
+        for (const prefixObj of response.CommonPrefixes) {
+          if (!prefixObj.Prefix) continue;
+          const dirName = prefixObj.Prefix.slice(searchPrefix.length).replace(/\/$/, "");
+          if (dirName && !seenDirs.has(dirName)) {
+            seenDirs.add(dirName);
+            entries.push({ name: dirName, type: "directory" });
+          }
+        }
+      }
+      continuationToken = response.NextContinuationToken;
+    } while (continuationToken);
+    return entries;
+  }
+  // ---------------------------------------------------------------------------
+  // Path Operations
+  // ---------------------------------------------------------------------------
+  async exists(path) {
+    const key = this.toKey(path);
+    if (!key) return true;
+    const client = await this.getReadyClient();
+    try {
+      await client.send(
+        new clientS3.HeadObjectCommand({
+          Bucket: this.bucket,
+          Key: key
+        })
+      );
+      return true;
+    } catch (error) {
+      if (!isNotFoundError(error)) throw this.handleError(error);
+    }
+    const response = await client.send(
+      new clientS3.ListObjectsV2Command({
+        Bucket: this.bucket,
+        Prefix: key.replace(/\/$/, "") + "/",
+        MaxKeys: 1
+      })
+    );
+    return (response.Contents?.length ?? 0) > 0;
+  }
+  async stat(path) {
+    const key = this.toKey(path);
+    if (!key) {
+      return {
+        name: "",
+        path,
+        type: "directory",
+        size: 0,
+        createdAt: /* @__PURE__ */ new Date(),
+        modifiedAt: /* @__PURE__ */ new Date()
+      };
+    }
+    const client = await this.getReadyClient();
+    try {
+      const response = await client.send(
+        new clientS3.HeadObjectCommand({
+          Bucket: this.bucket,
+          Key: key
+        })
+      );
+      const name = path.split("/").pop() ?? "";
+      return {
+        name,
+        path,
+        type: "file",
+        size: response.ContentLength ?? 0,
+        createdAt: response.LastModified ?? /* @__PURE__ */ new Date(),
+        modifiedAt: response.LastModified ?? /* @__PURE__ */ new Date()
+      };
+    } catch (error) {
+      if (!isNotFoundError(error)) throw this.handleError(error);
+      const isDir = await this.isDirectory(path);
+      if (isDir) {
+        const name = path.split("/").filter(Boolean).pop() ?? "";
+        return {
+          name,
+          path,
+          type: "directory",
+          size: 0,
+          createdAt: /* @__PURE__ */ new Date(),
+          modifiedAt: /* @__PURE__ */ new Date()
+        };
+      }
+      throw new workspace.FileNotFoundError(path);
+    }
+  }
+  async isFile(path) {
+    const key = this.toKey(path);
+    if (!key) return false;
+    const client = await this.getReadyClient();
+    try {
+      await client.send(
+        new clientS3.HeadObjectCommand({
+          Bucket: this.bucket,
+          Key: key
+        })
+      );
+      return true;
+    } catch (error) {
+      if (!isNotFoundError(error)) throw this.handleError(error);
+      return false;
+    }
+  }
+  async isDirectory(path) {
+    const key = this.toKey(path);
+    if (!key) return true;
+    const client = await this.getReadyClient();
+    const response = await client.send(
+      new clientS3.ListObjectsV2Command({
+        Bucket: this.bucket,
+        Prefix: key.replace(/\/$/, "") + "/",
+        MaxKeys: 1
+      })
+    );
+    return (response.Contents?.length ?? 0) > 0;
+  }
+  // ---------------------------------------------------------------------------
+  // Lifecycle (overrides base class protected methods)
+  // ---------------------------------------------------------------------------
+  /**
+   * Initialize the S3 client.
+   * Status management is handled by the base class.
+   */
+  async init() {
+    const client = this.getClient();
+    try {
+      await client.send(new clientS3.HeadBucketCommand({ Bucket: this.bucket }));
+    } catch (error) {
+      const statusCode = error.$metadata?.httpStatusCode;
+      const createError = (message2) => {
+        const err = new Error(message2);
+        if (statusCode) err.status = statusCode;
+        return err;
+      };
+      if (isAccessDeniedError(error)) {
+        throw createError(`Access denied to bucket "${this.bucket}" - check credentials and permissions`);
+      }
+      if (isNotFoundError(error)) {
+        throw createError(`Bucket "${this.bucket}" not found`);
+      }
+      const message = error instanceof Error ? error.message : String(error);
+      if (statusCode) {
+        throw createError(`Failed to access bucket "${this.bucket}" (HTTP ${statusCode}): ${message}`);
+      }
+      throw error;
+    }
+  }
+  /**
+   * Clean up the S3 client.
+   * Status management is handled by the base class.
+   */
+  async destroy() {
+    this._client = null;
+  }
+};
+
+exports.S3Filesystem = S3Filesystem;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map