@aigne/afs-cli 1.11.0-beta.1 → 1.11.0-beta.10

package/dist/core/commands/explain.cjs

@@ -0,0 +1,278 @@
+const require_mount_commands = require('../../config/mount-commands.cjs');
+const require_explain = require('../formatters/explain.cjs');
+const require_path_utils = require('../../path-utils.cjs');
+require('../path-utils.cjs');
+const require_types = require('./types.cjs');
+
+//#region src/core/commands/explain.ts
+/**
+* Create explain command factory
+*/
+function createExplainCommand(options) {
+	return {
+		command: "explain [topic]",
+		describe: "Explain AFS concepts or paths",
+		builder: { topic: {
+			type: "string",
+			description: "Topic (mount, path, uri) or AFS path (e.g., /src)"
+		} },
+		handler: async (argv) => {
+			const target = argv.topic;
+			if (!target) {
+				options.onResult({
+					command: "explain",
+					result: explainOverview(),
+					format: require_explain.formatExplainOutput
+				});
+				return;
+			}
+			if (target.startsWith("/") || target.startsWith("@") || target.startsWith("$")) {
+				const result = await getPathExplanation(await require_types.resolveAFS(options), target, require_path_utils.cliPathToCanonical(target));
+				options.onResult({
+					command: "explain",
+					result,
+					format: require_explain.formatPathExplainOutput
+				});
+			} else {
+				let afs;
+				try {
+					afs = await require_types.resolveAFS(options);
+				} catch {}
+				if (afs) try {
+					const canonicalPath = require_path_utils.cliPathToCanonical(`/${target}`);
+					const explainResult = await afs.explain(canonicalPath);
+					if (explainResult.format === "markdown" && explainResult.content) {
+						options.onResult({
+							command: "explain",
+							result: {
+								path: `/${target}`,
+								type: "explained",
+								markdown: explainResult.content
+							},
+							format: require_explain.formatPathExplainOutput
+						});
+						return;
+					}
+				} catch {}
+				const cwd = options.cwd ?? process.cwd();
+				const result = await getConceptExplanation(target.toLowerCase(), cwd, afs);
+				options.onResult({
+					command: "explain",
+					result,
+					format: require_explain.formatExplainOutput
+				});
+			}
+		}
+	};
+}
+/**
+* Get explanation for a path
+*/
+async function getPathExplanation(afs, path, canonicalPath) {
+	try {
+		try {
+			const explainResult = await afs.explain(canonicalPath);
+			if (explainResult.format === "markdown" && explainResult.content) return {
+				path,
+				type: "explained",
+				markdown: explainResult.content
+			};
+		} catch {}
+		let entry;
+		try {
+			entry = (await afs.stat(canonicalPath)).data;
+		} catch {}
+		if (!entry) try {
+			entry = (await afs.read(canonicalPath)).data;
+		} catch {}
+		if (!entry) return {
+			path,
+			type: "unknown"
+		};
+		const metadata = entry.meta || {};
+		const entryType = metadata.kind === "afs:executable" ? "exec" : typeof metadata.childrenCount === "number" ? "directory" : "file";
+		const result = {
+			path: entry.path,
+			type: entryType,
+			description: metadata.description,
+			meta: {}
+		};
+		if (metadata.provider) result.meta.provider = String(metadata.provider);
+		if (metadata.permissions) {
+			const perms = metadata.permissions;
+			result.meta.permissions = Array.isArray(perms) ? perms.join(", ") : String(perms);
+		}
+		if (entryType === "exec") {
+			if (metadata.inputs) result.inputs = Array.isArray(metadata.inputs) ? metadata.inputs : [String(metadata.inputs)];
+			if (metadata.outputs) result.outputs = Array.isArray(metadata.outputs) ? metadata.outputs : [String(metadata.outputs)];
+			if (metadata.errors) result.errors = Array.isArray(metadata.errors) ? metadata.errors : [String(metadata.errors)];
+			if (metadata.sideEffects) result.sideEffects = Array.isArray(metadata.sideEffects) ? metadata.sideEffects : [String(metadata.sideEffects)];
+		}
+		if (Object.keys(result.meta).length === 0) delete result.meta;
+		return result;
+	} catch (err) {
+		return {
+			path,
+			type: "error",
+			description: err instanceof Error ? err.message : String(err)
+		};
+	}
+}
+/**
+* Get explanation for a concept
+*/
+async function getConceptExplanation(topic, cwd, afs) {
+	switch (topic) {
+		case "mount":
+		case "mounts": return explainMounts(cwd, afs);
+		case "path":
+		case "paths": return explainPaths();
+		case "uri":
+		case "provider":
+		case "providers": return explainUri();
+		default: return {
+			topic: "Unknown Topic",
+			explanation: `Unknown topic: ${topic}\n\nAvailable topics: overview, mount, path, uri`
+		};
+	}
+}
+function explainOverview() {
+	return {
+		topic: "AFS Overview",
+		explanation: `AFS (Abstract File System) is a virtual filesystem that unifies different data sources into a single namespace.
+
+Core Concepts:
+- mount: Mount a data source to a virtual path
+- path: Virtual path, e.g., /src, /data
+- uri: Data source address, e.g., fs://, git://, sqlite://
+
+Data Flow:
+  User Path -> AFS -> /{mount} -> Provider -> Actual Data`,
+		examples: [
+			"afs mount add /src fs:///path/to/source",
+			"afs ls /src",
+			"afs read /src/file.txt"
+		]
+	};
+}
+async function explainMounts(cwd, afs) {
+	const result = await require_mount_commands.configMountListCommand(cwd);
+	if (result.mounts.length === 0) {
+		if (afs) try {
+			const listResult = await afs.list("$afs:/");
+			if (listResult.data?.length) return {
+				topic: "Mounts",
+				explanation: `Runtime mounts (mounted via API):\n\n${listResult.data.map((entry) => `  ${entry.path} (runtime mount)`).join("\n")}`,
+				examples: listResult.data.slice(0, 3).map((entry) => `afs ls ${entry.path}`)
+			};
+		} catch {}
+		return {
+			topic: "Mounts",
+			explanation: `No mounts configured.
+
+Use mount add to add a mount:
+  afs mount add <path> <uri>
+
+path: Virtual path for accessing data in AFS
+uri: Data source URI specifying the data origin`,
+			examples: ["afs mount add /src fs:///Users/me/project", "afs mount add /data sqlite:///data.db"]
+		};
+	}
+	return {
+		topic: "Mounts",
+		explanation: `Current mount configuration:
+
+${result.mounts.map((m) => `  ${m.path}${m.description ? ` - ${m.description}` : ""}`).join("\n")}
+
+After mounting, data is accessed via the mount path:
+  path="/src" -> /src`,
+		examples: result.mounts.map((m) => `afs ls ${m.path}`)
+	};
+}
+function explainPaths() {
+	return {
+		topic: "Paths",
+		explanation: `AFS Path Structure:
+
+/                     Root directory
+/{mount}              Mounted data source
+/{mount}/{path}       Files/nodes within a mount
+
+Path Mapping:
+  config: path="/src"  ->  access: /src
+  config: path="/data" ->  access: /data
+
+Mounts are accessed directly at their configured path.`
+	};
+}
+function explainUri() {
+	return {
+		topic: "URI",
+		explanation: `AFS URI Schemes and Objects:
+
+fs://       Local Filesystem Provider
+  Format: fs:///absolute/path or fs://./relative/path
+  Operations: list, read, write, delete
+
+git://      Git Repository Provider
+  Format: git:///local/repo or git://github.com/user/repo?branch=main
+  Operations: list, read, exec (diff, create-branch, commit, merge)
+
+sqlite://   SQLite Database Provider
+  Format: sqlite:///path/to/db.sqlite
+  Operations: list, read, exec (SQL queries)
+
+json://     JSON Data Provider
+  Format: json:///path/to/data.json
+  Operations: list, read, write
+
+toml://     TOML Data Provider
+  Format: toml:///path/to/config.toml
+  Operations: list, read, write
+
+sandbox://  Sandboxed Script Execution Provider
+  Format: sandbox:///path/to/scripts
+  Operations: list, read, exec
+
+github://   GitHub Issues/PRs Provider
+  Format: github://owner/repo
+  Operations: list, read, exec (create-issue, close-issue, etc.)
+
+http://     HTTP Proxy Provider
+  Format: http://host:port/path
+  Operations: list, read
+
+mcp://      MCP Server Provider
+  Format: mcp:///path/to/server
+  Operations: list, read, exec
+
+s3://       AWS S3 Storage Provider
+  Format: s3://bucket-name
+  Operations: list, read, write, delete
+
+gcs://      Google Cloud Storage Provider
+  Format: gcs://bucket-name
+  Operations: list, read, write, delete
+
+ec2://      AWS EC2 Instances Provider
+  Format: ec2://region
+  Operations: list, read, exec (run-instances)
+
+gce://      Google Compute Engine Provider
+  Format: gce://project/zone
+  Operations: list, read, exec
+
+dns://      Cloud DNS Provider
+  Format: dns://provider (route53, clouddns)
+  Operations: list, read`,
+		examples: [
+			"afs mount add /src fs:///Users/me/project",
+			"afs mount add /repo git://github.com/user/repo",
+			"afs mount add /db sqlite:///data.sqlite",
+			"afs mount add /s3 s3://my-bucket"
+		]
+	};
+}
+
+//#endregion
+exports.createExplainCommand = createExplainCommand;

package/dist/core/commands/explain.d.cts

@@ -0,0 +1,25 @@
+import { CommandFactoryOptions } from "./types.cjs";
+import { CommandModule } from "yargs";
+
+//#region src/core/commands/explain.d.ts
+/**
+ * Result for concept explanations (mount, paths, uri, overview)
+ */
+interface ExplainResult {
+  topic: string;
+  explanation: string;
+  examples?: string[];
+}
+/**
+ * Explain command arguments
+ */
+interface ExplainArgs {
+  topic?: string;
+}
+/**
+ * Create explain command factory
+ */
+declare function createExplainCommand(options: CommandFactoryOptions): CommandModule<unknown, ExplainArgs>;
+//#endregion
+export { ExplainArgs, ExplainResult, createExplainCommand };
+//# sourceMappingURL=explain.d.cts.map

package/dist/core/commands/explain.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"explain.d.cts","names":[],"sources":["../../../src/core/commands/explain.ts"],"mappings":";;;;;;;UAiBiB,aAAA;EACf,KAAA;EACA,WAAA;EACA,QAAA;AAAA;;;;UAsBe,WAAA;EACf,KAAA;AAAA;;;;iBAMc,oBAAA,CACd,OAAA,EAAS,qBAAA,GACR,aAAA,UAAuB,WAAA"}

package/dist/core/commands/explain.d.mts

@@ -0,0 +1,25 @@
+import { CommandFactoryOptions } from "./types.mjs";
+import { CommandModule } from "yargs";
+
+//#region src/core/commands/explain.d.ts
+/**
+ * Result for concept explanations (mount, paths, uri, overview)
+ */
+interface ExplainResult {
+  topic: string;
+  explanation: string;
+  examples?: string[];
+}
+/**
+ * Explain command arguments
+ */
+interface ExplainArgs {
+  topic?: string;
+}
+/**
+ * Create explain command factory
+ */
+declare function createExplainCommand(options: CommandFactoryOptions): CommandModule<unknown, ExplainArgs>;
+//#endregion
+export { ExplainArgs, ExplainResult, createExplainCommand };
+//# sourceMappingURL=explain.d.mts.map

package/dist/core/commands/explain.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"explain.d.mts","names":[],"sources":["../../../src/core/commands/explain.ts"],"mappings":";;;;;;;UAiBiB,aAAA;EACf,KAAA;EACA,WAAA;EACA,QAAA;AAAA;;;;UAsBe,WAAA;EACf,KAAA;AAAA;;;;iBAMc,oBAAA,CACd,OAAA,EAAS,qBAAA,GACR,aAAA,UAAuB,WAAA"}

package/dist/core/commands/explain.mjs

@@ -0,0 +1,279 @@
+import { configMountListCommand } from "../../config/mount-commands.mjs";
+import { formatExplainOutput, formatPathExplainOutput } from "../formatters/explain.mjs";
+import { cliPathToCanonical } from "../../path-utils.mjs";
+import "../path-utils.mjs";
+import { resolveAFS } from "./types.mjs";
+
+//#region src/core/commands/explain.ts
+/**
+* Create explain command factory
+*/
+function createExplainCommand(options) {
+	return {
+		command: "explain [topic]",
+		describe: "Explain AFS concepts or paths",
+		builder: { topic: {
+			type: "string",
+			description: "Topic (mount, path, uri) or AFS path (e.g., /src)"
+		} },
+		handler: async (argv) => {
+			const target = argv.topic;
+			if (!target) {
+				options.onResult({
+					command: "explain",
+					result: explainOverview(),
+					format: formatExplainOutput
+				});
+				return;
+			}
+			if (target.startsWith("/") || target.startsWith("@") || target.startsWith("$")) {
+				const result = await getPathExplanation(await resolveAFS(options), target, cliPathToCanonical(target));
+				options.onResult({
+					command: "explain",
+					result,
+					format: formatPathExplainOutput
+				});
+			} else {
+				let afs;
+				try {
+					afs = await resolveAFS(options);
+				} catch {}
+				if (afs) try {
+					const canonicalPath = cliPathToCanonical(`/${target}`);
+					const explainResult = await afs.explain(canonicalPath);
+					if (explainResult.format === "markdown" && explainResult.content) {
+						options.onResult({
+							command: "explain",
+							result: {
+								path: `/${target}`,
+								type: "explained",
+								markdown: explainResult.content
+							},
+							format: formatPathExplainOutput
+						});
+						return;
+					}
+				} catch {}
+				const cwd = options.cwd ?? process.cwd();
+				const result = await getConceptExplanation(target.toLowerCase(), cwd, afs);
+				options.onResult({
+					command: "explain",
+					result,
+					format: formatExplainOutput
+				});
+			}
+		}
+	};
+}
+/**
+* Get explanation for a path
+*/
+async function getPathExplanation(afs, path, canonicalPath) {
+	try {
+		try {
+			const explainResult = await afs.explain(canonicalPath);
+			if (explainResult.format === "markdown" && explainResult.content) return {
+				path,
+				type: "explained",
+				markdown: explainResult.content
+			};
+		} catch {}
+		let entry;
+		try {
+			entry = (await afs.stat(canonicalPath)).data;
+		} catch {}
+		if (!entry) try {
+			entry = (await afs.read(canonicalPath)).data;
+		} catch {}
+		if (!entry) return {
+			path,
+			type: "unknown"
+		};
+		const metadata = entry.meta || {};
+		const entryType = metadata.kind === "afs:executable" ? "exec" : typeof metadata.childrenCount === "number" ? "directory" : "file";
+		const result = {
+			path: entry.path,
+			type: entryType,
+			description: metadata.description,
+			meta: {}
+		};
+		if (metadata.provider) result.meta.provider = String(metadata.provider);
+		if (metadata.permissions) {
+			const perms = metadata.permissions;
+			result.meta.permissions = Array.isArray(perms) ? perms.join(", ") : String(perms);
+		}
+		if (entryType === "exec") {
+			if (metadata.inputs) result.inputs = Array.isArray(metadata.inputs) ? metadata.inputs : [String(metadata.inputs)];
+			if (metadata.outputs) result.outputs = Array.isArray(metadata.outputs) ? metadata.outputs : [String(metadata.outputs)];
+			if (metadata.errors) result.errors = Array.isArray(metadata.errors) ? metadata.errors : [String(metadata.errors)];
+			if (metadata.sideEffects) result.sideEffects = Array.isArray(metadata.sideEffects) ? metadata.sideEffects : [String(metadata.sideEffects)];
+		}
+		if (Object.keys(result.meta).length === 0) delete result.meta;
+		return result;
+	} catch (err) {
+		return {
+			path,
+			type: "error",
+			description: err instanceof Error ? err.message : String(err)
+		};
+	}
+}
+/**
+* Get explanation for a concept
+*/
+async function getConceptExplanation(topic, cwd, afs) {
+	switch (topic) {
+		case "mount":
+		case "mounts": return explainMounts(cwd, afs);
+		case "path":
+		case "paths": return explainPaths();
+		case "uri":
+		case "provider":
+		case "providers": return explainUri();
+		default: return {
+			topic: "Unknown Topic",
+			explanation: `Unknown topic: ${topic}\n\nAvailable topics: overview, mount, path, uri`
+		};
+	}
+}
+function explainOverview() {
+	return {
+		topic: "AFS Overview",
+		explanation: `AFS (Abstract File System) is a virtual filesystem that unifies different data sources into a single namespace.
+
+Core Concepts:
+- mount: Mount a data source to a virtual path
+- path: Virtual path, e.g., /src, /data
+- uri: Data source address, e.g., fs://, git://, sqlite://
+
+Data Flow:
+  User Path -> AFS -> /{mount} -> Provider -> Actual Data`,
+		examples: [
+			"afs mount add /src fs:///path/to/source",
+			"afs ls /src",
+			"afs read /src/file.txt"
+		]
+	};
+}
+async function explainMounts(cwd, afs) {
+	const result = await configMountListCommand(cwd);
+	if (result.mounts.length === 0) {
+		if (afs) try {
+			const listResult = await afs.list("$afs:/");
+			if (listResult.data?.length) return {
+				topic: "Mounts",
+				explanation: `Runtime mounts (mounted via API):\n\n${listResult.data.map((entry) => `  ${entry.path} (runtime mount)`).join("\n")}`,
+				examples: listResult.data.slice(0, 3).map((entry) => `afs ls ${entry.path}`)
+			};
+		} catch {}
+		return {
+			topic: "Mounts",
+			explanation: `No mounts configured.
+
+Use mount add to add a mount:
+  afs mount add <path> <uri>
+
+path: Virtual path for accessing data in AFS
+uri: Data source URI specifying the data origin`,
+			examples: ["afs mount add /src fs:///Users/me/project", "afs mount add /data sqlite:///data.db"]
+		};
+	}
+	return {
+		topic: "Mounts",
+		explanation: `Current mount configuration:
+
+${result.mounts.map((m) => `  ${m.path}${m.description ? ` - ${m.description}` : ""}`).join("\n")}
+
+After mounting, data is accessed via the mount path:
+  path="/src" -> /src`,
+		examples: result.mounts.map((m) => `afs ls ${m.path}`)
+	};
+}
+function explainPaths() {
+	return {
+		topic: "Paths",
+		explanation: `AFS Path Structure:
+
+/                     Root directory
+/{mount}              Mounted data source
+/{mount}/{path}       Files/nodes within a mount
+
+Path Mapping:
+  config: path="/src"  ->  access: /src
+  config: path="/data" ->  access: /data
+
+Mounts are accessed directly at their configured path.`
+	};
+}
+function explainUri() {
+	return {
+		topic: "URI",
+		explanation: `AFS URI Schemes and Objects:
+
+fs://       Local Filesystem Provider
+  Format: fs:///absolute/path or fs://./relative/path
+  Operations: list, read, write, delete
+
+git://      Git Repository Provider
+  Format: git:///local/repo or git://github.com/user/repo?branch=main
+  Operations: list, read, exec (diff, create-branch, commit, merge)
+
+sqlite://   SQLite Database Provider
+  Format: sqlite:///path/to/db.sqlite
+  Operations: list, read, exec (SQL queries)
+
+json://     JSON Data Provider
+  Format: json:///path/to/data.json
+  Operations: list, read, write
+
+toml://     TOML Data Provider
+  Format: toml:///path/to/config.toml
+  Operations: list, read, write
+
+sandbox://  Sandboxed Script Execution Provider
+  Format: sandbox:///path/to/scripts
+  Operations: list, read, exec
+
+github://   GitHub Issues/PRs Provider
+  Format: github://owner/repo
+  Operations: list, read, exec (create-issue, close-issue, etc.)
+
+http://     HTTP Proxy Provider
+  Format: http://host:port/path
+  Operations: list, read
+
+mcp://      MCP Server Provider
+  Format: mcp:///path/to/server
+  Operations: list, read, exec
+
+s3://       AWS S3 Storage Provider
+  Format: s3://bucket-name
+  Operations: list, read, write, delete
+
+gcs://      Google Cloud Storage Provider
+  Format: gcs://bucket-name
+  Operations: list, read, write, delete
+
+ec2://      AWS EC2 Instances Provider
+  Format: ec2://region
+  Operations: list, read, exec (run-instances)
+
+gce://      Google Compute Engine Provider
+  Format: gce://project/zone
+  Operations: list, read, exec
+
+dns://      Cloud DNS Provider
+  Format: dns://provider (route53, clouddns)
+  Operations: list, read`,
+		examples: [
+			"afs mount add /src fs:///Users/me/project",
+			"afs mount add /repo git://github.com/user/repo",
+			"afs mount add /db sqlite:///data.sqlite",
+			"afs mount add /s3 s3://my-bucket"
+		]
+	};
+}
+
+//#endregion
+export { createExplainCommand };
+//# sourceMappingURL=explain.mjs.map

package/dist/core/commands/explain.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"explain.mjs","names":[],"sources":["../../../src/core/commands/explain.ts"],"sourcesContent":["/**\n * explain Command - Core Implementation\n *\n * Explains AFS paths or concepts.\n * Matches old version output format with topic/explanation/examples structure.\n */\n\nimport type { AFS } from \"@aigne/afs\";\nimport type { CommandModule } from \"yargs\";\nimport { configMountListCommand } from \"../../config/mount-commands.js\";\nimport { formatExplainOutput, formatPathExplainOutput } from \"../formatters/index.js\";\nimport { cliPathToCanonical } from \"../path-utils.js\";\nimport { type CommandFactoryOptions, resolveAFS } from \"./types.js\";\n\n/**\n * Result for concept explanations (mount, paths, uri, overview)\n */\nexport interface ExplainResult {\n  topic: string;\n  explanation: string;\n  examples?: string[];\n}\n\n/**\n * Result for path explanations\n */\nexport interface PathExplainResult {\n  path: string;\n  type: string;\n  description?: string;\n  inputs?: string[];\n  outputs?: string[];\n  errors?: string[];\n  sideEffects?: string[];\n  meta?: Record<string, string>;\n  /** When set, the formatter renders this markdown directly instead of structured fields */\n  markdown?: string;\n}\n\n/**\n * Explain command arguments\n */\nexport interface ExplainArgs {\n  topic?: string;\n}\n\n/**\n * Create explain command factory\n */\nexport function createExplainCommand(\n  options: CommandFactoryOptions,\n): CommandModule<unknown, ExplainArgs> {\n  return {\n    command: \"explain [topic]\",\n    describe: \"Explain AFS concepts or paths\",\n    builder: {\n      topic: {\n        type: \"string\",\n        description: \"Topic (mount, path, uri) or AFS path (e.g., /src)\",\n      },\n    },\n    handler: async (argv) => {\n      const target = argv.topic;\n\n      // No target - explain overview\n      if (!target) {\n        options.onResult({\n          command: \"explain\",\n          result: explainOverview(),\n          format: formatExplainOutput,\n        });\n        return;\n      }\n\n      // Priority: try as path first, then as concept\n      const isPath = target.startsWith(\"/\") || target.startsWith(\"@\") || target.startsWith(\"$\");\n\n      if (isPath) {\n        const afs = await resolveAFS(options);\n        const canonicalPath = cliPathToCanonical(target);\n        const result = await getPathExplanation(afs, target, canonicalPath);\n        options.onResult({ command: \"explain\", result, format: formatPathExplainOutput });\n      } else {\n        // Not obviously a path — try as path first, fall back to concept\n        let afs: AFS | undefined;\n        try {\n          afs = await resolveAFS(options);\n        } catch {}\n\n        if (afs) {\n          try {\n            const canonicalPath = cliPathToCanonical(`/${target}`);\n            const explainResult = await afs.explain(canonicalPath);\n            if (explainResult.format === \"markdown\" && explainResult.content) {\n              options.onResult({\n                command: \"explain\",\n                result: { path: `/${target}`, type: \"explained\", markdown: explainResult.content },\n                format: formatPathExplainOutput,\n              });\n              return;\n            }\n          } catch {\n            // Not a valid path, fall through to concept\n          }\n        }\n\n        const cwd = options.cwd ?? process.cwd();\n        const result = await getConceptExplanation(target.toLowerCase(), cwd, afs);\n        options.onResult({\n          command: \"explain\",\n          result,\n          format: formatExplainOutput,\n        });\n      }\n    },\n  };\n}\n\n/**\n * Get explanation for a path\n */\nasync function getPathExplanation(\n  afs: AFS,\n  path: string,\n  canonicalPath: string,\n): Promise<PathExplainResult> {\n  try {\n    // Always try afs.explain() first — transparent passthrough to provider explain\n    try {\n      const explainResult = await afs.explain(canonicalPath);\n      if (explainResult.format === \"markdown\" && explainResult.content) {\n        return {\n          path,\n          type: \"explained\",\n          markdown: explainResult.content,\n        };\n      }\n    } catch {\n      // explain not available, fall through to stat-based logic\n    }\n\n    // Fallback: stat-based explanation\n    let entry:\n      | { path: string; meta?: Record<string, unknown> | null; content?: unknown }\n      | undefined;\n\n    try {\n      const statResult = await afs.stat(canonicalPath);\n      entry = statResult.data;\n    } catch {}\n\n    if (!entry) {\n      try {\n        const readResult = await afs.read(canonicalPath);\n        entry = readResult.data;\n      } catch {}\n    }\n\n    if (!entry) {\n      return {\n        path,\n        type: \"unknown\",\n      };\n    }\n\n    const metadata = entry.meta || {};\n    // Determine type from childrenCount: if defined, it has children (directory-like); otherwise file-like\n    const entryType =\n      metadata.kind === \"afs:executable\"\n        ? \"exec\"\n        : typeof metadata.childrenCount === \"number\"\n          ? \"directory\"\n          : \"file\";\n\n    const result: PathExplainResult = {\n      path: entry.path,\n      type: entryType,\n      description: metadata.description as string | undefined,\n      meta: {},\n    };\n\n    // Add metadata\n    if (metadata.provider) {\n      result.meta!.provider = String(metadata.provider);\n    }\n    if (metadata.permissions) {\n      const perms = metadata.permissions;\n      result.meta!.permissions = Array.isArray(perms) ? perms.join(\", \") : String(perms);\n    }\n\n    // For exec type, try to get schema info\n    if (entryType === \"exec\") {\n      if (metadata.inputs) {\n        result.inputs = Array.isArray(metadata.inputs)\n          ? (metadata.inputs as string[])\n          : [String(metadata.inputs)];\n      }\n      if (metadata.outputs) {\n        result.outputs = Array.isArray(metadata.outputs)\n          ? (metadata.outputs as string[])\n          : [String(metadata.outputs)];\n      }\n      if (metadata.errors) {\n        result.errors = Array.isArray(metadata.errors)\n          ? (metadata.errors as string[])\n          : [String(metadata.errors)];\n      }\n      if (metadata.sideEffects) {\n        result.sideEffects = Array.isArray(metadata.sideEffects)\n          ? (metadata.sideEffects as string[])\n          : [String(metadata.sideEffects)];\n      }\n    }\n\n    // Clean up empty metadata\n    if (Object.keys(result.meta!).length === 0) {\n      delete result.meta;\n    }\n\n    return result;\n  } catch (err) {\n    return {\n      path,\n      type: \"error\",\n      description: err instanceof Error ? err.message : String(err),\n    };\n  }\n}\n\n/**\n * Get explanation for a concept\n */\nasync function getConceptExplanation(\n  topic: string,\n  cwd: string,\n  afs?: AFS,\n): Promise<ExplainResult> {\n  switch (topic) {\n    case \"mount\":\n    case \"mounts\":\n      return explainMounts(cwd, afs);\n    case \"path\":\n    case \"paths\":\n      return explainPaths();\n    case \"uri\":\n    case \"provider\":\n    case \"providers\":\n      return explainUri();\n    default:\n      return {\n        topic: \"Unknown Topic\",\n        explanation: `Unknown topic: ${topic}\\n\\nAvailable topics: overview, mount, path, uri`,\n      };\n  }\n}\n\nfunction explainOverview(): ExplainResult {\n  return {\n    topic: \"AFS Overview\",\n    explanation: `AFS (Abstract File System) is a virtual filesystem that unifies different data sources into a single namespace.\n\nCore Concepts:\n- mount: Mount a data source to a virtual path\n- path: Virtual path, e.g., /src, /data\n- uri: Data source address, e.g., fs://, git://, sqlite://\n\nData Flow:\n  User Path -> AFS -> /{mount} -> Provider -> Actual Data`,\n    examples: [\"afs mount add /src fs:///path/to/source\", \"afs ls /src\", \"afs read /src/file.txt\"],\n  };\n}\n\nasync function explainMounts(cwd: string, afs?: AFS): Promise<ExplainResult> {\n  const result = await configMountListCommand(cwd);\n\n  if (result.mounts.length === 0) {\n    // Try runtime mounts if no config mounts\n    if (afs) {\n      try {\n        const listResult = await afs.list(\"$afs:/\");\n        if (listResult.data?.length) {\n          const runtimeMounts = listResult.data\n            .map((entry) => `  ${entry.path} (runtime mount)`)\n            .join(\"\\n\");\n\n          return {\n            topic: \"Mounts\",\n            explanation: `Runtime mounts (mounted via API):\\n\\n${runtimeMounts}`,\n            examples: listResult.data.slice(0, 3).map((entry) => `afs ls ${entry.path}`),\n          };\n        }\n      } catch {}\n    }\n\n    return {\n      topic: \"Mounts\",\n      explanation: `No mounts configured.\n\nUse mount add to add a mount:\n  afs mount add <path> <uri>\n\npath: Virtual path for accessing data in AFS\nuri: Data source URI specifying the data origin`,\n      examples: [\n        \"afs mount add /src fs:///Users/me/project\",\n        \"afs mount add /data sqlite:///data.db\",\n      ],\n    };\n  }\n\n  const mountList = result.mounts\n    .map((m) => `  ${m.path}${m.description ? ` - ${m.description}` : \"\"}`)\n    .join(\"\\n\");\n\n  return {\n    topic: \"Mounts\",\n    explanation: `Current mount configuration:\n\n${mountList}\n\nAfter mounting, data is accessed via the mount path:\n  path=\"/src\" -> /src`,\n    examples: result.mounts.map((m) => `afs ls ${m.path}`),\n  };\n}\n\nfunction explainPaths(): ExplainResult {\n  return {\n    topic: \"Paths\",\n    explanation: `AFS Path Structure:\n\n/                     Root directory\n/{mount}              Mounted data source\n/{mount}/{path}       Files/nodes within a mount\n\nPath Mapping:\n  config: path=\"/src\"  ->  access: /src\n  config: path=\"/data\" ->  access: /data\n\nMounts are accessed directly at their configured path.`,\n  };\n}\n\nfunction explainUri(): ExplainResult {\n  return {\n    topic: \"URI\",\n    explanation: `AFS URI Schemes and Objects:\n\nfs://       Local Filesystem Provider\n  Format: fs:///absolute/path or fs://./relative/path\n  Operations: list, read, write, delete\n\ngit://      Git Repository Provider\n  Format: git:///local/repo or git://github.com/user/repo?branch=main\n  Operations: list, read, exec (diff, create-branch, commit, merge)\n\nsqlite://   SQLite Database Provider\n  Format: sqlite:///path/to/db.sqlite\n  Operations: list, read, exec (SQL queries)\n\njson://     JSON Data Provider\n  Format: json:///path/to/data.json\n  Operations: list, read, write\n\ntoml://     TOML Data Provider\n  Format: toml:///path/to/config.toml\n  Operations: list, read, write\n\nsandbox://  Sandboxed Script Execution Provider\n  Format: sandbox:///path/to/scripts\n  Operations: list, read, exec\n\ngithub://   GitHub Issues/PRs Provider\n  Format: github://owner/repo\n  Operations: list, read, exec (create-issue, close-issue, etc.)\n\nhttp://     HTTP Proxy Provider\n  Format: http://host:port/path\n  Operations: list, read\n\nmcp://      MCP Server Provider\n  Format: mcp:///path/to/server\n  Operations: list, read, exec\n\ns3://       AWS S3 Storage Provider\n  Format: s3://bucket-name\n  Operations: list, read, write, delete\n\ngcs://      Google Cloud Storage Provider\n  Format: gcs://bucket-name\n  Operations: list, read, write, delete\n\nec2://      AWS EC2 Instances Provider\n  Format: ec2://region\n  Operations: list, read, exec (run-instances)\n\ngce://      Google Compute Engine Provider\n  Format: gce://project/zone\n  Operations: list, read, exec\n\ndns://      Cloud DNS Provider\n  Format: dns://provider (route53, clouddns)\n  Operations: list, read`,\n    examples: [\n      \"afs mount add /src fs:///Users/me/project\",\n      \"afs mount add /repo git://github.com/user/repo\",\n      \"afs mount add /db sqlite:///data.sqlite\",\n      \"afs mount add /s3 s3://my-bucket\",\n    ],\n  };\n}\n"],"mappings":"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"}

package/dist/core/commands/explore.cjs

@@ -0,0 +1,30 @@
+const require_types = require('./types.cjs');
+const require_version = require('../../version.cjs');
+
+//#region src/core/commands/explore.ts
+/**
+* Create explore command
+*/
+function createExploreCommand(options) {
+	return {
+		command: "explore [path]",
+		describe: "Interactive TUI explorer",
+		builder: { path: {
+			type: "string",
+			default: "/",
+			description: "Starting path"
+		} },
+		handler: async (argv) => {
+			const afs = await require_types.resolveAFS(options);
+			const { createExplorerScreen } = await Promise.resolve().then(() => require("../../explorer/screen.cjs"));
+			await createExplorerScreen({
+				afs,
+				startPath: argv.path,
+				version: require_version.VERSION
+			});
+		}
+	};
+}
+
+//#endregion
+exports.createExploreCommand = createExploreCommand;

package/dist/core/commands/explore.d.mts

@@ -0,0 +1,2 @@
+import "./types.mjs";
+import { CommandModule } from "yargs";