@aigne/afs-gce 1.11.0-beta.6 → 1.11.0-beta.7

package/dist/index.mjs

@@ -1,273 +1,9 @@
+import { AFSBaseProvider, AFSNotFoundError, AFSReadonlyError, Actions, Delete, Explain, List, Meta, Read, Stat, Write } from "@aigne/afs";
+import { camelize, optionalize, zodParse } from "@aigne/afs/utils/zod";
 import { InstancesClient } from "@google-cloud/compute";
-import { camelize, optionalize } from "@aigne/afs/utils/zod";
+import { joinURL } from "ufo";
 import { z } from "zod";
 
-//#region src/errors.ts
-/**
-* GCE Provider Error Handling
-*
-* Maps GCE 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 = class extends Error {
-	code;
-	retryAfter;
-	constructor(code, message, options) {
-		super(message);
-		this.name = "AFSError";
-		this.code = code;
-		this.retryAfter = options?.retryAfter;
-	}
-};
-/**
-* Map GCE 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 GCE error to AFS error
-*
-* @param error - GCE SDK error or generic error
-* @returns AFSError with appropriate error code
-*/
-function mapGCEError(error) {
-	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 GCE error";
-		return new AFSError(STATUS_TO_AFS_ERROR[statusCode] ?? AFSErrorCode.UNKNOWN, message);
-	}
-	if (error instanceof Error) return new AFSError(AFSErrorCode.UNKNOWN, error.message);
-	return new AFSError(AFSErrorCode.UNKNOWN, String(error));
-}
-
-//#endregion
-//#region src/path-resolver.ts
-/**
-* Parse an AFS path into GCE resource identifiers
-*
-* Path structure:
-* / - root
-* /instances - list all instances
-* /instances/{name} - specific instance
-* /instances/{name}/metadata.json - instance metadata
-* /instances/{name}/actions - list available actions
-* /instances/{name}/actions/{action} - specific action
-* /actions - global actions list
-* /actions/{action} - global action
-*
-* @param path - AFS path
-* @returns Parsed path with type and identifiers
-*/
-function parsePath(path) {
-	const segments = path.replace(/^\/+/, "").replace(/\/+$/, "").split("/").filter(Boolean);
-	if (segments.length === 0) return {
-		type: "root",
-		raw: path
-	};
-	const [first, second, third, fourth] = segments;
-	if (first === "instances") {
-		if (!second) return {
-			type: "instances",
-			raw: path
-		};
-		if (!third) return {
-			type: "instance",
-			instanceName: second,
-			raw: path
-		};
-		if (third === "metadata.json") return {
-			type: "instance-metadata",
-			instanceName: second,
-			fileName: third,
-			raw: path
-		};
-		if (third === "actions") {
-			if (!fourth) return {
-				type: "instance-actions",
-				instanceName: second,
-				raw: path
-			};
-			return {
-				type: "instance-action",
-				instanceName: second,
-				action: fourth,
-				raw: path
-			};
-		}
-		return {
-			type: "unknown",
-			raw: path
-		};
-	}
-	if (first === "actions") {
-		if (!second) return {
-			type: "actions",
-			raw: path
-		};
-		return {
-			type: "global-action",
-			action: second,
-			raw: path
-		};
-	}
-	return {
-		type: "unknown",
-		raw: path
-	};
-}
-/**
-* Build an AFS path from components
-*/
-function buildPath(...segments) {
-	return `/${segments.filter(Boolean).join("/")}`;
-}
-
-//#endregion
-//#region src/operations/actions.ts
-/**
-* Execute an action on a GCE resource
-*
-* @param client - GCE InstancesClient
-* @param projectId - GCP project ID
-* @param zone - GCE zone
-* @param path - AFS path to the action
-* @returns Action result
-*/
-async function executeAction(client, projectId, zone, path) {
-	try {
-		const parsed = parsePath(path);
-		switch (parsed.type) {
-			case "instance-action": return executeInstanceAction(client, projectId, zone, parsed.instanceName, parsed.action);
-			case "global-action": return executeGlobalAction(parsed.action);
-			default: throw new Error(`Cannot execute action on path: ${path}`);
-		}
-	} catch (error) {
-		throw mapGCEError(error);
-	}
-}
-/**
-* Execute an action on a specific instance
-*/
-async function executeInstanceAction(client, projectId, zone, instanceName, action) {
-	const [instance] = await client.get({
-		project: projectId,
-		zone,
-		instance: instanceName
-	});
-	const status = instance.status;
-	switch (action) {
-		case "start": return startInstance(client, projectId, zone, instanceName, status);
-		case "stop": return stopInstance(client, projectId, zone, instanceName, status);
-		case "reset": return resetInstance(client, projectId, zone, instanceName, status);
-		default: return {
-			success: false,
-			action,
-			error: `Unknown action: ${action}`
-		};
-	}
-}
-/**
-* Start an instance
-*/
-async function startInstance(client, projectId, zone, instanceName, currentStatus) {
-	if (currentStatus !== "STOPPED" && currentStatus !== "TERMINATED") return {
-		success: false,
-		action: "start",
-		error: `Cannot start instance in ${currentStatus} state. Instance must be STOPPED or TERMINATED.`
-	};
-	const [operation] = await client.start({
-		project: projectId,
-		zone,
-		instance: instanceName
-	});
-	return {
-		success: true,
-		action: "start",
-		operationName: operation.latestResponse?.name || "unknown"
-	};
-}
-/**
-* Stop an instance
-*/
-async function stopInstance(client, projectId, zone, instanceName, currentStatus) {
-	if (currentStatus !== "RUNNING") return {
-		success: false,
-		action: "stop",
-		error: `Cannot stop instance in ${currentStatus} state. Instance must be RUNNING.`
-	};
-	const [operation] = await client.stop({
-		project: projectId,
-		zone,
-		instance: instanceName
-	});
-	return {
-		success: true,
-		action: "stop",
-		operationName: operation.latestResponse?.name || "unknown"
-	};
-}
-/**
-* Reset an instance
-*/
-async function resetInstance(client, projectId, zone, instanceName, currentStatus) {
-	if (currentStatus !== "RUNNING") return {
-		success: false,
-		action: "reset",
-		error: `Cannot reset instance in ${currentStatus} state. Instance must be RUNNING.`
-	};
-	const [operation] = await client.reset({
-		project: projectId,
-		zone,
-		instance: instanceName
-	});
-	return {
-		success: true,
-		action: "reset",
-		operationName: operation.latestResponse?.name || "unknown"
-	};
-}
-/**
-* Execute a global action
-*/
-function executeGlobalAction(action) {
-	switch (action) {
-		case "refresh": return {
-			success: true,
-			action: "refresh"
-		};
-		default: return {
-			success: false,
-			action,
-			error: `Unknown global action: ${action}`
-		};
-	}
-}
-
-//#endregion
 //#region src/platform-ref.ts
 /**
 * Generate platform reference with GCP Console URL for an instance
@@ -317,6 +53,19 @@ const afsgceOptionsSchema = camelize(z.object({
 	cacheTtl: optionalize(z.number().int().min(0))
 }).strict());
 /**
+* GCE instance states
+*/
+const GCE_INSTANCE_STATES = [
+	"PROVISIONING",
+	"STAGING",
+	"RUNNING",
+	"STOPPING",
+	"STOPPED",
+	"SUSPENDING",
+	"SUSPENDED",
+	"TERMINATED"
+];
+/**
 * Kind constants for GCE resources
 */
 const KINDS = {
@@ -328,433 +77,58 @@ const KINDS = {
 };
 
 //#endregion
-//#region src/operations/list.ts
-/**
-* List GCE resources
-*
-* @param client - GCE InstancesClient
-* @param projectId - GCP project ID
-* @param zone - GCE zone
-* @param path - AFS path
-* @param options - List options
-* @returns List result with entries
-*/
-async function list(client, projectId, zone, path, options) {
-	try {
-		const parsed = parsePath(path);
-		switch (parsed.type) {
-			case "root": return listRoot(projectId);
-			case "instances": return listInstances(client, projectId, zone, options);
-			case "instance": return listInstanceChildren(client, projectId, zone, parsed.instanceName);
-			case "instance-actions": return listInstanceActions(client, projectId, zone, parsed.instanceName);
-			case "actions": return listGlobalActions(projectId);
-			default: return { data: [] };
-		}
-	} catch (error) {
-		throw mapGCEError(error);
-	}
-}
-/**
-* List root directory
-*/
-function listRoot(projectId) {
-	return { data: [{
-		id: `gce://${projectId}/instances`,
-		path: "/instances",
-		metadata: {
-			kind: KINDS.NODE,
-			kinds: [KINDS.NODE],
-			childrenCount: 0,
-			description: "GCE Instances",
-			platformRef: generateInstancesListPlatformRef(projectId)
-		}
-	}, {
-		id: `gce://${projectId}/actions`,
-		path: "/actions",
-		metadata: {
-			kind: KINDS.NODE,
-			kinds: [KINDS.NODE],
-			childrenCount: 0,
-			description: "Global Actions"
-		}
-	}] };
-}
-/**
-* List all instances
-*/
-async function listInstances(client, projectId, zone, options) {
-	const maxChildren = options?.maxChildren ?? 1e3;
-	const [instances] = await client.list({
-		project: projectId,
-		zone,
-		maxResults: maxChildren
-	});
-	return { data: (instances || []).map((instance) => {
-		const name = instance.name;
-		const machineType = instance.machineType?.split("/").pop() || "unknown";
-		return {
-			id: `gce://${projectId}/${zone}/${name}`,
-			path: buildPath("instances", name),
-			metadata: {
-				kind: KINDS.INSTANCE,
-				kinds: [
-					KINDS.INSTANCE,
-					KINDS.GCP_RESOURCE,
-					KINDS.NODE
-				],
-				childrenCount: 2,
-				status: instance.status,
-				machineType,
-				privateIp: instance.networkInterfaces?.[0]?.networkIP,
-				publicIp: instance.networkInterfaces?.[0]?.accessConfigs?.[0]?.natIP,
-				createdAt: instance.creationTimestamp,
-				labels: instance.labels,
-				platformRef: generateInstancePlatformRef(projectId, zone, name)
-			}
-		};
-	}) };
-}
-/**
-* List instance children (metadata.json, actions)
-*/
-async function listInstanceChildren(client, projectId, zone, instanceName) {
-	await client.get({
-		project: projectId,
-		zone,
-		instance: instanceName
-	});
-	return { data: [{
-		id: `gce://${projectId}/${zone}/${instanceName}/metadata.json`,
-		path: buildPath("instances", instanceName, "metadata.json"),
-		metadata: {
-			kind: KINDS.NODE,
-			kinds: [KINDS.NODE],
-			description: "Instance metadata"
-		}
-	}, {
-		id: `gce://${projectId}/${zone}/${instanceName}/actions`,
-		path: buildPath("instances", instanceName, "actions"),
-		metadata: {
-			kind: KINDS.NODE,
-			kinds: [KINDS.NODE],
-			childrenCount: 0,
-			description: "Instance actions"
-		}
-	}] };
-}
-/**
-* List available actions for an instance
-*/
-async function listInstanceActions(client, projectId, zone, instanceName) {
-	const [instance] = await client.get({
-		project: projectId,
-		zone,
-		instance: instanceName
-	});
-	const status = instance.status;
-	const actions = [];
-	switch (status) {
-		case "RUNNING":
-			actions.push("stop", "reset");
-			break;
-		case "STOPPED":
-		case "TERMINATED":
-			actions.push("start");
-			break;
-		case "SUSPENDED":
-			actions.push("resume");
-			break;
-		default: break;
-	}
-	return { data: actions.map((action) => ({
-		id: `gce://${projectId}/${zone}/${instanceName}/actions/${action}`,
-		path: buildPath("instances", instanceName, "actions", action),
-		metadata: {
-			kind: KINDS.ACTION,
-			kinds: [
-				KINDS.ACTION,
-				KINDS.EXECUTABLE,
-				KINDS.NODE
-			],
-			description: `${action.charAt(0).toUpperCase() + action.slice(1)} the instance`
-		}
-	})) };
-}
-/**
-* List global actions
-*/
-function listGlobalActions(projectId) {
-	return { data: [{
-		id: `gce://${projectId}/actions/refresh`,
-		path: "/actions/refresh",
-		metadata: {
-			kind: KINDS.ACTION,
-			kinds: [
-				KINDS.ACTION,
-				KINDS.EXECUTABLE,
-				KINDS.NODE
-			],
-			description: "Refresh instance cache"
-		}
-	}] };
+//#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/operations/read.ts
+//#region src/index.ts
 /**
-* Read GCE resource data
+* AFS GCE Provider
 *
-* @param client - GCE InstancesClient
-* @param projectId - GCP project ID
-* @param zone - GCE zone
-* @param path - AFS path
-* @param options - Read options
-* @returns Read result with content
-*/
-async function read(client, projectId, zone, path, _options) {
-	try {
-		const parsed = parsePath(path);
-		switch (parsed.type) {
-			case "instance-metadata": return readInstanceMetadata(client, projectId, zone, parsed.instanceName);
-			default: throw new Error(`Cannot read path: ${path}`);
-		}
-	} catch (error) {
-		throw mapGCEError(error);
-	}
-}
-/**
-* Read instance metadata as JSON
+* GCE provider using AFSBaseProvider decorator routing pattern.
+* Provides file-system-like access to Google Compute Engine instances.
 */
-async function readInstanceMetadata(client, projectId, zone, instanceName) {
-	const [instance] = await client.get({
-		project: projectId,
-		zone,
-		instance: instanceName
-	});
-	return { data: {
-		id: `gce://${projectId}/${zone}/${instanceName}/metadata.json`,
-		path: buildPath("instances", instanceName, "metadata.json"),
-		metadata: {
-			kind: KINDS.NODE,
-			kinds: [KINDS.NODE],
-			description: "Instance metadata"
-		},
-		content: JSON.stringify(instance, null, 2)
-	} };
-}
-
-//#endregion
-//#region src/operations/stat.ts
 /**
-* Get metadata for a GCE resource
-*
-* @param client - GCE InstancesClient
-* @param projectId - GCP project ID
-* @param zone - GCE zone
-* @param path - AFS path
-* @returns Entry with metadata
+* Map GCE SDK errors to appropriate AFS errors
 */
-async function stat(client, projectId, zone, path) {
-	try {
-		const parsed = parsePath(path);
-		switch (parsed.type) {
-			case "root": return statRoot(projectId);
-			case "instances": return statInstances(projectId);
-			case "instance": return statInstance(client, projectId, zone, parsed.instanceName);
-			case "instance-metadata": return statInstanceMetadata(client, projectId, zone, parsed.instanceName);
-			case "instance-actions": return statInstanceActions(client, projectId, zone, parsed.instanceName);
-			case "instance-action": return statInstanceAction(client, projectId, zone, parsed.instanceName, parsed.action);
-			case "actions": return statGlobalActions(projectId);
-			case "global-action": return statGlobalAction(projectId, parsed.action);
-			default: throw new Error(`Path not found: ${path}`);
-		}
-	} catch (error) {
-		throw mapGCEError(error);
+function mapGCEError(error, path) {
+	if (error instanceof AFSNotFoundError || error instanceof AFSReadonlyError) return error;
+	if (typeof error === "object" && error !== null && "code" in error) {
+		const err = error;
+		if (err.code === 404) return new AFSNotFoundError(path ?? "/", err.message);
 	}
+	if (error instanceof Error) return error;
+	return new Error(String(error));
 }
 /**
-* Stat root directory
-*/
-function statRoot(projectId) {
-	return {
-		id: `gce://${projectId}/`,
-		path: "/",
-		metadata: {
-			kind: KINDS.NODE,
-			kinds: [KINDS.NODE],
-			childrenCount: 2,
-			description: "GCE Root"
-		}
-	};
-}
-/**
-* Stat instances directory
-*/
-function statInstances(projectId) {
-	return {
-		id: `gce://${projectId}/instances`,
-		path: "/instances",
-		metadata: {
-			kind: KINDS.NODE,
-			kinds: [KINDS.NODE],
-			childrenCount: 0,
-			description: "GCE Instances",
-			platformRef: generateInstancesListPlatformRef(projectId)
-		}
-	};
-}
-/**
-* Stat a specific instance
-*/
-async function statInstance(client, projectId, zone, instanceName) {
-	const [instance] = await client.get({
-		project: projectId,
-		zone,
-		instance: instanceName
-	});
-	const machineType = instance.machineType?.split("/").pop() || "unknown";
-	return {
-		id: `gce://${projectId}/${zone}/${instanceName}`,
-		path: buildPath("instances", instanceName),
-		metadata: {
-			kind: KINDS.INSTANCE,
-			kinds: [
-				KINDS.INSTANCE,
-				KINDS.GCP_RESOURCE,
-				KINDS.NODE
-			],
-			childrenCount: 2,
-			status: instance.status,
-			machineType,
-			privateIp: instance.networkInterfaces?.[0]?.networkIP,
-			publicIp: instance.networkInterfaces?.[0]?.accessConfigs?.[0]?.natIP,
-			createdAt: instance.creationTimestamp,
-			labels: instance.labels,
-			platformRef: generateInstancePlatformRef(projectId, zone, instanceName)
-		}
-	};
-}
-/**
-* Stat instance metadata.json file
-*/
-async function statInstanceMetadata(client, projectId, zone, instanceName) {
-	await client.get({
-		project: projectId,
-		zone,
-		instance: instanceName
-	});
-	return {
-		id: `gce://${projectId}/${zone}/${instanceName}/metadata.json`,
-		path: buildPath("instances", instanceName, "metadata.json"),
-		metadata: {
-			kind: KINDS.NODE,
-			kinds: [KINDS.NODE],
-			description: "Instance metadata"
-		}
-	};
-}
-/**
-* Stat instance actions directory
-*/
-async function statInstanceActions(client, projectId, zone, instanceName) {
-	await client.get({
-		project: projectId,
-		zone,
-		instance: instanceName
-	});
-	return {
-		id: `gce://${projectId}/${zone}/${instanceName}/actions`,
-		path: buildPath("instances", instanceName, "actions"),
-		metadata: {
-			kind: KINDS.NODE,
-			kinds: [KINDS.NODE],
-			childrenCount: 0,
-			description: "Instance actions"
-		}
-	};
-}
-/**
-* Stat a specific instance action
-*/
-async function statInstanceAction(client, projectId, zone, instanceName, action) {
-	await client.get({
-		project: projectId,
-		zone,
-		instance: instanceName
-	});
-	return {
-		id: `gce://${projectId}/${zone}/${instanceName}/actions/${action}`,
-		path: buildPath("instances", instanceName, "actions", action),
-		metadata: {
-			kind: KINDS.ACTION,
-			kinds: [
-				KINDS.ACTION,
-				KINDS.EXECUTABLE,
-				KINDS.NODE
-			],
-			description: `${action.charAt(0).toUpperCase() + action.slice(1)} the instance`
-		}
-	};
-}
-/**
-* Stat global actions directory
-*/
-function statGlobalActions(projectId) {
-	return {
-		id: `gce://${projectId}/actions`,
-		path: "/actions",
-		metadata: {
-			kind: KINDS.NODE,
-			kinds: [KINDS.NODE],
-			childrenCount: 1,
-			description: "Global Actions"
-		}
-	};
-}
-/**
-* Stat a specific global action
-*/
-function statGlobalAction(projectId, action) {
-	return {
-		id: `gce://${projectId}/actions/${action}`,
-		path: buildPath("actions", action),
-		metadata: {
-			kind: KINDS.ACTION,
-			kinds: [
-				KINDS.ACTION,
-				KINDS.EXECUTABLE,
-				KINDS.NODE
-			],
-			description: `${action.charAt(0).toUpperCase() + action.slice(1)} action`
-		}
-	};
-}
-
-//#endregion
-//#region src/index.ts
-/**
-* AFS GCE Provider
+* AFSGCE Provider using AFSBaseProvider pattern
 *
-* Provides a file-system-like interface to GCE instances.
+* Provides file-system-like access to GCE instances.
+* Uses decorator routing (@List, @Read, @Write, @Delete, @Meta, @Actions, @Explain).
 *
 * @example
 * ```typescript
-* const provider = new AFSGCE({
-*   projectId: 'my-project',
-*   zone: 'us-central1-a',
+* const gce = new AFSGCE({
+*   projectId: "my-project",
+*   zone: "us-central1-a",
 * });
 *
-* // List instances
-* const instances = await provider.list('/instances');
+* // Mount to AFS
+* afs.mount(gce);
 *
-* // Get instance metadata
-* const metadata = await provider.read('/instances/my-vm/metadata.json');
+* // List instances
+* const result = await afs.list("/modules/gce/instances");
 *
-* // Start an instance (requires readwrite mode)
-* await provider.write('/instances/my-vm/actions/start', {});
+* // Read instance metadata
+* const meta = await afs.read("/modules/gce/instances/my-vm/metadata.json");
 * ```
 */
-var AFSGCE = class {
+var AFSGCE = class AFSGCE extends AFSBaseProvider {
 	name;
 	description;
 	accessMode;
@@ -762,6 +136,7 @@ var AFSGCE = class {
 	projectId;
 	zone;
 	constructor(options) {
+		super();
 		const validated = afsgceOptionsSchema.parse(options);
 		this.name = validated.name || "gce";
 		this.description = validated.description;
@@ -776,61 +151,577 @@ var AFSGCE = class {
 			} : void 0
 		});
 	}
-	/**
-	* List GCE resources
-	*/
-	async list(path, options) {
-		return list(this.client, this.projectId, this.zone, path, options);
-	}
-	/**
-	* Get metadata for a GCE resource
-	*/
-	async stat(path) {
-		const entry = await stat(this.client, this.projectId, this.zone, path);
+	static schema() {
+		return afsgceOptionsSchema;
+	}
+	static async load({ basePath, config } = {}) {
+		return new AFSGCE(zodParse(afsgceOptionsSchema, config, { prefix: basePath }));
+	}
+	async getInstance(instanceName) {
+		try {
+			const [instance] = await this.client.get({
+				project: this.projectId,
+				zone: this.zone,
+				instance: instanceName
+			});
+			return instance;
+		} catch (error) {
+			throw mapGCEError(error, joinURL("/instances", instanceName));
+		}
+	}
+	async listAllInstances(maxResults) {
+		const [instances] = await this.client.list({
+			project: this.projectId,
+			zone: this.zone,
+			maxResults: maxResults ?? 1e3
+		});
+		return instances || [];
+	}
+	buildInstanceEntry(instance, basePath) {
+		const name = instance.name;
+		const machineType = instance.machineType?.split("/").pop() || "unknown";
+		return {
+			id: `gce://${this.projectId}/${this.zone}/${name}`,
+			path: joinURL(basePath, name),
+			meta: {
+				kind: KINDS.INSTANCE,
+				kinds: [
+					KINDS.INSTANCE,
+					KINDS.GCP_RESOURCE,
+					KINDS.NODE
+				],
+				childrenCount: -1,
+				status: instance.status,
+				machineType,
+				privateIp: instance.networkInterfaces?.[0]?.networkIP,
+				publicIp: instance.networkInterfaces?.[0]?.accessConfigs?.[0]?.natIP,
+				createdAt: instance.creationTimestamp,
+				labels: instance.labels,
+				platformRef: generateInstancePlatformRef(this.projectId, this.zone, name)
+			}
+		};
+	}
+	async listRoot(_ctx) {
+		return { data: [{
+			id: `gce://${this.projectId}/instances`,
+			path: "/instances",
+			meta: {
+				kind: KINDS.NODE,
+				kinds: [KINDS.NODE],
+				childrenCount: -1,
+				description: "GCE Instances",
+				platformRef: generateInstancesListPlatformRef(this.projectId)
+			}
+		}, {
+			id: `gce://${this.projectId}/by-status`,
+			path: "/by-status",
+			meta: {
+				kind: KINDS.NODE,
+				kinds: [KINDS.NODE],
+				childrenCount: GCE_INSTANCE_STATES.length,
+				description: "Instances grouped by status"
+			}
+		}] };
+	}
+	async listInstances(_ctx) {
+		try {
+			return { data: (await this.listAllInstances()).map((instance) => this.buildInstanceEntry(instance, "/instances")) };
+		} catch (error) {
+			throw mapGCEError(error, "/instances");
+		}
+	}
+	async listInstanceChildren(ctx) {
+		await this.getInstance(ctx.params.instanceId);
+		return { data: [{
+			id: `gce://${this.projectId}/${this.zone}/${ctx.params.instanceId}/metadata.json`,
+			path: joinURL(ctx.path, "metadata.json"),
+			meta: {
+				kind: KINDS.NODE,
+				kinds: [KINDS.NODE],
+				description: "Instance metadata"
+			}
+		}, {
+			id: `gce://${this.projectId}/${this.zone}/${ctx.params.instanceId}/labels`,
+			path: joinURL(ctx.path, "labels"),
+			meta: {
+				kind: KINDS.NODE,
+				kinds: [KINDS.NODE],
+				childrenCount: -1,
+				description: "Instance labels"
+			}
+		}] };
+	}
+	async listInstanceLabels(ctx) {
+		const labels = (await this.getInstance(ctx.params.instanceId)).labels || {};
+		return { data: Object.entries(labels).map(([key, value]) => ({
+			id: `gce://${this.projectId}/${this.zone}/${ctx.params.instanceId}/labels/${key}`,
+			path: joinURL(ctx.path, encodeURIComponent(key)),
+			content: value,
+			meta: { kind: "gce:label" }
+		})) };
+	}
+	async listByStatus(_ctx) {
+		return { data: GCE_INSTANCE_STATES.map((status) => ({
+			id: `gce://${this.projectId}/by-status/${status.toLowerCase()}`,
+			path: joinURL("/by-status", status.toLowerCase()),
+			meta: {
+				kind: KINDS.NODE,
+				kinds: [KINDS.NODE],
+				childrenCount: -1,
+				description: `Instances in ${status} state`
+			}
+		})) };
+	}
+	async listByStatusFilter(ctx) {
+		try {
+			const statusUpper = ctx.params.status.toUpperCase();
+			return { data: (await this.listAllInstances()).filter((inst) => inst.status?.toUpperCase() === statusUpper).map((instance) => this.buildInstanceEntry(instance, ctx.path)) };
+		} catch (error) {
+			throw mapGCEError(error, ctx.path);
+		}
+	}
+	async readCapabilities(_ctx) {
+		const actionCatalogs = [];
+		actionCatalogs.push({
+			kind: "gce:instance",
+			description: "Instance lifecycle operations",
+			catalog: [
+				{
+					name: "start",
+					description: "Start a stopped or terminated instance",
+					inputSchema: {
+						type: "object",
+						properties: {}
+					}
+				},
+				{
+					name: "stop",
+					description: "Stop a running instance",
+					inputSchema: {
+						type: "object",
+						properties: {}
+					}
+				},
+				{
+					name: "reset",
+					description: "Reset (hard reboot) a running instance",
+					inputSchema: {
+						type: "object",
+						properties: {}
+					}
+				}
+			],
+			discovery: {
+				pathTemplate: "/instances/:instanceName/.actions",
+				note: "Replace :instanceName with actual instance name"
+			}
+		});
+		if (this.accessMode === "readwrite") actionCatalogs.push({
+			kind: "gce:global",
+			description: "Global GCE operations",
+			catalog: [{
+				name: "refresh",
+				description: "Refresh cached instance data",
+				inputSchema: {
+					type: "object",
+					properties: {}
+				}
+			}],
+			discovery: {
+				pathTemplate: "/.actions",
+				note: "Available at provider root"
+			}
+		});
+		return {
+			id: "/.meta/.capabilities",
+			path: "/.meta/.capabilities",
+			content: {
+				schemaVersion: 1,
+				provider: this.name,
+				version: "1.0.0",
+				description: this.description,
+				tools: [],
+				actions: actionCatalogs,
+				operations: this.getOperationsDeclaration()
+			},
+			meta: { kind: "afs:capabilities" }
+		};
+	}
+	async readInstanceMetadata(ctx) {
+		try {
+			const instance = await this.getInstance(ctx.params.instanceId);
+			return {
+				id: `gce://${this.projectId}/${this.zone}/${ctx.params.instanceId}/metadata.json`,
+				path: ctx.path,
+				meta: {
+					kind: KINDS.NODE,
+					kinds: [KINDS.NODE],
+					description: "Instance metadata"
+				},
+				content: JSON.stringify(instance, null, 2)
+			};
+		} catch (error) {
+			throw mapGCEError(error, ctx.path);
+		}
+	}
+	async readInstanceLabel(ctx) {
+		const value = ((await this.getInstance(ctx.params.instanceId)).labels || {})[ctx.params.labelKey];
+		if (value === void 0) throw new AFSNotFoundError(ctx.path);
+		return {
+			id: `gce://${this.projectId}/${this.zone}/${ctx.params.instanceId}/labels/${ctx.params.labelKey}`,
+			path: ctx.path,
+			content: value,
+			meta: { kind: "gce:label" }
+		};
+	}
+	async metaRoot(ctx) {
+		return {
+			id: `gce://${this.projectId}/`,
+			path: ctx.path,
+			meta: {
+				kind: KINDS.NODE,
+				kinds: [KINDS.NODE],
+				childrenCount: 2,
+				description: "GCE Root"
+			}
+		};
+	}
+	async metaInstances(ctx) {
+		return {
+			id: `gce://${this.projectId}/instances`,
+			path: ctx.path,
+			meta: {
+				kind: KINDS.NODE,
+				kinds: [KINDS.NODE],
+				childrenCount: -1,
+				description: "GCE Instances",
+				platformRef: generateInstancesListPlatformRef(this.projectId)
+			}
+		};
+	}
+	async metaInstance(ctx) {
+		try {
+			const instance = await this.getInstance(ctx.params.instanceId);
+			const machineType = instance.machineType?.split("/").pop() || "unknown";
+			return {
+				id: `gce://${this.projectId}/${this.zone}/${ctx.params.instanceId}`,
+				path: ctx.path,
+				meta: {
+					kind: KINDS.INSTANCE,
+					kinds: [
+						KINDS.INSTANCE,
+						KINDS.GCP_RESOURCE,
+						KINDS.NODE
+					],
+					childrenCount: -1,
+					status: instance.status,
+					machineType,
+					privateIp: instance.networkInterfaces?.[0]?.networkIP,
+					publicIp: instance.networkInterfaces?.[0]?.accessConfigs?.[0]?.natIP,
+					createdAt: instance.creationTimestamp,
+					labels: instance.labels,
+					platformRef: generateInstancePlatformRef(this.projectId, this.zone, ctx.params.instanceId)
+				}
+			};
+		} catch (error) {
+			throw mapGCEError(error, ctx.path);
+		}
+	}
+	async statRoot(ctx) {
+		const meta = await this.metaRoot(ctx);
 		return { data: {
-			path: entry.path,
-			childrenCount: entry.metadata?.childrenCount,
-			meta: entry.metadata
+			id: meta.id,
+			path: ctx.path,
+			meta: meta.meta
 		} };
 	}
-	/**
-	* Read GCE resource data
-	*/
-	async read(path, options) {
-		return read(this.client, this.projectId, this.zone, path, options);
-	}
-	/**
-	* Write/execute action on GCE resource
-	*
-	* In GCE, write is used to execute actions (start, stop, reset)
-	*/
-	async write(path, _content, _options) {
-		if (this.accessMode !== "readwrite") throw mapGCEError(/* @__PURE__ */ new Error("Write operations require readwrite access mode"));
-		const parsed = parsePath(path);
-		if (parsed.type === "instance-action" || parsed.type === "global-action") {
-			const result = await executeAction(this.client, this.projectId, this.zone, path);
+	async statInstances(ctx) {
+		const meta = await this.metaInstances(ctx);
+		return { data: {
+			id: meta.id,
+			path: ctx.path,
+			meta: meta.meta
+		} };
+	}
+	async statInstance(ctx) {
+		const meta = await this.metaInstance(ctx);
+		return { data: {
+			id: meta.id,
+			path: ctx.path,
+			meta: meta.meta
+		} };
+	}
+	async writeInstanceLabel(ctx, payload) {
+		if (this.accessMode !== "readwrite") throw new AFSReadonlyError("Write operations require readwrite access mode");
+		try {
+			const instance = await this.getInstance(ctx.params.instanceId);
+			const labels = { ...instance.labels || {} };
+			labels[ctx.params.labelKey] = String(payload.content ?? "");
+			await this.client.setLabels({
+				project: this.projectId,
+				zone: this.zone,
+				instance: ctx.params.instanceId,
+				instancesSetLabelsRequestResource: {
+					labels,
+					labelFingerprint: instance.labelFingerprint
+				}
+			});
 			return {
 				data: {
-					id: `gce://${this.projectId}/${this.zone}/${path}`,
-					path,
-					metadata: {
-						kind: KINDS.ACTION,
-						kinds: [
-							KINDS.ACTION,
-							KINDS.EXECUTABLE,
-							KINDS.NODE
-						],
-						success: result.success,
-						operationName: result.operationName,
-						error: result.error
-					}
+					id: `gce://${this.projectId}/${this.zone}/${ctx.params.instanceId}/labels/${ctx.params.labelKey}`,
+					path: ctx.path,
+					content: payload.content,
+					meta: { kind: "gce:label" }
 				},
-				message: result.success ? `Action ${result.action} executed successfully` : `Action ${result.action} failed: ${result.error}`
+				message: `Label '${ctx.params.labelKey}' set on instance '${ctx.params.instanceId}'`
+			};
+		} catch (error) {
+			throw mapGCEError(error, ctx.path);
+		}
+	}
+	async deleteInstanceLabel(ctx) {
+		if (this.accessMode !== "readwrite") throw new AFSReadonlyError("Delete operations require readwrite access mode");
+		try {
+			const instance = await this.getInstance(ctx.params.instanceId);
+			const labels = { ...instance.labels || {} };
+			if (!(ctx.params.labelKey in labels)) throw new AFSNotFoundError(ctx.path, `Label '${ctx.params.labelKey}' not found on instance '${ctx.params.instanceId}'`);
+			delete labels[ctx.params.labelKey];
+			await this.client.setLabels({
+				project: this.projectId,
+				zone: this.zone,
+				instance: ctx.params.instanceId,
+				instancesSetLabelsRequestResource: {
+					labels,
+					labelFingerprint: instance.labelFingerprint
+				}
+			});
+			return { message: `Label '${ctx.params.labelKey}' removed from instance '${ctx.params.instanceId}'` };
+		} catch (error) {
+			if (error instanceof AFSNotFoundError) throw error;
+			throw mapGCEError(error, ctx.path);
+		}
+	}
+	async listGlobalActions(ctx) {
+		return { data: [{
+			id: "refresh",
+			path: joinURL(ctx.path, "refresh"),
+			summary: "Refresh instance cache",
+			meta: {
+				kind: "afs:executable",
+				kinds: ["afs:executable", "afs:node"],
+				inputSchema: {
+					type: "object",
+					properties: {}
+				}
+			}
+		}] };
+	}
+	async refreshAction(_ctx, _args) {
+		return {
+			success: true,
+			data: { message: "Cache refreshed" }
+		};
+	}
+	async listInstanceActions(ctx) {
+		const status = (await this.getInstance(ctx.params.instanceId)).status;
+		const actions = [];
+		switch (status) {
+			case "RUNNING":
+				actions.push({
+					name: "stop",
+					summary: "Stop the instance"
+				}, {
+					name: "reset",
+					summary: "Reset (hard reboot) the instance"
+				});
+				break;
+			case "STOPPED":
+			case "TERMINATED":
+				actions.push({
+					name: "start",
+					summary: "Start the instance"
+				});
+				break;
+			case "SUSPENDED":
+				actions.push({
+					name: "start",
+					summary: "Resume the instance"
+				});
+				break;
+		}
+		return { data: actions.map((action) => ({
+			id: action.name,
+			path: joinURL(ctx.path, action.name),
+			summary: action.summary,
+			meta: {
+				kind: "afs:executable",
+				kinds: ["afs:executable", "afs:node"],
+				inputSchema: {
+					type: "object",
+					properties: {}
+				}
+			}
+		})) };
+	}
+	async startInstanceAction(ctx, _args) {
+		try {
+			const status = (await this.getInstance(ctx.params.instanceId)).status;
+			if (status !== "STOPPED" && status !== "TERMINATED") return {
+				success: false,
+				error: {
+					code: "INVALID_STATE",
+					message: `Cannot start instance in ${status} state. Instance must be STOPPED or TERMINATED.`
+				}
+			};
+			const [operation] = await this.client.start({
+				project: this.projectId,
+				zone: this.zone,
+				instance: ctx.params.instanceId
+			});
+			return {
+				success: true,
+				data: { operationName: operation.latestResponse?.name || "unknown" }
+			};
+		} catch (error) {
+			throw mapGCEError(error, ctx.path);
+		}
+	}
+	async stopInstanceAction(ctx, _args) {
+		try {
+			const status = (await this.getInstance(ctx.params.instanceId)).status;
+			if (status !== "RUNNING") return {
+				success: false,
+				error: {
+					code: "INVALID_STATE",
+					message: `Cannot stop instance in ${status} state. Instance must be RUNNING.`
+				}
+			};
+			const [operation] = await this.client.stop({
+				project: this.projectId,
+				zone: this.zone,
+				instance: ctx.params.instanceId
+			});
+			return {
+				success: true,
+				data: { operationName: operation.latestResponse?.name || "unknown" }
+			};
+		} catch (error) {
+			throw mapGCEError(error, ctx.path);
+		}
+	}
+	async resetInstanceAction(ctx, _args) {
+		try {
+			const status = (await this.getInstance(ctx.params.instanceId)).status;
+			if (status !== "RUNNING") return {
+				success: false,
+				error: {
+					code: "INVALID_STATE",
+					message: `Cannot reset instance in ${status} state. Instance must be RUNNING.`
+				}
+			};
+			const [operation] = await this.client.reset({
+				project: this.projectId,
+				zone: this.zone,
+				instance: ctx.params.instanceId
+			});
+			return {
+				success: true,
+				data: { operationName: operation.latestResponse?.name || "unknown" }
+			};
+		} catch (error) {
+			throw mapGCEError(error, ctx.path);
+		}
+	}
+	async explainRoot(_ctx) {
+		try {
+			const instances = await this.listAllInstances();
+			const byStatus = {};
+			for (const inst of instances) {
+				const status = inst.status || "UNKNOWN";
+				byStatus[status] = (byStatus[status] || 0) + 1;
+			}
+			const statusLines = Object.entries(byStatus).map(([status, count]) => `- **${status}**: ${count}`).join("\n");
+			return {
+				format: "markdown",
+				content: `# GCE Provider
+
+- **Project**: ${this.projectId}
+- **Zone**: ${this.zone}
+- **Access Mode**: ${this.accessMode}
+- **Total Instances**: ${instances.length}
+
+## Instances by Status
+
+${statusLines || "- No instances found"}
+
+## Navigation
+
+- \`/instances/\` — list all instances
+- \`/by-status/\` — instances grouped by status
+- \`/.actions/\` — global actions
+`
+			};
+		} catch (error) {
+			throw mapGCEError(error);
+		}
+	}
+	async explainInstance(ctx) {
+		try {
+			const instance = await this.getInstance(ctx.params.instanceId);
+			const machineType = instance.machineType?.split("/").pop() || "unknown";
+			const privateIp = instance.networkInterfaces?.[0]?.networkIP || "none";
+			const publicIp = instance.networkInterfaces?.[0]?.accessConfigs?.[0]?.natIP || "none";
+			const labels = instance.labels || {};
+			const labelLines = Object.entries(labels).map(([k, v]) => `- \`${k}\`: ${v}`).join("\n");
+			return {
+				format: "markdown",
+				content: `# Instance: ${ctx.params.instanceId}
+
+- **Status**: ${instance.status}
+- **Machine Type**: ${machineType}
+- **Zone**: ${this.zone}
+- **Created**: ${instance.creationTimestamp || "unknown"}
+
+## Network
+
+- **Private IP**: ${privateIp}
+- **Public IP**: ${publicIp}
+
+## Labels
+
+${labelLines || "- No labels"}
+`
 			};
+		} catch (error) {
+			throw mapGCEError(error, ctx.path);
 		}
-		throw mapGCEError(/* @__PURE__ */ new Error(`Cannot write to path: ${path}`));
 	}
 };
+__decorate([List("/")], AFSGCE.prototype, "listRoot", null);
+__decorate([List("/instances")], AFSGCE.prototype, "listInstances", null);
+__decorate([List("/instances/:instanceId"), List("/by-status/:status/:instanceId")], AFSGCE.prototype, "listInstanceChildren", null);
+__decorate([List("/instances/:instanceId/labels"), List("/by-status/:status/:instanceId/labels")], AFSGCE.prototype, "listInstanceLabels", null);
+__decorate([List("/by-status")], AFSGCE.prototype, "listByStatus", null);
+__decorate([List("/by-status/:status")], AFSGCE.prototype, "listByStatusFilter", null);
+__decorate([Read("/.meta/.capabilities")], AFSGCE.prototype, "readCapabilities", null);
+__decorate([Read("/instances/:instanceId/metadata.json"), Read("/by-status/:status/:instanceId/metadata.json")], AFSGCE.prototype, "readInstanceMetadata", null);
+__decorate([Read("/instances/:instanceId/labels/:labelKey"), Read("/by-status/:status/:instanceId/labels/:labelKey")], AFSGCE.prototype, "readInstanceLabel", null);
+__decorate([Meta("/")], AFSGCE.prototype, "metaRoot", null);
+__decorate([Meta("/instances")], AFSGCE.prototype, "metaInstances", null);
+__decorate([Meta("/instances/:instanceId"), Meta("/by-status/:status/:instanceId")], AFSGCE.prototype, "metaInstance", null);
+__decorate([Stat("/")], AFSGCE.prototype, "statRoot", null);
+__decorate([Stat("/instances")], AFSGCE.prototype, "statInstances", null);
+__decorate([Stat("/instances/:instanceId"), Stat("/by-status/:status/:instanceId")], AFSGCE.prototype, "statInstance", null);
+__decorate([Write("/instances/:instanceId/labels/:labelKey"), Write("/by-status/:status/:instanceId/labels/:labelKey")], AFSGCE.prototype, "writeInstanceLabel", null);
+__decorate([Delete("/instances/:instanceId/labels/:labelKey"), Delete("/by-status/:status/:instanceId/labels/:labelKey")], AFSGCE.prototype, "deleteInstanceLabel", null);
+__decorate([Actions("/")], AFSGCE.prototype, "listGlobalActions", null);
+__decorate([Actions.Exec("/", "refresh")], AFSGCE.prototype, "refreshAction", null);
+__decorate([Actions("/instances/:instanceId"), Actions("/by-status/:status/:instanceId")], AFSGCE.prototype, "listInstanceActions", null);
+__decorate([Actions.Exec("/instances/:instanceId", "start"), Actions.Exec("/by-status/:status/:instanceId", "start")], AFSGCE.prototype, "startInstanceAction", null);
+__decorate([Actions.Exec("/instances/:instanceId", "stop"), Actions.Exec("/by-status/:status/:instanceId", "stop")], AFSGCE.prototype, "stopInstanceAction", null);
+__decorate([Actions.Exec("/instances/:instanceId", "reset"), Actions.Exec("/by-status/:status/:instanceId", "reset")], AFSGCE.prototype, "resetInstanceAction", null);
+__decorate([Explain("/")], AFSGCE.prototype, "explainRoot", null);
+__decorate([Explain("/instances/:instanceId"), Explain("/by-status/:status/:instanceId")], AFSGCE.prototype, "explainInstance", null);
 
 //#endregion
 export { AFSGCE, afsgceOptionsSchema };