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

package/dist/commands/explain.cjs

@@ -0,0 +1,244 @@
+const require_mount = require('./mount.cjs');
+
+//#region src/commands/explain.ts
+/**
+* Explain AFS concepts or current configuration
+*/
+async function explainCommand(cwd, topic) {
+	switch (topic) {
+		case "mount":
+		case "mounts": return explainMounts(cwd);
+		case "path":
+		case "paths": return explainPaths();
+		case "uri": return explainUri();
+		default: return explainOverview();
+	}
+}
+/**
+* Explain an AFS object at a given path
+*/
+async function explainPathCommand(runtime, path) {
+	const entry = (await runtime.read(path)).data;
+	if (!entry) return {
+		path,
+		type: "unknown"
+	};
+	const metadata = entry.metadata || {};
+	const entryType = metadata.type || "file";
+	const result = {
+		path: entry.path,
+		type: entryType,
+		description: metadata.description,
+		metadata: {}
+	};
+	if (metadata.provider) result.metadata.provider = String(metadata.provider);
+	if (metadata.permissions) {
+		const perms = metadata.permissions;
+		result.metadata.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.metadata).length === 0) delete result.metadata;
+	return result;
+}
+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 -> /modules/{name} -> Provider -> Actual Data`,
+		examples: [
+			"afs mount add /src fs:///path/to/source",
+			"afs ls /modules/src",
+			"afs read /modules/src/file.txt"
+		]
+	};
+}
+async function explainMounts(cwd) {
+	const result = await require_mount.mountListCommand(cwd);
+	if (result.mounts.length === 0) 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.uri}${m.description ? ` (${m.description})` : ""}`).join("\n")}
+
+After mounting, data is accessed via /modules/{name}:
+  path="/src" -> /modules/src`,
+		examples: result.mounts.map((m) => {
+			return `afs ls /modules/${m.path.slice(1).replace(/\//g, "-") || "root"}`;
+		})
+	};
+}
+function explainPaths() {
+	return {
+		topic: "Paths",
+		explanation: `AFS Path Structure:
+
+/                     Root directory
+/modules              All mounted modules
+/modules/{name}       Specific module, name derived from mount path
+
+Path Mapping:
+  config: path="/src"  ->  access: /modules/src
+  config: path="/data" ->  access: /modules/data
+
+Note: The path configured by user is transformed to /modules/{name}`
+	};
+}
+function explainUri() {
+	return {
+		topic: "URI",
+		explanation: `AFS URI Schemes and Objects:
+
+fs://       Local Filesystem Provider
+  Format: fs:///absolute/path or fs://./relative/path
+  Objects:
+    - directory: folder entries, supports list
+    - file: file entries, supports read/write
+  Operations: list, read, write, delete
+
+git://      Git Repository Provider
+  Format: git:///local/repo or git://github.com/user/repo?branch=main
+  Objects:
+    - directory: tree entries
+    - file: blob entries, read-only
+  Operations: list, read
+
+sqlite://   SQLite Database Provider
+  Format: sqlite:///path/to/db.sqlite
+  Objects:
+    - directory: database root, tables list
+    - exec: table entries, supports query operations
+  Operations: list, read, exec (SQL queries)
+
+json://     JSON Data Provider
+  Format: json:///path/to/data.json
+  Objects:
+    - directory: object/array entries
+    - file: primitive values
+  Operations: list, read, write`,
+		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"
+		]
+	};
+}
+/**
+* Format explain output for different views
+*/
+function formatExplainOutput(result, view) {
+	switch (view) {
+		case "json": return JSON.stringify(result, null, 2);
+		case "llm": return formatLlm(result);
+		default: return formatDefault(result);
+	}
+}
+function formatDefault(result) {
+	let output = `${result.topic}\n${"=".repeat(result.topic.length)}\n\n${result.explanation}`;
+	if (result.examples && result.examples.length > 0) output += `\n\nExamples:\n${result.examples.map((e) => `  $ ${e}`).join("\n")}`;
+	return output;
+}
+function formatLlm(result) {
+	const lines = [
+		`TOPIC ${result.topic}`,
+		"",
+		result.explanation
+	];
+	if (result.examples && result.examples.length > 0) {
+		lines.push("", "EXAMPLES");
+		for (const example of result.examples) lines.push(`CMD ${example}`);
+	}
+	return lines.join("\n");
+}
+/**
+* Format object explain output for different views
+*/
+function formatPathExplainOutput(result, view) {
+	switch (view) {
+		case "json": return JSON.stringify(result, null, 2);
+		case "llm": return formatPathLlm(result);
+		default: return formatPathDefault(result);
+	}
+}
+function formatPathDefault(result) {
+	const lines = [];
+	lines.push(`PATH ${result.path}`);
+	lines.push("");
+	lines.push("TYPE");
+	lines.push(result.type);
+	if (result.description) {
+		lines.push("");
+		lines.push("DESCRIPTION");
+		lines.push(result.description);
+	}
+	if (result.inputs && result.inputs.length > 0) {
+		lines.push("");
+		lines.push("INPUTS");
+		for (const input of result.inputs) lines.push(`- ${input}`);
+	}
+	if (result.outputs && result.outputs.length > 0) {
+		lines.push("");
+		lines.push("OUTPUTS");
+		for (const output of result.outputs) lines.push(`- ${output}`);
+	}
+	if (result.errors && result.errors.length > 0) {
+		lines.push("");
+		lines.push("ERRORS");
+		for (const error of result.errors) lines.push(`- ${error}`);
+	}
+	if (result.sideEffects && result.sideEffects.length > 0) {
+		lines.push("");
+		lines.push("SIDE EFFECTS");
+		for (const effect of result.sideEffects) lines.push(`- ${effect}`);
+	} else {
+		lines.push("");
+		lines.push("SIDE EFFECTS");
+		lines.push("- none");
+	}
+	if (result.metadata && Object.keys(result.metadata).length > 0) {
+		lines.push("");
+		lines.push("METADATA");
+		for (const [key, value] of Object.entries(result.metadata)) lines.push(`- ${key}: ${value}`);
+	}
+	return lines.join("\n");
+}
+function formatPathLlm(result) {
+	const lines = [];
+	lines.push(`PATH ${result.path}`);
+	lines.push(`TYPE ${result.type.toUpperCase()}`);
+	if (result.description) lines.push(`DESC ${result.description}`);
+	if (result.inputs && result.inputs.length > 0) lines.push(`INPUTS ${result.inputs.join(", ")}`);
+	if (result.outputs && result.outputs.length > 0) lines.push(`OUTPUTS ${result.outputs.join(", ")}`);
+	if (result.errors && result.errors.length > 0) lines.push(`ERRORS ${result.errors.join(", ")}`);
+	lines.push(`SIDE_EFFECTS ${result.sideEffects?.join(", ") || "none"}`);
+	if (result.metadata) for (const [key, value] of Object.entries(result.metadata)) lines.push(`${key.toUpperCase()} ${value}`);
+	return lines.join("\n");
+}
+
+//#endregion
+exports.explainCommand = explainCommand;
+exports.explainPathCommand = explainPathCommand;
+exports.formatExplainOutput = formatExplainOutput;
+exports.formatPathExplainOutput = formatPathExplainOutput;

package/dist/commands/explain.mjs

@@ -0,0 +1,242 @@
+import { mountListCommand } from "./mount.mjs";
+
+//#region src/commands/explain.ts
+/**
+* Explain AFS concepts or current configuration
+*/
+async function explainCommand(cwd, topic) {
+	switch (topic) {
+		case "mount":
+		case "mounts": return explainMounts(cwd);
+		case "path":
+		case "paths": return explainPaths();
+		case "uri": return explainUri();
+		default: return explainOverview();
+	}
+}
+/**
+* Explain an AFS object at a given path
+*/
+async function explainPathCommand(runtime, path) {
+	const entry = (await runtime.read(path)).data;
+	if (!entry) return {
+		path,
+		type: "unknown"
+	};
+	const metadata = entry.metadata || {};
+	const entryType = metadata.type || "file";
+	const result = {
+		path: entry.path,
+		type: entryType,
+		description: metadata.description,
+		metadata: {}
+	};
+	if (metadata.provider) result.metadata.provider = String(metadata.provider);
+	if (metadata.permissions) {
+		const perms = metadata.permissions;
+		result.metadata.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.metadata).length === 0) delete result.metadata;
+	return result;
+}
+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 -> /modules/{name} -> Provider -> Actual Data`,
+		examples: [
+			"afs mount add /src fs:///path/to/source",
+			"afs ls /modules/src",
+			"afs read /modules/src/file.txt"
+		]
+	};
+}
+async function explainMounts(cwd) {
+	const result = await mountListCommand(cwd);
+	if (result.mounts.length === 0) 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.uri}${m.description ? ` (${m.description})` : ""}`).join("\n")}
+
+After mounting, data is accessed via /modules/{name}:
+  path="/src" -> /modules/src`,
+		examples: result.mounts.map((m) => {
+			return `afs ls /modules/${m.path.slice(1).replace(/\//g, "-") || "root"}`;
+		})
+	};
+}
+function explainPaths() {
+	return {
+		topic: "Paths",
+		explanation: `AFS Path Structure:
+
+/                     Root directory
+/modules              All mounted modules
+/modules/{name}       Specific module, name derived from mount path
+
+Path Mapping:
+  config: path="/src"  ->  access: /modules/src
+  config: path="/data" ->  access: /modules/data
+
+Note: The path configured by user is transformed to /modules/{name}`
+	};
+}
+function explainUri() {
+	return {
+		topic: "URI",
+		explanation: `AFS URI Schemes and Objects:
+
+fs://       Local Filesystem Provider
+  Format: fs:///absolute/path or fs://./relative/path
+  Objects:
+    - directory: folder entries, supports list
+    - file: file entries, supports read/write
+  Operations: list, read, write, delete
+
+git://      Git Repository Provider
+  Format: git:///local/repo or git://github.com/user/repo?branch=main
+  Objects:
+    - directory: tree entries
+    - file: blob entries, read-only
+  Operations: list, read
+
+sqlite://   SQLite Database Provider
+  Format: sqlite:///path/to/db.sqlite
+  Objects:
+    - directory: database root, tables list
+    - exec: table entries, supports query operations
+  Operations: list, read, exec (SQL queries)
+
+json://     JSON Data Provider
+  Format: json:///path/to/data.json
+  Objects:
+    - directory: object/array entries
+    - file: primitive values
+  Operations: list, read, write`,
+		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"
+		]
+	};
+}
+/**
+* Format explain output for different views
+*/
+function formatExplainOutput(result, view) {
+	switch (view) {
+		case "json": return JSON.stringify(result, null, 2);
+		case "llm": return formatLlm(result);
+		default: return formatDefault(result);
+	}
+}
+function formatDefault(result) {
+	let output = `${result.topic}\n${"=".repeat(result.topic.length)}\n\n${result.explanation}`;
+	if (result.examples && result.examples.length > 0) output += `\n\nExamples:\n${result.examples.map((e) => `  $ ${e}`).join("\n")}`;
+	return output;
+}
+function formatLlm(result) {
+	const lines = [
+		`TOPIC ${result.topic}`,
+		"",
+		result.explanation
+	];
+	if (result.examples && result.examples.length > 0) {
+		lines.push("", "EXAMPLES");
+		for (const example of result.examples) lines.push(`CMD ${example}`);
+	}
+	return lines.join("\n");
+}
+/**
+* Format object explain output for different views
+*/
+function formatPathExplainOutput(result, view) {
+	switch (view) {
+		case "json": return JSON.stringify(result, null, 2);
+		case "llm": return formatPathLlm(result);
+		default: return formatPathDefault(result);
+	}
+}
+function formatPathDefault(result) {
+	const lines = [];
+	lines.push(`PATH ${result.path}`);
+	lines.push("");
+	lines.push("TYPE");
+	lines.push(result.type);
+	if (result.description) {
+		lines.push("");
+		lines.push("DESCRIPTION");
+		lines.push(result.description);
+	}
+	if (result.inputs && result.inputs.length > 0) {
+		lines.push("");
+		lines.push("INPUTS");
+		for (const input of result.inputs) lines.push(`- ${input}`);
+	}
+	if (result.outputs && result.outputs.length > 0) {
+		lines.push("");
+		lines.push("OUTPUTS");
+		for (const output of result.outputs) lines.push(`- ${output}`);
+	}
+	if (result.errors && result.errors.length > 0) {
+		lines.push("");
+		lines.push("ERRORS");
+		for (const error of result.errors) lines.push(`- ${error}`);
+	}
+	if (result.sideEffects && result.sideEffects.length > 0) {
+		lines.push("");
+		lines.push("SIDE EFFECTS");
+		for (const effect of result.sideEffects) lines.push(`- ${effect}`);
+	} else {
+		lines.push("");
+		lines.push("SIDE EFFECTS");
+		lines.push("- none");
+	}
+	if (result.metadata && Object.keys(result.metadata).length > 0) {
+		lines.push("");
+		lines.push("METADATA");
+		for (const [key, value] of Object.entries(result.metadata)) lines.push(`- ${key}: ${value}`);
+	}
+	return lines.join("\n");
+}
+function formatPathLlm(result) {
+	const lines = [];
+	lines.push(`PATH ${result.path}`);
+	lines.push(`TYPE ${result.type.toUpperCase()}`);
+	if (result.description) lines.push(`DESC ${result.description}`);
+	if (result.inputs && result.inputs.length > 0) lines.push(`INPUTS ${result.inputs.join(", ")}`);
+	if (result.outputs && result.outputs.length > 0) lines.push(`OUTPUTS ${result.outputs.join(", ")}`);
+	if (result.errors && result.errors.length > 0) lines.push(`ERRORS ${result.errors.join(", ")}`);
+	lines.push(`SIDE_EFFECTS ${result.sideEffects?.join(", ") || "none"}`);
+	if (result.metadata) for (const [key, value] of Object.entries(result.metadata)) lines.push(`${key.toUpperCase()} ${value}`);
+	return lines.join("\n");
+}
+
+//#endregion
+export { explainCommand, explainPathCommand, formatExplainOutput, formatPathExplainOutput };
+//# sourceMappingURL=explain.mjs.map

package/dist/commands/explain.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"explain.mjs","names":[],"sources":["../../src/commands/explain.ts"],"sourcesContent":["import type { AFSRuntime } from \"../runtime.js\";\nimport type { ViewType } from \"./ls.js\";\nimport { mountListCommand } from \"./mount.js\";\n\nexport interface ExplainResult {\n  topic: string;\n  explanation: string;\n  examples?: string[];\n}\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  metadata?: Record<string, string>;\n}\n\n/**\n * Explain AFS concepts or current configuration\n */\nexport async function explainCommand(cwd: string, topic?: string): Promise<ExplainResult> {\n  switch (topic) {\n    case \"mount\":\n    case \"mounts\":\n      return explainMounts(cwd);\n    case \"path\":\n    case \"paths\":\n      return explainPaths();\n    case \"uri\":\n      return explainUri();\n    default:\n      return explainOverview();\n  }\n}\n\n/**\n * Explain an AFS object at a given path\n */\nexport async function explainPathCommand(\n  runtime: AFSRuntime,\n  path: string,\n): Promise<PathExplainResult> {\n  const readResult = await runtime.read(path);\n  const entry = readResult.data;\n\n  if (!entry) {\n    return {\n      path,\n      type: \"unknown\",\n    };\n  }\n\n  const metadata = entry.metadata || {};\n  const entryType = (metadata.type as string) || \"file\";\n\n  const result: PathExplainResult = {\n    path: entry.path,\n    type: entryType,\n    description: metadata.description as string | undefined,\n    metadata: {},\n  };\n\n  // Add metadata\n  if (metadata.provider) {\n    result.metadata!.provider = String(metadata.provider);\n  }\n  if (metadata.permissions) {\n    const perms = metadata.permissions;\n    result.metadata!.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.metadata!).length === 0) {\n    delete result.metadata;\n  }\n\n  return result;\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 -> /modules/{name} -> Provider -> Actual Data`,\n    examples: [\n      \"afs mount add /src fs:///path/to/source\",\n      \"afs ls /modules/src\",\n      \"afs read /modules/src/file.txt\",\n    ],\n  };\n}\n\nasync function explainMounts(cwd: string): Promise<ExplainResult> {\n  const result = await mountListCommand(cwd);\n\n  if (result.mounts.length === 0) {\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.uri}${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 /modules/{name}:\n  path=\"/src\" -> /modules/src`,\n    examples: result.mounts.map((m) => {\n      const name = m.path.slice(1).replace(/\\//g, \"-\") || \"root\";\n      return `afs ls /modules/${name}`;\n    }),\n  };\n}\n\nfunction explainPaths(): ExplainResult {\n  return {\n    topic: \"Paths\",\n    explanation: `AFS Path Structure:\n\n/                     Root directory\n/modules              All mounted modules\n/modules/{name}       Specific module, name derived from mount path\n\nPath Mapping:\n  config: path=\"/src\"  ->  access: /modules/src\n  config: path=\"/data\" ->  access: /modules/data\n\nNote: The path configured by user is transformed to /modules/{name}`,\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  Objects:\n    - directory: folder entries, supports list\n    - file: file entries, supports read/write\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  Objects:\n    - directory: tree entries\n    - file: blob entries, read-only\n  Operations: list, read\n\nsqlite://   SQLite Database Provider\n  Format: sqlite:///path/to/db.sqlite\n  Objects:\n    - directory: database root, tables list\n    - exec: table entries, supports query operations\n  Operations: list, read, exec (SQL queries)\n\njson://     JSON Data Provider\n  Format: json:///path/to/data.json\n  Objects:\n    - directory: object/array entries\n    - file: primitive values\n  Operations: list, read, write`,\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    ],\n  };\n}\n\n/**\n * Format explain output for different views\n */\nexport function formatExplainOutput(result: ExplainResult, view: ViewType): string {\n  switch (view) {\n    case \"json\":\n      return JSON.stringify(result, null, 2);\n    case \"llm\":\n      return formatLlm(result);\n    default:\n      return formatDefault(result);\n  }\n}\n\nfunction formatDefault(result: ExplainResult): string {\n  let output = `${result.topic}\\n${\"=\".repeat(result.topic.length)}\\n\\n${result.explanation}`;\n\n  if (result.examples && result.examples.length > 0) {\n    output += `\\n\\nExamples:\\n${result.examples.map((e) => `  $ ${e}`).join(\"\\n\")}`;\n  }\n\n  return output;\n}\n\nfunction formatLlm(result: ExplainResult): string {\n  const lines = [`TOPIC ${result.topic}`, \"\", result.explanation];\n\n  if (result.examples && result.examples.length > 0) {\n    lines.push(\"\", \"EXAMPLES\");\n    for (const example of result.examples) {\n      lines.push(`CMD ${example}`);\n    }\n  }\n\n  return lines.join(\"\\n\");\n}\n\n/**\n * Format object explain output for different views\n */\nexport function formatPathExplainOutput(result: PathExplainResult, view: ViewType): string {\n  switch (view) {\n    case \"json\":\n      return JSON.stringify(result, null, 2);\n    case \"llm\":\n      return formatPathLlm(result);\n    default:\n      return formatPathDefault(result);\n  }\n}\n\nfunction formatPathDefault(result: PathExplainResult): string {\n  const lines: string[] = [];\n\n  lines.push(`PATH ${result.path}`);\n  lines.push(\"\");\n  lines.push(\"TYPE\");\n  lines.push(result.type);\n\n  if (result.description) {\n    lines.push(\"\");\n    lines.push(\"DESCRIPTION\");\n    lines.push(result.description);\n  }\n\n  if (result.inputs && result.inputs.length > 0) {\n    lines.push(\"\");\n    lines.push(\"INPUTS\");\n    for (const input of result.inputs) {\n      lines.push(`- ${input}`);\n    }\n  }\n\n  if (result.outputs && result.outputs.length > 0) {\n    lines.push(\"\");\n    lines.push(\"OUTPUTS\");\n    for (const output of result.outputs) {\n      lines.push(`- ${output}`);\n    }\n  }\n\n  if (result.errors && result.errors.length > 0) {\n    lines.push(\"\");\n    lines.push(\"ERRORS\");\n    for (const error of result.errors) {\n      lines.push(`- ${error}`);\n    }\n  }\n\n  if (result.sideEffects && result.sideEffects.length > 0) {\n    lines.push(\"\");\n    lines.push(\"SIDE EFFECTS\");\n    for (const effect of result.sideEffects) {\n      lines.push(`- ${effect}`);\n    }\n  } else {\n    lines.push(\"\");\n    lines.push(\"SIDE EFFECTS\");\n    lines.push(\"- none\");\n  }\n\n  if (result.metadata && Object.keys(result.metadata).length > 0) {\n    lines.push(\"\");\n    lines.push(\"METADATA\");\n    for (const [key, value] of Object.entries(result.metadata)) {\n      lines.push(`- ${key}: ${value}`);\n    }\n  }\n\n  return lines.join(\"\\n\");\n}\n\nfunction formatPathLlm(result: PathExplainResult): string {\n  const lines: string[] = [];\n\n  lines.push(`PATH ${result.path}`);\n  lines.push(`TYPE ${result.type.toUpperCase()}`);\n\n  if (result.description) {\n    lines.push(`DESC ${result.description}`);\n  }\n\n  if (result.inputs && result.inputs.length > 0) {\n    lines.push(`INPUTS ${result.inputs.join(\", \")}`);\n  }\n\n  if (result.outputs && result.outputs.length > 0) {\n    lines.push(`OUTPUTS ${result.outputs.join(\", \")}`);\n  }\n\n  if (result.errors && result.errors.length > 0) {\n    lines.push(`ERRORS ${result.errors.join(\", \")}`);\n  }\n\n  lines.push(`SIDE_EFFECTS ${result.sideEffects?.join(\", \") || \"none\"}`);\n\n  if (result.metadata) {\n    for (const [key, value] of Object.entries(result.metadata)) {\n      lines.push(`${key.toUpperCase()} ${value}`);\n    }\n  }\n\n  return lines.join(\"\\n\");\n}\n"],"mappings":"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"}

package/dist/commands/index.cjs

@@ -0,0 +1,7 @@
+const require_exec = require('./exec.cjs');
+const require_mount = require('./mount.cjs');
+const require_explain = require('./explain.cjs');
+const require_ls = require('./ls.cjs');
+const require_read = require('./read.cjs');
+const require_stat = require('./stat.cjs');
+const require_write = require('./write.cjs');

package/dist/commands/index.mjs

@@ -0,0 +1,9 @@
+import { execCommand, formatExecOutput } from "./exec.mjs";
+import { formatMountListOutput, mountAddCommand, mountListCommand, mountRemoveCommand, mountValidateCommand } from "./mount.mjs";
+import { explainCommand, explainPathCommand, formatExplainOutput, formatPathExplainOutput } from "./explain.mjs";
+import { formatLsOutput, lsCommand } from "./ls.mjs";
+import { formatReadOutput, readCommand } from "./read.mjs";
+import { formatStatOutput, statCommand } from "./stat.mjs";
+import { formatWriteOutput, writeCommand } from "./write.mjs";
+
+export {  };

package/dist/commands/ls.cjs

@@ -0,0 +1,136 @@
+
+//#region src/commands/ls.ts
+/**
+* List directory contents
+*/
+async function lsCommand(runtime, path, options = {}) {
+	const result = await runtime.list(path, {
+		maxDepth: options.maxDepth ?? 1,
+		limit: options.limit,
+		maxChildren: options.maxChildren,
+		pattern: options.pattern
+	});
+	const entries = result.data.map((entry) => ({
+		path: entry.path,
+		type: mapEntryType(entry.metadata?.type),
+		size: entry.metadata?.size,
+		modified: entry.updatedAt?.toISOString(),
+		childrenCount: entry.metadata?.childrenCount,
+		childrenTruncated: entry.metadata?.childrenTruncated
+	}));
+	const truncated = entries.some((e) => e.childrenTruncated) || options.limit !== void 0 && entries.length >= options.limit || result.message?.toLowerCase().includes("truncat");
+	return {
+		entries,
+		total: entries.length,
+		truncated,
+		message: result.message
+	};
+}
+function mapEntryType(type) {
+	if (type === "file") return "file";
+	return "directory";
+}
+/**
+* Format ls output for different views
+*/
+function formatLsOutput(result, view) {
+	switch (view) {
+		case "json": return formatJson(result);
+		case "llm": return formatLlm(result);
+		case "human": return formatHuman(result);
+		default: return formatDefault(result);
+	}
+}
+/**
+* Default format: Machine truth, one path per line
+*/
+function formatDefault(result) {
+	const lines = result.entries.map((entry) => entry.path);
+	if (result.truncated) lines.push(`# Results truncated (${result.total} shown)`);
+	return lines.join("\n");
+}
+/**
+* JSON format: Structured output
+*/
+function formatJson(result) {
+	return JSON.stringify({
+		entries: result.entries,
+		total: result.total,
+		truncated: result.truncated,
+		message: result.message
+	}, null, 2);
+}
+/**
+* LLM format: Token-efficient, semantic facts
+*/
+function formatLlm(result) {
+	const lines = [];
+	for (const entry of result.entries) {
+		const parts = [`ENTRY ${entry.path}`];
+		parts.push(`TYPE=${entry.type}`);
+		if (entry.size !== void 0) parts.push(`SIZE=${entry.size}`);
+		if (entry.childrenCount !== void 0) parts.push(`CHILDREN=${entry.childrenCount}`);
+		if (entry.childrenTruncated) parts.push("TRUNCATED");
+		lines.push(parts.join(" "));
+	}
+	lines.push(`TOTAL ${result.total}`);
+	if (result.truncated) lines.push("TRUNCATED true");
+	return lines.join("\n");
+}
+/**
+* Human format: Tree structure
+*/
+function formatHuman(result) {
+	const root = {
+		name: "",
+		children: /* @__PURE__ */ new Map()
+	};
+	for (const entry of result.entries) {
+		const parts = entry.path.split("/").filter(Boolean);
+		let current = root;
+		for (let i = 0; i < parts.length; i++) {
+			const part = parts[i];
+			if (!current.children.has(part)) current.children.set(part, {
+				name: part,
+				children: /* @__PURE__ */ new Map()
+			});
+			current = current.children.get(part);
+			if (i === parts.length - 1) current.entry = entry;
+		}
+	}
+	const lines = [];
+	renderTree(root, "", lines);
+	if (result.truncated) {
+		lines.push("");
+		lines.push(`(Results truncated - ${result.total} entries shown)`);
+	}
+	return lines.join("\n");
+}
+function renderTree(node, prefix, lines) {
+	const children = Array.from(node.children.values());
+	for (let i = 0; i < children.length; i++) {
+		const child = children[i];
+		const isLast = i === children.length - 1;
+		const connector = isLast ? "└── " : "├── ";
+		const icon = child.entry ? getTypeIcon(child.entry.type) : "📂";
+		const sizeStr = child.entry?.size !== void 0 ? `  ${formatSize(child.entry.size)}` : "";
+		lines.push(`${prefix}${connector}${icon} ${child.name}${sizeStr}`);
+		renderTree(child, prefix + (isLast ? "    " : "│   "), lines);
+	}
+}
+function getTypeIcon(type) {
+	switch (type) {
+		case "directory": return "📂";
+		case "file": return "📄";
+		default: return "📄";
+	}
+}
+function formatSize(bytes) {
+	if (bytes < 1024) return `${bytes}B`;
+	if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)}KB`;
+	return `${(bytes / (1024 * 1024)).toFixed(1)}MB`;
+}
+
+//#endregion
+exports.formatLsOutput = formatLsOutput;
+exports.lsCommand = lsCommand;