@aigne/afs-cli 1.11.0-beta.5 → 1.11.0-beta.7

package/dist/core/commands/types.cjs

@@ -0,0 +1,13 @@
+const require_afs_loader = require('../../config/afs-loader.cjs');
+
+//#region src/core/commands/types.ts
+/**
+* Resolve AFS instance: use injected instance or lazy-load from config
+*/
+function resolveAFS(options) {
+	if (options.afs) return Promise.resolve(options.afs);
+	return require_afs_loader.loadAFS(options.cwd ?? process.cwd()).then((result) => result.afs);
+}
+
+//#endregion
+exports.resolveAFS = resolveAFS;

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

@@ -0,0 +1,54 @@
+import { ViewType } from "../types.cjs";
+import { CommandModule } from "yargs";
+import { AFS } from "@aigne/afs";
+
+//#region src/core/commands/types.d.ts
+/**
+ * Format function type for command output
+ *
+ * Uses `any` for result type to allow different AFS result types
+ * (AFSListResult, AFSReadResult, etc.) to be passed to the formatter.
+ */
+type FormatFunction = (result: any, view: ViewType, options?: {
+  path?: string;
+}) => string;
+/**
+ * Command output passed to executor via onResult callback
+ */
+interface CommandOutput {
+  /** The command name (ls, read, write, etc.) */
+  command: string;
+  /** Raw result from AFS operation */
+  result: unknown;
+  /** Format function to convert result to string */
+  format: FormatFunction;
+  /** Error info if command failed (presence indicates failure) */
+  error?: {
+    /** Exit code (from ExitCode enum) */code?: number; /** Error message */
+    message: string;
+  };
+}
+/**
+ * Options passed to command factory functions
+ */
+interface CommandFactoryOptions {
+  /** AFS instance for executing operations (optional: injected in tests, lazy-loaded in production) */
+  afs?: AFS;
+  /** Original command line arguments (for pre-parsing in builder) */
+  argv: string[];
+  /** Callback to pass result back to executor */
+  onResult: (output: CommandOutput) => void;
+  /** Current working directory (for explore command) */
+  cwd?: string;
+}
+/**
+ * Command factory function type
+ *
+ * Uses `any` for CommandModule generics to allow different command
+ * factories (with different argument types) to be stored in a common array.
+ * Each individual factory uses strict types internally.
+ */
+type CommandFactory = (options: CommandFactoryOptions) => CommandModule<unknown, any>;
+//#endregion
+export { CommandFactory, CommandFactoryOptions, CommandOutput, FormatFunction };
+//# sourceMappingURL=types.d.cts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.cts","names":[],"sources":["../../../src/core/commands/types.ts"],"mappings":";;;;;;;;;;;KAiBY,cAAA,IAAkB,MAAA,OAAa,IAAA,EAAM,QAAA,EAAU,OAAA;EAAY,IAAA;AAAA;;;;UAKtD,aAAA;EAIf;EAFA,OAAA;EAIQ;EAFR,MAAA;EAME;EAJF,MAAA,EAAQ,cAAA;EAMC;EAJT,KAAA;IAWe,qCATb,IAAA,WAWI;IATJ,OAAA;EAAA;AAAA;;;;UAOa,qBAAA;EAQf;EANA,GAAA,GAAM,GAAA;EAMH;EAJH,IAAA;EAsBwB;EApBxB,QAAA,GAAW,MAAA,EAAQ,aAAA;EAoByD;EAlB5E,GAAA;AAAA;;;;;;;;KAkBU,cAAA,IAAkB,OAAA,EAAS,qBAAA,KAA0B,aAAA"}

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

@@ -0,0 +1,54 @@
+import { ViewType } from "../types.mjs";
+import { AFS } from "@aigne/afs";
+import { CommandModule } from "yargs";
+
+//#region src/core/commands/types.d.ts
+/**
+ * Format function type for command output
+ *
+ * Uses `any` for result type to allow different AFS result types
+ * (AFSListResult, AFSReadResult, etc.) to be passed to the formatter.
+ */
+type FormatFunction = (result: any, view: ViewType, options?: {
+  path?: string;
+}) => string;
+/**
+ * Command output passed to executor via onResult callback
+ */
+interface CommandOutput {
+  /** The command name (ls, read, write, etc.) */
+  command: string;
+  /** Raw result from AFS operation */
+  result: unknown;
+  /** Format function to convert result to string */
+  format: FormatFunction;
+  /** Error info if command failed (presence indicates failure) */
+  error?: {
+    /** Exit code (from ExitCode enum) */code?: number; /** Error message */
+    message: string;
+  };
+}
+/**
+ * Options passed to command factory functions
+ */
+interface CommandFactoryOptions {
+  /** AFS instance for executing operations (optional: injected in tests, lazy-loaded in production) */
+  afs?: AFS;
+  /** Original command line arguments (for pre-parsing in builder) */
+  argv: string[];
+  /** Callback to pass result back to executor */
+  onResult: (output: CommandOutput) => void;
+  /** Current working directory (for explore command) */
+  cwd?: string;
+}
+/**
+ * Command factory function type
+ *
+ * Uses `any` for CommandModule generics to allow different command
+ * factories (with different argument types) to be stored in a common array.
+ * Each individual factory uses strict types internally.
+ */
+type CommandFactory = (options: CommandFactoryOptions) => CommandModule<unknown, any>;
+//#endregion
+export { CommandFactory, CommandFactoryOptions, CommandOutput, FormatFunction };
+//# sourceMappingURL=types.d.mts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.mts","names":[],"sources":["../../../src/core/commands/types.ts"],"mappings":";;;;;;;;;;;KAiBY,cAAA,IAAkB,MAAA,OAAa,IAAA,EAAM,QAAA,EAAU,OAAA;EAAY,IAAA;AAAA;;;;UAKtD,aAAA;EAIf;EAFA,OAAA;EAIQ;EAFR,MAAA;EAME;EAJF,MAAA,EAAQ,cAAA;EAMC;EAJT,KAAA;IAWe,qCATb,IAAA,WAWI;IATJ,OAAA;EAAA;AAAA;;;;UAOa,qBAAA;EAQf;EANA,GAAA,GAAM,GAAA;EAMH;EAJH,IAAA;EAsBwB;EApBxB,QAAA,GAAW,MAAA,EAAQ,aAAA;EAoByD;EAlB5E,GAAA;AAAA;;;;;;;;KAkBU,cAAA,IAAkB,OAAA,EAAS,qBAAA,KAA0B,aAAA"}

package/dist/core/commands/types.mjs

@@ -0,0 +1,14 @@
+import { loadAFS } from "../../config/afs-loader.mjs";
+
+//#region src/core/commands/types.ts
+/**
+* Resolve AFS instance: use injected instance or lazy-load from config
+*/
+function resolveAFS(options) {
+	if (options.afs) return Promise.resolve(options.afs);
+	return loadAFS(options.cwd ?? process.cwd()).then((result) => result.afs);
+}
+
+//#endregion
+export { resolveAFS };
+//# sourceMappingURL=types.mjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.mjs","names":[],"sources":["../../../src/core/commands/types.ts"],"sourcesContent":["/**\n * Command Factory Types\n *\n * Defines the interface for yargs CommandModule factories.\n */\n\nimport type { AFS } from \"@aigne/afs\";\nimport type { CommandModule } from \"yargs\";\nimport { loadAFS } from \"../../config/afs-loader.js\";\nimport type { ViewType } from \"../types.js\";\n\n/**\n * Format function type for command output\n *\n * Uses `any` for result type to allow different AFS result types\n * (AFSListResult, AFSReadResult, etc.) to be passed to the formatter.\n */\nexport type FormatFunction = (result: any, view: ViewType, options?: { path?: string }) => string;\n\n/**\n * Command output passed to executor via onResult callback\n */\nexport interface CommandOutput {\n  /** The command name (ls, read, write, etc.) */\n  command: string;\n  /** Raw result from AFS operation */\n  result: unknown;\n  /** Format function to convert result to string */\n  format: FormatFunction;\n  /** Error info if command failed (presence indicates failure) */\n  error?: {\n    /** Exit code (from ExitCode enum) */\n    code?: number;\n    /** Error message */\n    message: string;\n  };\n}\n\n/**\n * Options passed to command factory functions\n */\nexport interface CommandFactoryOptions {\n  /** AFS instance for executing operations (optional: injected in tests, lazy-loaded in production) */\n  afs?: AFS;\n  /** Original command line arguments (for pre-parsing in builder) */\n  argv: string[];\n  /** Callback to pass result back to executor */\n  onResult: (output: CommandOutput) => void;\n  /** Current working directory (for explore command) */\n  cwd?: string;\n}\n\n/**\n * Resolve AFS instance: use injected instance or lazy-load from config\n */\nexport function resolveAFS(options: CommandFactoryOptions): Promise<AFS> {\n  if (options.afs) return Promise.resolve(options.afs);\n  return loadAFS(options.cwd ?? process.cwd()).then((result) => result.afs);\n}\n\n/**\n * Command factory function type\n *\n * Uses `any` for CommandModule generics to allow different command\n * factories (with different argument types) to be stored in a common array.\n * Each individual factory uses strict types internally.\n */\nexport type CommandFactory = (options: CommandFactoryOptions) => CommandModule<unknown, any>;\n"],"mappings":";;;;;;AAuDA,SAAgB,WAAW,SAA8C;AACvE,KAAI,QAAQ,IAAK,QAAO,QAAQ,QAAQ,QAAQ,IAAI;AACpD,QAAO,QAAQ,QAAQ,OAAO,QAAQ,KAAK,CAAC,CAAC,MAAM,WAAW,OAAO,IAAI"}

package/dist/core/commands/write.cjs

@@ -0,0 +1,70 @@
+const require_write = require('../formatters/write.cjs');
+const require_path_utils = require('../../path-utils.cjs');
+require('../path-utils.cjs');
+const require_types = require('./types.cjs');
+
+//#region src/core/commands/write.ts
+/**
+* Parse --meta values into metadata object
+*/
+function parseMetaValues(metaValues) {
+	if (!metaValues || metaValues.length === 0) return void 0;
+	const meta = {};
+	for (const item of metaValues) {
+		const idx = item.indexOf("=");
+		if (idx > 0) {
+			const key = item.slice(0, idx);
+			meta[key] = item.slice(idx + 1);
+		}
+	}
+	return Object.keys(meta).length > 0 ? meta : void 0;
+}
+/**
+* Create write command factory
+*/
+function createWriteCommand(options) {
+	return {
+		command: "write <path> [content]",
+		describe: "Write content to file",
+		builder: {
+			path: {
+				type: "string",
+				demandOption: true,
+				description: "Path to write"
+			},
+			content: {
+				type: "string",
+				description: "Content to write"
+			},
+			append: {
+				type: "boolean",
+				description: "Append to file instead of overwriting",
+				default: false
+			},
+			meta: {
+				type: "string",
+				array: true,
+				description: "Set metadata field (key=value)"
+			}
+		},
+		handler: async (argv) => {
+			const metadata = parseMetaValues(argv.meta);
+			const fields = metadata ? Object.keys(metadata) : void 0;
+			if (argv.content === void 0 && !metadata) throw new Error("write requires content (use --content or provide as second argument)");
+			const afs = await require_types.resolveAFS(options);
+			const canonicalPath = require_path_utils.cliPathToCanonical(argv.path);
+			const writeData = {};
+			if (argv.content !== void 0) writeData.content = argv.content;
+			if (metadata) writeData.meta = metadata;
+			const result = await afs.write(canonicalPath, writeData, { append: argv.append });
+			options.onResult({
+				command: "write",
+				result,
+				format: (res, view) => require_write.formatWriteOutput(res, view, { fields })
+			});
+		}
+	};
+}
+
+//#endregion
+exports.createWriteCommand = createWriteCommand;

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

@@ -0,0 +1,20 @@
+import { CommandFactoryOptions } from "./types.cjs";
+import { CommandModule } from "yargs";
+
+//#region src/core/commands/write.d.ts
+/**
+ * Write command arguments
+ */
+interface WriteArgs {
+  path: string;
+  content?: string;
+  append: boolean;
+  meta?: string[];
+}
+/**
+ * Create write command factory
+ */
+declare function createWriteCommand(options: CommandFactoryOptions): CommandModule<unknown, WriteArgs>;
+//#endregion
+export { WriteArgs, createWriteCommand };
+//# sourceMappingURL=write.d.cts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"write.d.cts","names":[],"sources":["../../../src/core/commands/write.ts"],"mappings":";;;;;;;UAgBiB,SAAA;EACf,IAAA;EACA,OAAA;EACA,MAAA;EACA,IAAA;AAAA;;;;iBAwBc,kBAAA,CACd,OAAA,EAAS,qBAAA,GACR,aAAA,UAAuB,SAAA"}

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

@@ -0,0 +1,20 @@
+import { CommandFactoryOptions } from "./types.mjs";
+import { CommandModule } from "yargs";
+
+//#region src/core/commands/write.d.ts
+/**
+ * Write command arguments
+ */
+interface WriteArgs {
+  path: string;
+  content?: string;
+  append: boolean;
+  meta?: string[];
+}
+/**
+ * Create write command factory
+ */
+declare function createWriteCommand(options: CommandFactoryOptions): CommandModule<unknown, WriteArgs>;
+//#endregion
+export { WriteArgs, createWriteCommand };
+//# sourceMappingURL=write.d.mts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"write.d.mts","names":[],"sources":["../../../src/core/commands/write.ts"],"mappings":";;;;;;;UAgBiB,SAAA;EACf,IAAA;EACA,OAAA;EACA,MAAA;EACA,IAAA;AAAA;;;;iBAwBc,kBAAA,CACd,OAAA,EAAS,qBAAA,GACR,aAAA,UAAuB,SAAA"}

package/dist/core/commands/write.mjs

@@ -0,0 +1,71 @@
+import { formatWriteOutput } from "../formatters/write.mjs";
+import { cliPathToCanonical } from "../../path-utils.mjs";
+import "../path-utils.mjs";
+import { resolveAFS } from "./types.mjs";
+
+//#region src/core/commands/write.ts
+/**
+* Parse --meta values into metadata object
+*/
+function parseMetaValues(metaValues) {
+	if (!metaValues || metaValues.length === 0) return void 0;
+	const meta = {};
+	for (const item of metaValues) {
+		const idx = item.indexOf("=");
+		if (idx > 0) {
+			const key = item.slice(0, idx);
+			meta[key] = item.slice(idx + 1);
+		}
+	}
+	return Object.keys(meta).length > 0 ? meta : void 0;
+}
+/**
+* Create write command factory
+*/
+function createWriteCommand(options) {
+	return {
+		command: "write <path> [content]",
+		describe: "Write content to file",
+		builder: {
+			path: {
+				type: "string",
+				demandOption: true,
+				description: "Path to write"
+			},
+			content: {
+				type: "string",
+				description: "Content to write"
+			},
+			append: {
+				type: "boolean",
+				description: "Append to file instead of overwriting",
+				default: false
+			},
+			meta: {
+				type: "string",
+				array: true,
+				description: "Set metadata field (key=value)"
+			}
+		},
+		handler: async (argv) => {
+			const metadata = parseMetaValues(argv.meta);
+			const fields = metadata ? Object.keys(metadata) : void 0;
+			if (argv.content === void 0 && !metadata) throw new Error("write requires content (use --content or provide as second argument)");
+			const afs = await resolveAFS(options);
+			const canonicalPath = cliPathToCanonical(argv.path);
+			const writeData = {};
+			if (argv.content !== void 0) writeData.content = argv.content;
+			if (metadata) writeData.meta = metadata;
+			const result = await afs.write(canonicalPath, writeData, { append: argv.append });
+			options.onResult({
+				command: "write",
+				result,
+				format: (res, view) => formatWriteOutput(res, view, { fields })
+			});
+		}
+	};
+}
+
+//#endregion
+export { createWriteCommand };
+//# sourceMappingURL=write.mjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"write.mjs","names":[],"sources":["../../../src/core/commands/write.ts"],"sourcesContent":["/**\n * write Command - Core Implementation\n *\n * Writes content to a file/node. Accepts AFS instance directly.\n * Returns AFSWriteResult directly (no custom type).\n */\n\nimport type { AFSWriteEntryPayload } from \"@aigne/afs\";\nimport type { CommandModule } from \"yargs\";\nimport { formatWriteOutput } from \"../formatters/index.js\";\nimport { cliPathToCanonical } from \"../path-utils.js\";\nimport { type CommandFactoryOptions, resolveAFS } from \"./types.js\";\n\n/**\n * Write command arguments\n */\nexport interface WriteArgs {\n  path: string;\n  content?: string;\n  append: boolean;\n  meta?: string[];\n}\n\n/**\n * Parse --meta values into metadata object\n */\nfunction parseMetaValues(metaValues?: string[]): Record<string, string> | undefined {\n  if (!metaValues || metaValues.length === 0) return undefined;\n\n  const meta: Record<string, string> = {};\n  for (const item of metaValues) {\n    const idx = item.indexOf(\"=\");\n    if (idx > 0) {\n      const key = item.slice(0, idx);\n      const value = item.slice(idx + 1);\n      meta[key] = value;\n    }\n  }\n  return Object.keys(meta).length > 0 ? meta : undefined;\n}\n\n/**\n * Create write command factory\n */\nexport function createWriteCommand(\n  options: CommandFactoryOptions,\n): CommandModule<unknown, WriteArgs> {\n  return {\n    command: \"write <path> [content]\",\n    describe: \"Write content to file\",\n    builder: {\n      path: {\n        type: \"string\",\n        demandOption: true,\n        description: \"Path to write\",\n      },\n      content: {\n        type: \"string\",\n        description: \"Content to write\",\n      },\n      append: {\n        type: \"boolean\",\n        description: \"Append to file instead of overwriting\",\n        default: false,\n      },\n      meta: {\n        type: \"string\",\n        array: true,\n        description: \"Set metadata field (key=value)\",\n      },\n    },\n    handler: async (argv) => {\n      const metadata = parseMetaValues(argv.meta);\n      const fields = metadata ? Object.keys(metadata) : undefined;\n\n      // Content is required unless only setting metadata\n      if (argv.content === undefined && !metadata) {\n        throw new Error(\"write requires content (use --content or provide as second argument)\");\n      }\n\n      const afs = await resolveAFS(options);\n      const canonicalPath = cliPathToCanonical(argv.path);\n      const writeData: AFSWriteEntryPayload = {};\n\n      if (argv.content !== undefined) {\n        writeData.content = argv.content;\n      }\n      if (metadata) {\n        writeData.meta = metadata;\n      }\n\n      const result = await afs.write(canonicalPath, writeData, { append: argv.append });\n      options.onResult({\n        command: \"write\",\n        result,\n        format: (res, view) => formatWriteOutput(res, view, { fields }),\n      });\n    },\n  };\n}\n"],"mappings":";;;;;;;;;AA0BA,SAAS,gBAAgB,YAA2D;AAClF,KAAI,CAAC,cAAc,WAAW,WAAW,EAAG,QAAO;CAEnD,MAAM,OAA+B,EAAE;AACvC,MAAK,MAAM,QAAQ,YAAY;EAC7B,MAAM,MAAM,KAAK,QAAQ,IAAI;AAC7B,MAAI,MAAM,GAAG;GACX,MAAM,MAAM,KAAK,MAAM,GAAG,IAAI;AAE9B,QAAK,OADS,KAAK,MAAM,MAAM,EAAE;;;AAIrC,QAAO,OAAO,KAAK,KAAK,CAAC,SAAS,IAAI,OAAO;;;;;AAM/C,SAAgB,mBACd,SACmC;AACnC,QAAO;EACL,SAAS;EACT,UAAU;EACV,SAAS;GACP,MAAM;IACJ,MAAM;IACN,cAAc;IACd,aAAa;IACd;GACD,SAAS;IACP,MAAM;IACN,aAAa;IACd;GACD,QAAQ;IACN,MAAM;IACN,aAAa;IACb,SAAS;IACV;GACD,MAAM;IACJ,MAAM;IACN,OAAO;IACP,aAAa;IACd;GACF;EACD,SAAS,OAAO,SAAS;GACvB,MAAM,WAAW,gBAAgB,KAAK,KAAK;GAC3C,MAAM,SAAS,WAAW,OAAO,KAAK,SAAS,GAAG;AAGlD,OAAI,KAAK,YAAY,UAAa,CAAC,SACjC,OAAM,IAAI,MAAM,uEAAuE;GAGzF,MAAM,MAAM,MAAM,WAAW,QAAQ;GACrC,MAAM,gBAAgB,mBAAmB,KAAK,KAAK;GACnD,MAAM,YAAkC,EAAE;AAE1C,OAAI,KAAK,YAAY,OACnB,WAAU,UAAU,KAAK;AAE3B,OAAI,SACF,WAAU,OAAO;GAGnB,MAAM,SAAS,MAAM,IAAI,MAAM,eAAe,WAAW,EAAE,QAAQ,KAAK,QAAQ,CAAC;AACjF,WAAQ,SAAS;IACf,SAAS;IACT;IACA,SAAS,KAAK,SAAS,kBAAkB,KAAK,MAAM,EAAE,QAAQ,CAAC;IAChE,CAAC;;EAEL"}

package/dist/core/executor/index.cjs

@@ -0,0 +1,196 @@
+const require_rolldown_runtime = require('../../_virtual/rolldown_runtime.cjs');
+const require_index = require('../commands/index.cjs');
+let yargs = require("yargs");
+yargs = require_rolldown_runtime.__toESM(yargs);
+
+//#region src/core/executor/index.ts
+/**
+* AFS Command Executor
+*
+* Provides a unified interface for executing AFS commands using yargs.
+*
+* @example
+* ```typescript
+* const executor = new AFSCommandExecutor(afs, { tty: false });
+* const result = await executor.execute("afs ls /path --depth=2");
+* console.log(result.formatted);
+* ```
+*/
+var AFSCommandExecutor = class {
+	afs;
+	options;
+	constructor(afs, options) {
+		this.afs = afs;
+		this.options = options ?? {};
+	}
+	/**
+	* Execute an AFS command
+	*
+	* @param argv - Command string or array of arguments
+	*   - String: "afs ls /path --depth=2" or "ls /path --depth=2"
+	*   - Array: ["ls", "/path", "--depth=2"]
+	* @returns Execution result with formatted output
+	*/
+	async execute(argv) {
+		const normalizedArgs = this.normalizeArgv(argv);
+		let commandResult;
+		const outputOptions = this.extractOutputOptions(normalizedArgs);
+		const factoryOptions = {
+			afs: this.afs,
+			argv: normalizedArgs,
+			cwd: this.options.cwd,
+			onResult: (result) => {
+				commandResult = result;
+			}
+		};
+		let parser = (0, yargs.default)(normalizedArgs).scriptName("afs").usage("$0 <command> [options]").option("json", {
+			type: "boolean",
+			description: "Output in JSON format",
+			global: true
+		}).option("yaml", {
+			type: "boolean",
+			description: "Output in YAML format",
+			global: true
+		}).option("view", {
+			type: "string",
+			choices: [
+				"default",
+				"llm",
+				"human"
+			],
+			default: "default",
+			description: "Output view format",
+			global: true
+		}).option("interactive", {
+			alias: "i",
+			type: "boolean",
+			description: "Start interactive REPL mode",
+			global: false
+		}).help(true).alias("h", "help").version(this.options.version || "unknown").alias("v", "version").demandCommand().showHelpOnFail(true).exitProcess(false);
+		for (const factory of require_index.commandFactories) parser = parser.command(factory(factoryOptions));
+		try {
+			let output;
+			let error;
+			const parsed = await parser.parseAsync(normalizedArgs, {}, (e, _, o) => {
+				if (e) error = e;
+				output = o;
+			});
+			if (error) return {
+				success: false,
+				command: normalizedArgs[0] || "unknown",
+				result: void 0,
+				formatted: output,
+				error: { message: error.message }
+			};
+			if (parsed.help) return {
+				success: true,
+				command: "help",
+				formatted: output
+			};
+			if (parsed.version) return {
+				success: true,
+				command: "version",
+				formatted: output
+			};
+			if (!commandResult) throw new Error("Command not found");
+			const view = outputOptions.json ? "json" : outputOptions.yaml ? "yaml" : outputOptions.view;
+			const formatted = commandResult.format(commandResult.result, view, { path: this.extractPath(normalizedArgs) });
+			if (commandResult.error) return {
+				success: false,
+				command: commandResult.command,
+				result: commandResult.result,
+				formatted,
+				error: commandResult.error
+			};
+			return {
+				success: true,
+				command: commandResult.command,
+				result: commandResult.result,
+				formatted
+			};
+		} catch (error) {
+			const errorMessage = error instanceof Error ? error.message : String(error);
+			return {
+				success: false,
+				command: normalizedArgs[0] || "unknown",
+				result: void 0,
+				formatted: `ERROR: ${errorMessage}`,
+				error: { message: errorMessage }
+			};
+		}
+	}
+	/**
+	* Normalize argv to an array of strings
+	*/
+	normalizeArgv(argv) {
+		if (typeof argv === "string") return this.tokenize(argv);
+		const filtered = [];
+		let foundCommand = false;
+		for (const arg of argv) {
+			if (!foundCommand && (arg.includes("node") || arg.includes("bun") || arg.endsWith(".js") || arg.endsWith(".ts"))) continue;
+			if (!foundCommand && arg === "afs") continue;
+			filtered.push(arg);
+			if (!arg.startsWith("-")) foundCommand = true;
+		}
+		return filtered;
+	}
+	/**
+	* Tokenize a command string, respecting quotes
+	*/
+	tokenize(input) {
+		const tokens = [];
+		let current = "";
+		let inQuote = false;
+		let quoteChar = "";
+		for (let i = 0; i < input.length; i++) {
+			const char = input[i];
+			if (inQuote) if (char === quoteChar) inQuote = false;
+			else current += char;
+			else if (char === "\"" || char === "'") {
+				inQuote = true;
+				quoteChar = char;
+			} else if (char === " " || char === "	") {
+				if (current) {
+					tokens.push(current);
+					current = "";
+				}
+			} else current += char;
+		}
+		if (current) tokens.push(current);
+		if (tokens[0] === "afs") tokens.shift();
+		return tokens;
+	}
+	/**
+	* Extract output options from args
+	*/
+	extractOutputOptions(args) {
+		let json = false;
+		let yaml = false;
+		let view;
+		for (let i = 0; i < args.length; i++) {
+			const arg = args[i];
+			if (arg === "--json") json = true;
+			if (arg === "--yaml") yaml = true;
+			if (arg.startsWith("--view=")) view = arg.slice(7);
+			else if (arg === "--view" && args[i + 1] && !args[i + 1].startsWith("-")) view = args[i + 1];
+		}
+		if (!view) view = this.options.tty ? "human" : "default";
+		return {
+			json,
+			yaml,
+			view
+		};
+	}
+	/**
+	* Extract path from args (first non-option argument after command)
+	*/
+	extractPath(args) {
+		for (let i = 1; i < args.length; i++) {
+			const arg = args[i];
+			if (!arg.startsWith("-")) return arg;
+		}
+	}
+};
+
+//#endregion
+exports.AFSCommandExecutor = AFSCommandExecutor;

package/dist/core/executor/index.d.cts

@@ -0,0 +1,77 @@
+import { AFS } from "@aigne/afs";
+
+//#region src/core/executor/index.d.ts
+/**
+ * Result from executing a command
+ */
+interface ExecuteResult {
+  /** Whether the command executed successfully */
+  success: boolean;
+  /** The command that was executed (ls, read, write, etc.) */
+  command: string;
+  /** The raw result data from AFS */
+  result?: unknown;
+  /** Formatted output string */
+  formatted: string;
+  /** Error info if the command failed */
+  error?: {
+    /** Exit code (from ExitCode enum) */code?: number; /** Error message */
+    message: string;
+  };
+}
+/**
+ * Options for the executor
+ */
+interface ExecutorOptions {
+  /** Whether the output is for a TTY (enables colors) */
+  tty?: boolean;
+  /** Current working directory (for explore command) */
+  cwd?: string;
+  /** Version of the AFS CLI */
+  version?: string;
+}
+/**
+ * AFS Command Executor
+ *
+ * Provides a unified interface for executing AFS commands using yargs.
+ *
+ * @example
+ * ```typescript
+ * const executor = new AFSCommandExecutor(afs, { tty: false });
+ * const result = await executor.execute("afs ls /path --depth=2");
+ * console.log(result.formatted);
+ * ```
+ */
+declare class AFSCommandExecutor {
+  private afs?;
+  private options;
+  constructor(afs?: AFS, options?: ExecutorOptions);
+  /**
+   * Execute an AFS command
+   *
+   * @param argv - Command string or array of arguments
+   *   - String: "afs ls /path --depth=2" or "ls /path --depth=2"
+   *   - Array: ["ls", "/path", "--depth=2"]
+   * @returns Execution result with formatted output
+   */
+  execute(argv: string | string[]): Promise<ExecuteResult>;
+  /**
+   * Normalize argv to an array of strings
+   */
+  private normalizeArgv;
+  /**
+   * Tokenize a command string, respecting quotes
+   */
+  private tokenize;
+  /**
+   * Extract output options from args
+   */
+  private extractOutputOptions;
+  /**
+   * Extract path from args (first non-option argument after command)
+   */
+  private extractPath;
+}
+//#endregion
+export { AFSCommandExecutor, ExecuteResult, ExecutorOptions };
+//# sourceMappingURL=index.d.cts.map

package/dist/core/executor/index.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.cts","names":[],"sources":["../../../src/core/executor/index.ts"],"mappings":";;;;;;UAkBiB,aAAA;EAQf;EANA,OAAA;EAUE;EARF,OAAA;EAUS;EART,MAAA;EAee;EAbf,SAAA;;EAEA,KAAA;IAaA,qCAXE,IAAA,WAeF;IAbE,OAAA;EAAA;AAAA;;;;UAOa,eAAA;EAsCiC;EApChD,GAAA;EAoC+C;EAlC/C,GAAA;EAkBQ;EAhBR,OAAA;AAAA;;;;;;;;;;;;;cAeW,kBAAA;EAAA,QACH,GAAA;EAAA,QACA,OAAA;cAEI,GAAA,GAAM,GAAA,EAAK,OAAA,GAAU,eAAA;;;;;;;;;EAa3B,OAAA,CAAQ,IAAA,sBAA0B,OAAA,CAAQ,aAAA;;;;UA6IxC,aAAA;;;;UAoCA,QAAA;;;;UA2CA,oBAAA;;;;UA+BA,WAAA;AAAA"}