@aigne/afs-gcs 1.11.0-beta.10

package/dist/index.mjs

@@ -0,0 +1,1206 @@
+import { AFSBaseProvider, AFSError, AFSNotFoundError, Actions, Delete, Explain, List, Meta, Read, Search, Stat, Write } from "@aigne/afs";
+import { camelize, optionalize, zodParse } from "@aigne/afs/utils/zod";
+import { joinURL } from "ufo";
+import { z } from "zod";
+import { Storage } from "@google-cloud/storage";
+
+//#region src/cache.ts
+/**
+* LRU Cache with TTL support
+*/
+var LRUCache = class {
+	cache = /* @__PURE__ */ new Map();
+	maxSize;
+	defaultTtl;
+	/**
+	* Create a new LRU cache
+	*
+	* @param maxSize - Maximum number of entries (default: 1000)
+	* @param defaultTtl - Default TTL in seconds (default: 60)
+	*/
+	constructor(maxSize = 1e3, defaultTtl = 60) {
+		this.maxSize = maxSize;
+		this.defaultTtl = defaultTtl;
+	}
+	/**
+	* Get a value from the cache
+	*
+	* @param key - Cache key
+	* @returns Cached value or undefined if not found/expired
+	*/
+	get(key) {
+		const entry = this.cache.get(key);
+		if (!entry) return;
+		if (Date.now() > entry.expiresAt) {
+			this.cache.delete(key);
+			return;
+		}
+		this.cache.delete(key);
+		this.cache.set(key, entry);
+		return entry.value;
+	}
+	/**
+	* Set a value in the cache
+	*
+	* @param key - Cache key
+	* @param value - Value to cache
+	* @param ttl - TTL in seconds (optional, uses default)
+	*/
+	set(key, value, ttl) {
+		if (this.cache.has(key)) this.cache.delete(key);
+		while (this.cache.size >= this.maxSize) {
+			const oldestKey = this.cache.keys().next().value;
+			if (oldestKey) this.cache.delete(oldestKey);
+		}
+		const expiresAt = Date.now() + (ttl ?? this.defaultTtl) * 1e3;
+		this.cache.set(key, {
+			value,
+			expiresAt
+		});
+	}
+	/**
+	* Delete a value from the cache
+	*
+	* @param key - Cache key
+	*/
+	delete(key) {
+		this.cache.delete(key);
+	}
+	/**
+	* Delete all entries matching a prefix
+	*
+	* @param prefix - Key prefix to match
+	*/
+	deleteByPrefix(prefix) {
+		for (const key of this.cache.keys()) if (key.startsWith(prefix)) this.cache.delete(key);
+	}
+	/**
+	* Clear all entries
+	*/
+	clear() {
+		this.cache.clear();
+	}
+	/**
+	* Get the number of entries in the cache
+	*/
+	get size() {
+		return this.cache.size;
+	}
+	/**
+	* Prune expired entries
+	*/
+	prune() {
+		const now = Date.now();
+		for (const [key, entry] of this.cache.entries()) if (now > entry.expiresAt) this.cache.delete(key);
+	}
+};
+/**
+* Create a cache key from bucket, prefix, and path
+*/
+function createCacheKey(bucket, prefix, path, suffix) {
+	const base = `${bucket}:${prefix}:${path}`;
+	return suffix ? `${base}:${suffix}` : base;
+}
+
+//#endregion
+//#region src/client.ts
+/**
+* GCS Client Factory
+*
+* Creates configured Google Cloud Storage clients.
+*/
+/**
+* Create a GCS Storage client from options
+*
+* @param options - AFSGCS options
+* @returns Configured Storage client
+*/
+function createGCSClient(options) {
+	const storageOptions = {};
+	if (options.projectId) storageOptions.projectId = options.projectId;
+	if (options.endpoint) storageOptions.apiEndpoint = options.endpoint;
+	if (options.keyFilename) storageOptions.keyFilename = options.keyFilename;
+	if (options.credentials) storageOptions.credentials = {
+		client_email: options.credentials.clientEmail,
+		private_key: options.credentials.privateKey
+	};
+	return new Storage(storageOptions);
+}
+
+//#endregion
+//#region src/errors.ts
+/**
+* GCS Provider Error Handling
+*
+* Maps GCS SDK errors to AFS error types.
+*/
+/**
+* AFS error codes
+*/
+const AFSErrorCode = {
+	ENTRY_NOT_FOUND: "ENTRY_NOT_FOUND",
+	MODULE_NOT_FOUND: "MODULE_NOT_FOUND",
+	PERMISSION_DENIED: "PERMISSION_DENIED",
+	AUTH_ERROR: "AUTH_ERROR",
+	RATE_LIMIT_EXCEEDED: "RATE_LIMIT_EXCEEDED",
+	INVALID_OPERATION: "INVALID_OPERATION",
+	ALREADY_EXISTS: "ALREADY_EXISTS",
+	SERVICE_UNAVAILABLE: "SERVICE_UNAVAILABLE",
+	UNKNOWN: "UNKNOWN"
+};
+/**
+* AFS Error class
+*/
+var AFSError$1 = class extends Error {
+	code;
+	retryAfter;
+	constructor(code, message, options) {
+		super(message);
+		this.name = "AFSError";
+		this.code = code;
+		this.retryAfter = options?.retryAfter;
+	}
+};
+/**
+* Custom GCS error class for internal use
+*/
+var GCSError = class extends Error {
+	constructor(message, code) {
+		super(message);
+		this.code = code;
+		this.name = "GCSError";
+	}
+};
+/**
+* Map GCS HTTP status codes to AFS error codes
+*/
+const STATUS_TO_AFS_ERROR = {
+	400: AFSErrorCode.INVALID_OPERATION,
+	401: AFSErrorCode.AUTH_ERROR,
+	403: AFSErrorCode.PERMISSION_DENIED,
+	404: AFSErrorCode.ENTRY_NOT_FOUND,
+	409: AFSErrorCode.ALREADY_EXISTS,
+	429: AFSErrorCode.RATE_LIMIT_EXCEEDED,
+	503: AFSErrorCode.SERVICE_UNAVAILABLE
+};
+/**
+* Map GCS error to AFS error
+*
+* @param error - GCS SDK error or generic error
+* @returns AFSError with appropriate error code
+*/
+function mapGCSError(error) {
+	if (error instanceof GCSError) return new AFSError$1(STATUS_TO_AFS_ERROR[error.code] ?? AFSErrorCode.UNKNOWN, error.message);
+	if (typeof error === "object" && error !== null && "code" in error) {
+		const err = error;
+		const statusCode = typeof err.code === "number" ? err.code : 500;
+		const message = err.message ?? "Unknown GCS error";
+		return new AFSError$1(STATUS_TO_AFS_ERROR[statusCode] ?? AFSErrorCode.UNKNOWN, message);
+	}
+	if (error instanceof Error) return new AFSError$1(AFSErrorCode.UNKNOWN, error.message);
+	return new AFSError$1(AFSErrorCode.UNKNOWN, String(error));
+}
+
+//#endregion
+//#region src/platform-ref.ts
+/**
+* Generate platform reference with GCP Console URL
+*
+* @param bucket - GCS bucket name
+* @param prefix - Object prefix/key (without leading slash)
+* @param isDirectory - Whether this is a directory (prefix)
+* @returns Platform reference with console URL
+*/
+function generatePlatformRef(bucket, prefix, isDirectory) {
+	if (isDirectory) return { consoleUrl: `https://console.cloud.google.com/storage/browser/${bucket}/${prefix.endsWith("/") ? prefix : prefix ? `${prefix}/` : ""}` };
+	return { consoleUrl: `https://console.cloud.google.com/storage/browser/_details/${bucket}/${encodeURIComponent(prefix).replace(/%2F/g, "/")}` };
+}
+
+//#endregion
+//#region src/types.ts
+/**
+* AFS GCS Provider Types
+*/
+/**
+* GCS bucket name validation regex
+* - 3-63 characters
+* - lowercase letters, numbers, hyphens, dots (but not consecutive dots)
+* - must start and end with letter or number
+*/
+const BUCKET_NAME_REGEX = /^[a-z0-9][a-z0-9.-]{1,61}[a-z0-9]$/;
+/**
+* Additional validation for bucket names
+*/
+function isValidBucketName(name) {
+	if (!BUCKET_NAME_REGEX.test(name)) return false;
+	if (name.includes("..")) return false;
+	if (name.includes("_")) return false;
+	return true;
+}
+/**
+* Zod schema for options validation
+*/
+const afsgcsOptionsSchema = camelize(z.object({
+	name: optionalize(z.string()),
+	description: optionalize(z.string()),
+	bucket: z.string().refine(isValidBucketName, "Invalid GCS bucket name"),
+	prefix: optionalize(z.string()),
+	projectId: optionalize(z.string()),
+	accessMode: optionalize(z.enum(["readonly", "readwrite"])),
+	endpoint: optionalize(z.string().url()),
+	keyFilename: optionalize(z.string()),
+	credentials: optionalize(z.object({
+		clientEmail: z.string(),
+		privateKey: z.string()
+	})),
+	cacheTtl: optionalize(z.number().int().min(0))
+}).strict());
+
+//#endregion
+//#region \0@oxc-project+runtime@0.108.0/helpers/decorate.js
+function __decorate(decorators, target, key, desc) {
+	var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+	if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+	else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+	return c > 3 && r && Object.defineProperty(target, key, r), r;
+}
+
+//#endregion
+//#region src/gcs-afs.ts
+/**
+* AFS GCS Provider
+*
+* GCS provider using AFSBaseProvider decorator routing pattern.
+* Provides access to Google Cloud Storage through AFS.
+*/
+/**
+* Default URL expiration time (1 hour)
+*/
+const DEFAULT_EXPIRES_IN = 3600;
+/**
+* Maximum expiration time (7 days)
+*/
+const MAX_EXPIRES_IN = 604800;
+/**
+* Maximum sources for compose operation
+*/
+const MAX_COMPOSE_SOURCES = 32;
+/**
+* AFSGCS Provider using Base Provider pattern
+*
+* Provides access to Google Cloud Storage through AFS.
+* Uses decorator routing (@List, @Read, @Write, @Delete, @Meta, @Actions).
+*
+* @example
+* ```typescript
+* const gcs = new AFSGCS({
+*   bucket: "my-bucket",
+*   prefix: "data",
+*   projectId: "my-project",
+* });
+*
+* // Mount to AFS
+* afs.mount(gcs);
+*
+* // List objects
+* const result = await afs.list("/modules/my-bucket/data");
+*
+* // Read object
+* const content = await afs.read("/modules/my-bucket/data/file.json");
+* ```
+*/
+var AFSGCS = class AFSGCS extends AFSBaseProvider {
+	name;
+	description;
+	accessMode;
+	options;
+	storage;
+	bucket;
+	listCache;
+	statCache;
+	constructor(options) {
+		super();
+		const { uri: _uri, token: _token, auth: _auth, ...cleanOptions } = options;
+		const parsed = afsgcsOptionsSchema.parse(cleanOptions);
+		this.options = {
+			...parsed,
+			bucket: parsed.bucket,
+			prefix: parsed.prefix ?? "",
+			accessMode: parsed.accessMode ?? "readonly"
+		};
+		this.name = parsed.name ?? parsed.bucket;
+		this.description = parsed.description ?? `GCS bucket: ${parsed.bucket}`;
+		this.accessMode = this.options.accessMode ?? "readonly";
+		this.storage = createGCSClient(this.options);
+		this.bucket = this.storage.bucket(parsed.bucket);
+		if (parsed.cacheTtl && parsed.cacheTtl > 0) {
+			this.listCache = new LRUCache(1e3, parsed.cacheTtl);
+			this.statCache = new LRUCache(5e3, parsed.cacheTtl);
+		}
+	}
+	/**
+	* Schema for configuration validation
+	*/
+	static schema() {
+		return afsgcsOptionsSchema;
+	}
+	/**
+	* Provider manifest for URI-based discovery
+	*/
+	static manifest() {
+		return {
+			name: "gcs",
+			description: "Google Cloud Storage bucket.\n- Browse, read, write, and delete objects; search by key prefix\n- Exec actions: `presign-download`, `presign-upload`, `compose` (concatenate objects), `rewrite` (copy with transform)\n- Path structure: `/{key-prefix}/{object-key}`",
+			uriTemplate: "gcs://{bucket}/{prefix+?}",
+			category: "cloud-storage",
+			schema: z.object({
+				bucket: z.string(),
+				prefix: z.string().optional(),
+				projectId: z.string().optional(),
+				keyFilename: z.string().optional()
+			}),
+			tags: [
+				"gcp",
+				"gcs",
+				"cloud",
+				"storage"
+			]
+		};
+	}
+	/**
+	* Load from configuration file
+	*/
+	static async load({ basePath, config } = {}) {
+		return new AFSGCS(zodParse(afsgcsOptionsSchema, config, { prefix: basePath }));
+	}
+	/**
+	* Build the full GCS key from a path
+	*/
+	buildGCSKey(path) {
+		const normalizedPath = path.replace(/^\/+/, "").replace(/\/+$/, "");
+		return this.options.prefix ? `${this.options.prefix}/${normalizedPath}` : normalizedPath;
+	}
+	/**
+	* Generate a unique ID for a GCS object
+	*/
+	generateId(key) {
+		const cleanKey = key.replace(/^\/+/, "");
+		return `gcs://${this.options.bucket}/${cleanKey}`;
+	}
+	/**
+	* Invalidate caches for a given path
+	*/
+	invalidateCache(path) {
+		if (this.statCache) {
+			const statKey = createCacheKey(this.options.bucket, this.options.prefix ?? "", path);
+			this.statCache.delete(statKey);
+		}
+		if (this.listCache) {
+			const parentPath = path.split("/").slice(0, -1).join("/") || "/";
+			const listPrefix = createCacheKey(this.options.bucket, this.options.prefix ?? "", parentPath);
+			this.listCache.deleteByPrefix(listPrefix);
+		}
+	}
+	/**
+	* Clear all caches
+	*/
+	clearCache() {
+		this.listCache?.clear();
+		this.statCache?.clear();
+	}
+	async listHandler(ctx) {
+		try {
+			const normalizedPath = (ctx.params.path ?? "").replace(/^\/+/, "").replace(/\/+$/, "");
+			const fullPrefix = this.options.prefix ? normalizedPath ? `${this.options.prefix}/${normalizedPath}/` : `${this.options.prefix}/` : normalizedPath ? `${normalizedPath}/` : "";
+			const maxChildren = ctx.options?.limit ?? 1e3;
+			if (this.listCache) {
+				const cacheKey = createCacheKey(this.options.bucket, this.options.prefix ?? "", normalizedPath, JSON.stringify(ctx.options ?? {}));
+				const cached = this.listCache.get(cacheKey);
+				if (cached) return cached;
+			}
+			const result = await this.listWithDelimiter(fullPrefix, normalizedPath, maxChildren);
+			if (this.listCache) {
+				const cacheKey = createCacheKey(this.options.bucket, this.options.prefix ?? "", normalizedPath, JSON.stringify(ctx.options ?? {}));
+				this.listCache.set(cacheKey, result);
+				if (this.statCache) for (const entry of result.data) {
+					const statKey = createCacheKey(this.options.bucket, this.options.prefix ?? "", entry.path);
+					this.statCache.set(statKey, entry);
+				}
+			}
+			return result;
+		} catch (error) {
+			if (error instanceof AFSNotFoundError) throw error;
+			throw mapGCSError(error);
+		}
+	}
+	/**
+	* List with delimiter (single level)
+	*/
+	async listWithDelimiter(prefix, basePath, maxChildren) {
+		const childEntries = [];
+		const bucketName = this.options.bucket;
+		const [files, , apiResponse] = await this.bucket.getFiles({
+			prefix,
+			delimiter: "/",
+			maxResults: maxChildren
+		});
+		const prefixes = apiResponse?.prefixes;
+		if (prefixes) for (const dirPrefix of prefixes) {
+			if (!dirPrefix) continue;
+			const dirName = dirPrefix.slice(prefix.length).replace(/\/$/, "");
+			if (!dirName) continue;
+			childEntries.push({
+				id: this.generateId(dirPrefix),
+				path: joinURL("/", basePath, dirName),
+				meta: {
+					kind: "afs:node",
+					childrenCount: -1,
+					platformRef: generatePlatformRef(bucketName, dirPrefix, true)
+				}
+			});
+			if (childEntries.length >= maxChildren) break;
+		}
+		for (const file of files) {
+			if (!file.name) continue;
+			if (file.name === prefix) continue;
+			if (file.name.endsWith("/")) {
+				const dirName = file.name.slice(prefix.length).replace(/\/$/, "");
+				if (!dirName) continue;
+				childEntries.push({
+					id: this.generateId(file.name),
+					path: joinURL("/", basePath, dirName),
+					updatedAt: file.metadata.updated ? new Date(file.metadata.updated) : void 0,
+					meta: {
+						kind: "afs:node",
+						childrenCount: -1,
+						platformRef: generatePlatformRef(bucketName, file.name, true)
+					}
+				});
+				if (childEntries.length >= maxChildren) break;
+				continue;
+			}
+			const fileName = file.name.slice(prefix.length);
+			if (!fileName || fileName.includes("/")) continue;
+			childEntries.push({
+				id: this.generateId(file.name),
+				path: joinURL("/", basePath, fileName),
+				updatedAt: file.metadata.updated ? new Date(file.metadata.updated) : void 0,
+				meta: {
+					size: file.metadata.size ? Number(file.metadata.size) : void 0,
+					contentType: file.metadata.contentType,
+					lastModified: file.metadata.updated,
+					etag: file.metadata.etag,
+					storageClass: file.metadata.storageClass,
+					platformRef: generatePlatformRef(bucketName, file.name, false)
+				}
+			});
+			if (childEntries.length >= maxChildren) break;
+		}
+		const selfPath = basePath ? basePath.startsWith("/") ? basePath : `/${basePath}` : "/";
+		if (childEntries.length === 0 && basePath) {
+			const key = this.options.prefix ? `${this.options.prefix}/${basePath}` : basePath;
+			const [fileExists] = await this.bucket.file(key).exists();
+			if (fileExists) return { data: [] };
+			const [dirExists] = await this.bucket.file(`${key}/`).exists();
+			if (!dirExists) throw new AFSNotFoundError(selfPath);
+		}
+		return { data: childEntries };
+	}
+	async listVersionsHandler(ctx) {
+		try {
+			const normalizedPath = ctx.params.path.replace(/^\/+/, "").replace(/\/+$/, "");
+			const key = this.options.prefix ? `${this.options.prefix}/${normalizedPath}` : normalizedPath;
+			const [files] = await this.bucket.getFiles({
+				prefix: key,
+				versions: true
+			});
+			const entries = [];
+			for (const versionFile of files) {
+				if (versionFile.name !== key) continue;
+				const generation = versionFile.metadata.generation;
+				if (!generation) continue;
+				const versionPath = joinURL("/", normalizedPath, "@versions", String(generation));
+				const isLive = !versionFile.metadata.timeDeleted;
+				entries.push({
+					id: `${this.generateId(key)}:${generation}`,
+					path: versionPath,
+					updatedAt: versionFile.metadata.timeCreated ? new Date(versionFile.metadata.timeCreated) : void 0,
+					meta: {
+						generation,
+						isLive,
+						timeCreated: versionFile.metadata.timeCreated,
+						size: versionFile.metadata.size ? Number(versionFile.metadata.size) : 0,
+						etag: versionFile.metadata.etag
+					}
+				});
+			}
+			return { data: entries };
+		} catch (error) {
+			throw mapGCSError(error);
+		}
+	}
+	async readHandler(ctx) {
+		try {
+			const key = this.buildGCSKey(ctx.params.path);
+			const normalizedOutputPath = ctx.path.startsWith("/") ? ctx.path : `/${ctx.path}`;
+			const bucketName = this.options.bucket;
+			if (!key) {
+				const [files$1, , apiResponse$1] = await this.bucket.getFiles({
+					prefix: this.options.prefix ? `${this.options.prefix}/` : "",
+					delimiter: "/",
+					maxResults: 1e3
+				});
+				const childrenCount = ((apiResponse$1?.prefixes)?.length ?? 0) + files$1.length;
+				return {
+					id: this.generateId("/"),
+					path: "/",
+					content: "",
+					meta: {
+						kind: "afs:node",
+						childrenCount,
+						platformRef: generatePlatformRef(bucketName, "", true)
+					}
+				};
+			}
+			const file = this.bucket.file(key);
+			const [exists] = await file.exists();
+			if (exists) {
+				const [metadata] = await file.getMetadata();
+				if (key.endsWith("/") || metadata.contentType === "application/x-directory") return {
+					id: this.generateId(key),
+					path: normalizedOutputPath,
+					content: "",
+					updatedAt: metadata.updated ? new Date(metadata.updated) : void 0,
+					meta: {
+						kind: "afs:node",
+						childrenCount: -1,
+						platformRef: generatePlatformRef(bucketName, key, true)
+					}
+				};
+				const [content] = await file.download();
+				return {
+					id: this.generateId(key),
+					path: normalizedOutputPath,
+					content: content.toString("utf-8"),
+					updatedAt: metadata.updated ? new Date(metadata.updated) : void 0,
+					meta: {
+						size: metadata.size ? Number(metadata.size) : void 0,
+						mimeType: metadata.contentType,
+						contentType: metadata.contentType,
+						lastModified: metadata.updated,
+						etag: metadata.etag
+					}
+				};
+			}
+			const [files, , apiResponse] = await this.bucket.getFiles({
+				prefix: `${key}/`,
+				delimiter: "/",
+				maxResults: 1e3
+			});
+			const prefixes = apiResponse?.prefixes;
+			if (files.length > 0 || prefixes && prefixes.length > 0) {
+				const childrenCount = (prefixes?.length ?? 0) + files.length;
+				return {
+					id: this.generateId(`${key}/`),
+					path: normalizedOutputPath,
+					content: "",
+					meta: {
+						kind: "afs:node",
+						childrenCount,
+						platformRef: generatePlatformRef(bucketName, key, true)
+					}
+				};
+			}
+			const dirMarker = this.bucket.file(`${key}/`);
+			const [dirExists] = await dirMarker.exists();
+			if (dirExists) {
+				const [dirMetadata] = await dirMarker.getMetadata();
+				return {
+					id: this.generateId(`${key}/`),
+					path: normalizedOutputPath,
+					content: "",
+					updatedAt: dirMetadata.updated ? new Date(dirMetadata.updated) : void 0,
+					meta: {
+						kind: "afs:node",
+						childrenCount: -1,
+						platformRef: generatePlatformRef(bucketName, key, true)
+					}
+				};
+			}
+			throw new AFSNotFoundError(`/${ctx.params.path}`);
+		} catch (error) {
+			if (error instanceof AFSError || error instanceof AFSNotFoundError) throw error;
+			throw mapGCSError(error);
+		}
+	}
+	async readVersionHandler(ctx) {
+		try {
+			const normalizedPath = ctx.params.path.replace(/^\/+/, "").replace(/\/+$/, "");
+			const key = this.options.prefix ? `${this.options.prefix}/${normalizedPath}` : normalizedPath;
+			const generation = ctx.params.generation;
+			const file = this.bucket.file(key, { generation: parseInt(generation, 10) });
+			const [exists] = await file.exists();
+			if (!exists) throw new AFSNotFoundError(`/${normalizedPath}/@versions/${generation}`);
+			const [content] = await file.download();
+			const [metadata] = await file.getMetadata();
+			return {
+				id: `${this.generateId(key)}:${generation}`,
+				path: ctx.path,
+				content: content.toString("utf-8"),
+				updatedAt: metadata.timeCreated ? new Date(metadata.timeCreated) : void 0,
+				meta: {
+					size: metadata.size ? Number(metadata.size) : void 0,
+					contentType: metadata.contentType,
+					timeCreated: metadata.timeCreated,
+					etag: metadata.etag,
+					generation: metadata.generation
+				}
+			};
+		} catch (error) {
+			if (error instanceof AFSNotFoundError) throw error;
+			throw mapGCSError(error);
+		}
+	}
+	async metaHandler(ctx) {
+		try {
+			const path = ctx.params.path ?? "";
+			const normalizedPath = path.replace(/^\/+/, "").replace(/\/+$/, "");
+			const key = this.options.prefix ? normalizedPath ? `${this.options.prefix}/${normalizedPath}` : this.options.prefix : normalizedPath;
+			const bucketName = this.options.bucket;
+			if (!key) {
+				const [files$1, , apiResponse] = await this.bucket.getFiles({
+					prefix: this.options.prefix ? `${this.options.prefix}/` : "",
+					delimiter: "/",
+					maxResults: 1e3
+				});
+				const childrenCount = ((apiResponse?.prefixes)?.length ?? 0) + files$1.length;
+				return {
+					id: this.generateId("/"),
+					path: "/.meta",
+					meta: {
+						kind: "afs:node",
+						childrenCount,
+						platformRef: generatePlatformRef(bucketName, "", true)
+					}
+				};
+			}
+			if (this.statCache) {
+				const cacheKey = createCacheKey(bucketName, this.options.prefix ?? "", path);
+				const cached = this.statCache.get(cacheKey);
+				if (cached) return {
+					id: cached.id,
+					path: ctx.path,
+					meta: cached.meta
+				};
+			}
+			const file = this.bucket.file(key);
+			const [exists] = await file.exists();
+			if (exists) {
+				const [metadata] = await file.getMetadata();
+				if (key.endsWith("/") || metadata.contentType === "application/x-directory") return {
+					id: this.generateId(key),
+					path: ctx.path,
+					updatedAt: metadata.updated ? new Date(metadata.updated) : void 0,
+					meta: {
+						kind: "afs:node",
+						childrenCount: -1,
+						platformRef: generatePlatformRef(bucketName, key, true)
+					}
+				};
+				const result = {
+					id: this.generateId(key),
+					path: ctx.path,
+					updatedAt: metadata.updated ? new Date(metadata.updated) : void 0,
+					meta: {
+						kind: "afs:document",
+						size: metadata.size ? Number(metadata.size) : void 0,
+						contentType: metadata.contentType,
+						lastModified: metadata.updated,
+						etag: metadata.etag,
+						storageClass: metadata.storageClass,
+						generation: metadata.generation,
+						metageneration: metadata.metageneration,
+						crc32c: metadata.crc32c,
+						md5Hash: metadata.md5Hash,
+						platformRef: generatePlatformRef(bucketName, key, false)
+					}
+				};
+				if (this.statCache) {
+					const cacheKey = createCacheKey(bucketName, this.options.prefix ?? "", path);
+					this.statCache.set(cacheKey, result);
+				}
+				return result;
+			}
+			const [files] = await this.bucket.getFiles({
+				prefix: `${key}/`,
+				maxResults: 1
+			});
+			if (files.length > 0) return {
+				id: this.generateId(`${key}/`),
+				path: ctx.path,
+				meta: {
+					kind: "afs:node",
+					childrenCount: -1,
+					platformRef: generatePlatformRef(bucketName, key, true)
+				}
+			};
+			const dirMarker = this.bucket.file(`${key}/`);
+			const [dirExists] = await dirMarker.exists();
+			if (dirExists) {
+				const [dirMetadata] = await dirMarker.getMetadata();
+				return {
+					id: this.generateId(`${key}/`),
+					path: ctx.path,
+					updatedAt: dirMetadata.updated ? new Date(dirMetadata.updated) : void 0,
+					meta: {
+						kind: "afs:node",
+						childrenCount: -1,
+						platformRef: generatePlatformRef(bucketName, key, true)
+					}
+				};
+			}
+			throw new AFSNotFoundError(path.startsWith("/") ? path : `/${path}`);
+		} catch (error) {
+			if (error instanceof AFSNotFoundError) throw error;
+			throw mapGCSError(error);
+		}
+	}
+	async statHandler(ctx) {
+		const metaEntry = await this.metaHandler({
+			...ctx,
+			path: ctx.path.endsWith("/.meta") ? ctx.path : `${ctx.path}/.meta`
+		});
+		const pathSegments = ctx.path.split("/").filter(Boolean);
+		return { data: {
+			id: pathSegments.length > 0 ? pathSegments[pathSegments.length - 1] : "/",
+			path: ctx.path,
+			meta: metaEntry.meta
+		} };
+	}
+	async writeHandler(ctx, payload) {
+		try {
+			const key = this.buildGCSKey(ctx.params.path);
+			const file = this.bucket.file(key);
+			let content;
+			if (typeof payload.content === "string") content = payload.content;
+			else if (Buffer.isBuffer(payload.content)) content = payload.content;
+			else if (payload.content !== void 0) content = JSON.stringify(payload.content);
+			else content = "";
+			const saveOptions = { validation: false };
+			if (payload.meta?.mimeType || payload.meta?.contentType) saveOptions.contentType = payload.meta.mimeType ?? payload.meta.contentType;
+			await file.save(content, saveOptions);
+			const [metadata] = await file.getMetadata();
+			const normalizedOutputPath = ctx.path.startsWith("/") ? ctx.path : `/${ctx.path}`;
+			this.invalidateCache(ctx.params.path);
+			return { data: {
+				id: this.generateId(key),
+				path: normalizedOutputPath,
+				content: payload.content,
+				updatedAt: metadata.updated ? new Date(metadata.updated) : /* @__PURE__ */ new Date(),
+				meta: {
+					size: metadata.size ? Number(metadata.size) : 0,
+					etag: metadata.etag,
+					generation: metadata.generation,
+					...payload.meta
+				}
+			} };
+		} catch (error) {
+			throw mapGCSError(error);
+		}
+	}
+	async deleteHandler(ctx) {
+		try {
+			const key = this.buildGCSKey(ctx.params.path);
+			const file = this.bucket.file(key);
+			const [exists] = await file.exists();
+			if (exists) {
+				await file.delete();
+				this.invalidateCache(ctx.params.path);
+				return { message: `Successfully deleted: ${ctx.params.path}` };
+			}
+			const [files] = await this.bucket.getFiles({
+				prefix: `${key}/`,
+				maxResults: 1
+			});
+			if (files.length === 0) throw new AFSNotFoundError(`/${ctx.params.path}`);
+			throw new AFSError(`Cannot delete non-empty directory: ${ctx.params.path}. Use recursive option.`, "AFS_INVALID_OPERATION");
+		} catch (error) {
+			if (error instanceof AFSError || error instanceof AFSNotFoundError) throw error;
+			throw mapGCSError(error);
+		}
+	}
+	async listActionsHandler(ctx) {
+		return { data: [
+			{
+				id: "presign-download",
+				path: joinURL(ctx.path, "presign-download"),
+				summary: "Generate signed download URL",
+				meta: {
+					kind: "afs:executable",
+					kinds: ["afs:executable", "afs:node"],
+					inputSchema: {
+						type: "object",
+						properties: { expiresIn: {
+							type: "number",
+							description: "Expiration in seconds (default: 3600, max: 604800)"
+						} }
+					}
+				}
+			},
+			{
+				id: "presign-upload",
+				path: joinURL(ctx.path, "presign-upload"),
+				summary: "Generate signed upload URL",
+				meta: {
+					kind: "afs:executable",
+					kinds: ["afs:executable", "afs:node"],
+					inputSchema: {
+						type: "object",
+						properties: {
+							expiresIn: {
+								type: "number",
+								description: "Expiration in seconds"
+							},
+							contentType: {
+								type: "string",
+								description: "Content-Type for upload"
+							}
+						}
+					}
+				}
+			},
+			{
+				id: "compose",
+				path: joinURL(ctx.path, "compose"),
+				summary: "Compose multiple objects into one",
+				meta: {
+					kind: "afs:executable",
+					kinds: ["afs:executable", "afs:node"],
+					inputSchema: {
+						type: "object",
+						properties: { sources: {
+							type: "array",
+							description: "Array of source paths (2-32)",
+							items: { type: "string" }
+						} },
+						required: ["sources"]
+					}
+				}
+			},
+			{
+				id: "rewrite",
+				path: joinURL(ctx.path, "rewrite"),
+				summary: "Rewrite object to new location",
+				meta: {
+					kind: "afs:executable",
+					kinds: ["afs:executable", "afs:node"],
+					inputSchema: {
+						type: "object",
+						properties: {
+							destination: {
+								type: "string",
+								description: "Destination path"
+							},
+							storageClass: {
+								type: "string",
+								description: "Target storage class"
+							},
+							contentType: {
+								type: "string",
+								description: "Override content type"
+							}
+						},
+						required: ["destination"]
+					}
+				}
+			}
+		] };
+	}
+	async signDownloadActionHandler(ctx, args) {
+		const normalizedPath = ctx.params.path.replace(/^\/+/, "").replace(/\/+$/, "");
+		const key = this.options.prefix ? `${this.options.prefix}/${normalizedPath}` : normalizedPath;
+		const file = this.bucket.file(key);
+		let expiresIn = args.expiresIn ?? DEFAULT_EXPIRES_IN;
+		if (expiresIn > MAX_EXPIRES_IN) expiresIn = MAX_EXPIRES_IN;
+		if (expiresIn < 1) expiresIn = 1;
+		const expiresAt = Date.now() + expiresIn * 1e3;
+		const [url] = await file.getSignedUrl({
+			action: "read",
+			expires: expiresAt
+		});
+		return {
+			success: true,
+			data: {
+				url,
+				expiresAt: new Date(expiresAt).toISOString()
+			}
+		};
+	}
+	async signUploadActionHandler(ctx, args) {
+		const normalizedPath = ctx.params.path.replace(/^\/+/, "").replace(/\/+$/, "");
+		const key = this.options.prefix ? `${this.options.prefix}/${normalizedPath}` : normalizedPath;
+		const file = this.bucket.file(key);
+		let expiresIn = args.expiresIn ?? DEFAULT_EXPIRES_IN;
+		if (expiresIn > MAX_EXPIRES_IN) expiresIn = MAX_EXPIRES_IN;
+		if (expiresIn < 1) expiresIn = 1;
+		const expiresAt = Date.now() + expiresIn * 1e3;
+		const contentType = args.contentType ?? "application/octet-stream";
+		const [url] = await file.getSignedUrl({
+			action: "write",
+			expires: expiresAt,
+			contentType
+		});
+		return {
+			success: true,
+			data: {
+				url,
+				expiresAt: new Date(expiresAt).toISOString()
+			}
+		};
+	}
+	async composeActionHandler(ctx, args) {
+		const normalizedPath = ctx.params.path.replace(/^\/+/, "").replace(/\/+$/, "");
+		const destinationKey = this.options.prefix ? `${this.options.prefix}/${normalizedPath}` : normalizedPath;
+		const sources = args.sources;
+		if (!sources || !Array.isArray(sources) || sources.length < 2) throw new AFSError("compose requires at least 2 source objects", "AFS_INVALID_ARGUMENT");
+		if (sources.length > MAX_COMPOSE_SOURCES) throw new AFSError(`compose supports maximum ${MAX_COMPOSE_SOURCES} sources`, "AFS_INVALID_ARGUMENT");
+		const sourceFiles = sources.map((source) => {
+			const sourcePath = source.replace(/^\/+/, "").replace(/\/+$/, "");
+			const sourceKey = this.options.prefix ? `${this.options.prefix}/${sourcePath}` : sourcePath;
+			return this.bucket.file(sourceKey);
+		});
+		const destinationFile = this.bucket.file(destinationKey);
+		await this.bucket.combine(sourceFiles, destinationFile);
+		const [metadata] = await destinationFile.getMetadata();
+		this.invalidateCache(ctx.params.path);
+		return {
+			success: true,
+			data: {
+				generation: metadata.generation,
+				size: metadata.size ? Number(metadata.size) : 0,
+				etag: metadata.etag
+			}
+		};
+	}
+	async rewriteActionHandler(ctx, args) {
+		const normalizedPath = ctx.params.path.replace(/^\/+/, "").replace(/\/+$/, "");
+		const sourceKey = this.options.prefix ? `${this.options.prefix}/${normalizedPath}` : normalizedPath;
+		const destination = args.destination;
+		if (!destination) throw new AFSError("rewrite requires destination path", "AFS_INVALID_ARGUMENT");
+		const destPath = destination.replace(/^\/+/, "").replace(/\/+$/, "");
+		const destKey = this.options.prefix ? `${this.options.prefix}/${destPath}` : destPath;
+		const sourceFile = this.bucket.file(sourceKey);
+		const destFile = this.bucket.file(destKey);
+		const copyOptions = {};
+		if (args.storageClass) copyOptions.metadata = { storageClass: args.storageClass };
+		if (args.contentType) copyOptions.contentType = args.contentType;
+		await sourceFile.copy(destFile, copyOptions);
+		const [metadata] = await destFile.getMetadata();
+		this.invalidateCache(destPath);
+		return {
+			success: true,
+			data: {
+				destination: `/${destPath}`,
+				generation: metadata.generation,
+				size: metadata.size ? Number(metadata.size) : 0,
+				etag: metadata.etag,
+				storageClass: metadata.storageClass
+			}
+		};
+	}
+	async explainHandler(ctx) {
+		const normalizedPath = (ctx.params.path ?? "").replace(/^\/+/, "").replace(/\/+$/, "");
+		if (!normalizedPath) {
+			const [files$1, , response$1] = await this.bucket.getFiles({
+				prefix: this.options.prefix ? `${this.options.prefix}/` : void 0,
+				delimiter: "/",
+				maxResults: 1e3
+			});
+			const objectCount$1 = files$1.length;
+			const prefixCount$1 = response$1?.prefixes?.length ?? 0;
+			const lines$1 = [];
+			lines$1.push(`# ${this.options.bucket}`);
+			lines$1.push("");
+			lines$1.push(`- **Type**: GCS Bucket`);
+			lines$1.push(`- **Bucket**: ${this.options.bucket}`);
+			if (this.options.prefix) lines$1.push(`- **Prefix**: ${this.options.prefix}`);
+			if (this.options.projectId) lines$1.push(`- **Project**: ${this.options.projectId}`);
+			lines$1.push(`- **Access Mode**: ${this.accessMode}`);
+			lines$1.push(`- **Top-level Objects**: ${objectCount$1}`);
+			lines$1.push(`- **Top-level Prefixes**: ${prefixCount$1}`);
+			return {
+				format: "markdown",
+				content: lines$1.join("\n")
+			};
+		}
+		const key = this.buildGCSKey(normalizedPath);
+		const file = this.bucket.file(key);
+		const [exists] = await file.exists();
+		if (exists) {
+			const [metadata] = await file.getMetadata();
+			const lines$1 = [];
+			lines$1.push(`# ${normalizedPath}`);
+			lines$1.push("");
+			lines$1.push(`- **Type**: Object`);
+			lines$1.push(`- **Key**: ${key}`);
+			lines$1.push(`- **Size**: ${metadata.size ?? 0} bytes`);
+			if (metadata.contentType) lines$1.push(`- **Content-Type**: ${metadata.contentType}`);
+			if (metadata.storageClass) lines$1.push(`- **Storage Class**: ${metadata.storageClass}`);
+			if (metadata.updated) lines$1.push(`- **Last Modified**: ${metadata.updated}`);
+			if (metadata.etag) lines$1.push(`- **ETag**: ${metadata.etag}`);
+			if (metadata.generation) lines$1.push(`- **Generation**: ${metadata.generation}`);
+			return {
+				format: "markdown",
+				content: lines$1.join("\n")
+			};
+		}
+		const prefix = key.endsWith("/") ? key : `${key}/`;
+		const [files, , response] = await this.bucket.getFiles({
+			prefix,
+			delimiter: "/",
+			maxResults: 1e3
+		});
+		const objectCount = files.length;
+		const prefixCount = response?.prefixes?.length ?? 0;
+		if (objectCount === 0 && prefixCount === 0) throw new AFSNotFoundError(`/${normalizedPath}`, `Path not found: ${normalizedPath}`);
+		const lines = [];
+		lines.push(`# ${normalizedPath}/`);
+		lines.push("");
+		lines.push(`- **Type**: Prefix (directory)`);
+		lines.push(`- **Prefix**: ${prefix}`);
+		lines.push(`- **Objects**: ${objectCount}`);
+		lines.push(`- **Sub-prefixes**: ${prefixCount}`);
+		return {
+			format: "markdown",
+			content: lines.join("\n")
+		};
+	}
+	async searchHandler(ctx, query) {
+		const { minimatch } = await import("minimatch");
+		const normalizedPath = (ctx.params.path ?? "").replace(/^\/+/, "").replace(/\/+$/, "");
+		const prefix = normalizedPath ? this.options.prefix ? `${this.options.prefix}/${normalizedPath}/` : `${normalizedPath}/` : this.options.prefix ? `${this.options.prefix}/` : "";
+		const [files] = await this.bucket.getFiles({ prefix: prefix || void 0 });
+		const results = [];
+		for (const file of files) {
+			const relativePath = prefix ? file.name.slice(prefix.length) : file.name;
+			if (!relativePath) continue;
+			if (minimatch(relativePath, query)) {
+				const displayPath = joinURL("/", normalizedPath, relativePath);
+				results.push({
+					id: this.generateId(file.name),
+					path: displayPath,
+					meta: {
+						size: file.metadata?.size ? Number(file.metadata.size) : void 0,
+						contentType: file.metadata?.contentType,
+						lastModified: file.metadata?.updated
+					}
+				});
+			}
+		}
+		return { data: results };
+	}
+	async readCapabilities(_ctx) {
+		const capabilities = {
+			schemaVersion: 1,
+			provider: "gcs",
+			description: `GCS bucket: ${this.options.bucket}`,
+			tools: [],
+			operations: this.getOperationsDeclaration(),
+			actions: [{
+				description: "GCS object actions",
+				catalog: [
+					{
+						name: "presign-download",
+						description: "Generate a signed download URL",
+						inputSchema: {
+							type: "object",
+							properties: { expiresIn: {
+								type: "number",
+								description: "Expiration in seconds (default: 3600, max: 604800)"
+							} }
+						}
+					},
+					{
+						name: "presign-upload",
+						description: "Generate a signed upload URL",
+						inputSchema: {
+							type: "object",
+							properties: {
+								expiresIn: {
+									type: "number",
+									description: "Expiration in seconds"
+								},
+								contentType: {
+									type: "string",
+									description: "Content-Type for upload"
+								}
+							}
+						}
+					},
+					{
+						name: "compose",
+						description: "Compose multiple objects into one (max 32 sources)",
+						inputSchema: {
+							type: "object",
+							properties: { sources: {
+								type: "array",
+								description: "Array of source paths (2-32)",
+								items: { type: "string" }
+							} },
+							required: ["sources"]
+						}
+					},
+					{
+						name: "rewrite",
+						description: "Copy/rewrite object to a new location",
+						inputSchema: {
+							type: "object",
+							properties: {
+								destination: {
+									type: "string",
+									description: "Destination path"
+								},
+								storageClass: {
+									type: "string",
+									description: "Target storage class"
+								},
+								contentType: {
+									type: "string",
+									description: "Override content type"
+								}
+							},
+							required: ["destination"]
+						}
+					}
+				],
+				discovery: { pathTemplate: "/{path}/.actions" }
+			}]
+		};
+		return {
+			id: ".capabilities",
+			path: "/.meta/.capabilities",
+			content: JSON.stringify(capabilities, null, 2),
+			meta: { kind: "afs:capabilities" }
+		};
+	}
+};
+__decorate([List("/"), List("/:path*")], AFSGCS.prototype, "listHandler", null);
+__decorate([List("/:path*/@versions")], AFSGCS.prototype, "listVersionsHandler", null);
+__decorate([Read("/:path*")], AFSGCS.prototype, "readHandler", null);
+__decorate([Read("/:path*/@versions/:generation")], AFSGCS.prototype, "readVersionHandler", null);
+__decorate([Meta("/"), Meta("/:path*")], AFSGCS.prototype, "metaHandler", null);
+__decorate([Stat("/"), Stat("/:path*")], AFSGCS.prototype, "statHandler", null);
+__decorate([Write("/:path*")], AFSGCS.prototype, "writeHandler", null);
+__decorate([Delete("/:path*")], AFSGCS.prototype, "deleteHandler", null);
+__decorate([Actions("/:path*")], AFSGCS.prototype, "listActionsHandler", null);
+__decorate([Actions.Exec("/:path*", "presign-download")], AFSGCS.prototype, "signDownloadActionHandler", null);
+__decorate([Actions.Exec("/:path*", "presign-upload")], AFSGCS.prototype, "signUploadActionHandler", null);
+__decorate([Actions.Exec("/:path*", "compose")], AFSGCS.prototype, "composeActionHandler", null);
+__decorate([Actions.Exec("/:path*", "rewrite")], AFSGCS.prototype, "rewriteActionHandler", null);
+__decorate([Explain("/"), Explain("/:path*")], AFSGCS.prototype, "explainHandler", null);
+__decorate([Search("/"), Search("/:path*")], AFSGCS.prototype, "searchHandler", null);
+__decorate([Read("/.meta/.capabilities")], AFSGCS.prototype, "readCapabilities", null);
+
+//#endregion
+export { AFSGCS, AFSGCS as default };
+//# sourceMappingURL=index.mjs.map