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

package/dist/config/schema.mjs

@@ -0,0 +1,98 @@
+import { AFSPathError, validatePath } from "@aigne/afs";
+import { z } from "zod";
+
+//#region src/config/schema.ts
+/**
+* Characters forbidden in namespace names (security-sensitive)
+*/
+const NAMESPACE_FORBIDDEN_CHARS = [
+	"/",
+	"\\",
+	":",
+	";",
+	"|",
+	"&",
+	"`",
+	"$",
+	"(",
+	")",
+	">",
+	"<",
+	"\n",
+	"\r",
+	"	",
+	"\0"
+];
+/**
+* Validate namespace name
+*/
+function validateNamespace(namespace) {
+	if (!namespace || namespace.trim() === "") throw new Error("Namespace cannot be empty or whitespace-only");
+	for (const char of NAMESPACE_FORBIDDEN_CHARS) if (namespace.includes(char)) throw new Error(`Namespace contains forbidden character: '${char}'`);
+	return namespace;
+}
+/**
+* Mount configuration schema
+*/
+const MountSchema = z.object({
+	path: z.string().transform((val, ctx) => {
+		try {
+			return validatePath(val);
+		} catch (e) {
+			const message = e instanceof AFSPathError ? e.message : "Invalid path";
+			ctx.addIssue({
+				code: z.ZodIssueCode.custom,
+				message
+			});
+			return z.NEVER;
+		}
+	}),
+	uri: z.string().min(1, "URI is required"),
+	namespace: z.string().transform((val, ctx) => {
+		try {
+			return validateNamespace(val);
+		} catch (e) {
+			ctx.addIssue({
+				code: z.ZodIssueCode.custom,
+				message: e instanceof Error ? e.message : "Invalid namespace"
+			});
+			return z.NEVER;
+		}
+	}).optional(),
+	description: z.string().optional(),
+	access_mode: z.enum(["readonly", "readwrite"]).optional(),
+	auth: z.string().optional(),
+	token: z.string().optional(),
+	options: z.record(z.string(), z.unknown()).optional()
+});
+/**
+* Serve configuration schema
+*/
+const ServeSchema = z.object({
+	host: z.string().default("localhost"),
+	port: z.number().int().positive().default(3e3),
+	path: z.string().default("/afs"),
+	readonly: z.boolean().default(false),
+	cors: z.boolean().default(false),
+	max_body_size: z.number().int().positive().default(10 * 1024 * 1024),
+	token: z.string().optional()
+});
+/**
+* Registry configuration schema
+*/
+const RegistrySchema = z.object({
+	enabled: z.boolean().default(true),
+	providers: z.array(z.record(z.string(), z.unknown())).optional()
+});
+/**
+* Root configuration schema for afs.toml
+*/
+const ConfigSchema = z.object({
+	mounts: z.array(MountSchema).default([]),
+	serve: ServeSchema.optional(),
+	registry: RegistrySchema.optional()
+});
+
+//#endregion
+export { ConfigSchema, MountSchema };
+//# sourceMappingURL=schema.mjs.map

package/dist/config/schema.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.mjs","names":[],"sources":["../../src/config/schema.ts"],"sourcesContent":["import { AFSPathError, validatePath } from \"@aigne/afs\";\nimport { z } from \"zod\";\n\n/**\n * Characters forbidden in namespace names (security-sensitive)\n */\nconst NAMESPACE_FORBIDDEN_CHARS = [\n  \"/\", // Path separator\n  \"\\\\\", // Windows path separator\n  \":\", // Namespace separator\n  \";\", // Shell metachar\n  \"|\", // Shell pipe\n  \"&\", // Shell background\n  \"`\", // Shell command substitution\n  \"$\", // Shell variable\n  \"(\", // Shell subshell\n  \")\", // Shell subshell\n  \">\", // Shell redirect\n  \"<\", // Shell redirect\n  \"\\n\", // Newline\n  \"\\r\", // Carriage return\n  \"\\t\", // Tab\n  \"\\x00\", // NUL\n];\n\n/**\n * Validate namespace name\n */\nfunction validateNamespace(namespace: string): string {\n  if (!namespace || namespace.trim() === \"\") {\n    throw new Error(\"Namespace cannot be empty or whitespace-only\");\n  }\n\n  for (const char of NAMESPACE_FORBIDDEN_CHARS) {\n    if (namespace.includes(char)) {\n      throw new Error(`Namespace contains forbidden character: '${char}'`);\n    }\n  }\n\n  return namespace;\n}\n\n/**\n * Mount configuration schema\n */\nexport const MountSchema = z.object({\n  /** Mount path (must follow Unix path semantics) */\n  path: z.string().transform((val, ctx) => {\n    try {\n      return validatePath(val);\n    } catch (e) {\n      const message = e instanceof AFSPathError ? e.message : \"Invalid path\";\n      ctx.addIssue({\n        code: z.ZodIssueCode.custom,\n        message,\n      });\n      return z.NEVER;\n    }\n  }),\n\n  /** Provider URI (e.g., fs:///path, git:///repo?branch=main) */\n  uri: z.string().min(1, \"URI is required\"),\n\n  /** Namespace for this mount (optional, defaults to default namespace) */\n  namespace: z\n    .string()\n    .transform((val, ctx) => {\n      try {\n        return validateNamespace(val);\n      } catch (e) {\n        ctx.addIssue({\n          code: z.ZodIssueCode.custom,\n          message: e instanceof Error ? e.message : \"Invalid namespace\",\n        });\n        return z.NEVER;\n      }\n    })\n    .optional(),\n\n  /** Human/LLM readable description */\n  description: z.string().optional(),\n\n  /** Access mode: readonly or readwrite */\n  access_mode: z.enum([\"readonly\", \"readwrite\"]).optional(),\n\n  /** Authentication string (supports ${ENV_VAR} references) */\n  auth: z.string().optional(),\n\n  /** Authorization token for HTTP providers (supports ${ENV_VAR} references) */\n  token: z.string().optional(),\n\n  /** Provider-specific options (passed through to provider) */\n  options: z.record(z.string(), z.unknown()).optional(),\n});\n\n/**\n * Serve configuration schema\n */\nexport const ServeSchema = z.object({\n  /** Host address to listen on */\n  host: z.string().default(\"localhost\"),\n\n  /** Port to listen on */\n  port: z.number().int().positive().default(3000),\n\n  /** Base path for the server */\n  path: z.string().default(\"/afs\"),\n\n  /** Run in readonly mode (disable write operations) */\n  readonly: z.boolean().default(false),\n\n  /** Enable CORS support */\n  cors: z.boolean().default(false),\n\n  /** Maximum request body size in bytes */\n  max_body_size: z\n    .number()\n    .int()\n    .positive()\n    .default(10 * 1024 * 1024), // 10MB\n\n  /** Bearer token for authorization (supports ${ENV_VAR} references) */\n  token: z.string().optional(),\n});\n\n/**\n * Registry configuration schema\n */\nexport const RegistrySchema = z.object({\n  /** Enable/disable auto-mounting the official registry (default: true) */\n  enabled: z.boolean().default(true),\n\n  /** Static provider manifests (for offline/testing use) */\n  providers: z.array(z.record(z.string(), z.unknown())).optional(),\n});\n\n/**\n * Root configuration schema for afs.toml\n */\nexport const ConfigSchema = z.object({\n  /** List of mount configurations */\n  mounts: z.array(MountSchema).default([]),\n\n  /** HTTP server configuration */\n  serve: ServeSchema.optional(),\n\n  /** Provider registry configuration */\n  registry: RegistrySchema.optional(),\n});\n\n/** Type for a single mount configuration */\nexport type MountConfig = z.infer<typeof MountSchema>;\n\n/** Type for serve configuration */\nexport type ServeConfig = z.infer<typeof ServeSchema>;\n\n/** Type for the root AFS configuration */\nexport type AFSConfig = z.infer<typeof ConfigSchema>;\n"],"mappings":";;;;;;;AAMA,MAAM,4BAA4B;CAChC;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACD;;;;AAKD,SAAS,kBAAkB,WAA2B;AACpD,KAAI,CAAC,aAAa,UAAU,MAAM,KAAK,GACrC,OAAM,IAAI,MAAM,+CAA+C;AAGjE,MAAK,MAAM,QAAQ,0BACjB,KAAI,UAAU,SAAS,KAAK,CAC1B,OAAM,IAAI,MAAM,4CAA4C,KAAK,GAAG;AAIxE,QAAO;;;;;AAMT,MAAa,cAAc,EAAE,OAAO;CAElC,MAAM,EAAE,QAAQ,CAAC,WAAW,KAAK,QAAQ;AACvC,MAAI;AACF,UAAO,aAAa,IAAI;WACjB,GAAG;GACV,MAAM,UAAU,aAAa,eAAe,EAAE,UAAU;AACxD,OAAI,SAAS;IACX,MAAM,EAAE,aAAa;IACrB;IACD,CAAC;AACF,UAAO,EAAE;;GAEX;CAGF,KAAK,EAAE,QAAQ,CAAC,IAAI,GAAG,kBAAkB;CAGzC,WAAW,EACR,QAAQ,CACR,WAAW,KAAK,QAAQ;AACvB,MAAI;AACF,UAAO,kBAAkB,IAAI;WACtB,GAAG;AACV,OAAI,SAAS;IACX,MAAM,EAAE,aAAa;IACrB,SAAS,aAAa,QAAQ,EAAE,UAAU;IAC3C,CAAC;AACF,UAAO,EAAE;;GAEX,CACD,UAAU;CAGb,aAAa,EAAE,QAAQ,CAAC,UAAU;CAGlC,aAAa,EAAE,KAAK,CAAC,YAAY,YAAY,CAAC,CAAC,UAAU;CAGzD,MAAM,EAAE,QAAQ,CAAC,UAAU;CAG3B,OAAO,EAAE,QAAQ,CAAC,UAAU;CAG5B,SAAS,EAAE,OAAO,EAAE,QAAQ,EAAE,EAAE,SAAS,CAAC,CAAC,UAAU;CACtD,CAAC;;;;AAKF,MAAa,cAAc,EAAE,OAAO;CAElC,MAAM,EAAE,QAAQ,CAAC,QAAQ,YAAY;CAGrC,MAAM,EAAE,QAAQ,CAAC,KAAK,CAAC,UAAU,CAAC,QAAQ,IAAK;CAG/C,MAAM,EAAE,QAAQ,CAAC,QAAQ,OAAO;CAGhC,UAAU,EAAE,SAAS,CAAC,QAAQ,MAAM;CAGpC,MAAM,EAAE,SAAS,CAAC,QAAQ,MAAM;CAGhC,eAAe,EACZ,QAAQ,CACR,KAAK,CACL,UAAU,CACV,QAAQ,KAAK,OAAO,KAAK;CAG5B,OAAO,EAAE,QAAQ,CAAC,UAAU;CAC7B,CAAC;;;;AAKF,MAAa,iBAAiB,EAAE,OAAO;CAErC,SAAS,EAAE,SAAS,CAAC,QAAQ,KAAK;CAGlC,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE,EAAE,SAAS,CAAC,CAAC,CAAC,UAAU;CACjE,CAAC;;;;AAKF,MAAa,eAAe,EAAE,OAAO;CAEnC,QAAQ,EAAE,MAAM,YAAY,CAAC,QAAQ,EAAE,CAAC;CAGxC,OAAO,YAAY,UAAU;CAG7B,UAAU,eAAe,UAAU;CACpC,CAAC"}

package/dist/core/commands/delete.cjs

@@ -0,0 +1,41 @@
+const require_delete = require('../formatters/delete.cjs');
+const require_path_utils = require('../../path-utils.cjs');
+require('../path-utils.cjs');
+const require_types = require('./types.cjs');
+
+//#region src/core/commands/delete.ts
+/**
+* Create delete command factory
+*/
+function createDeleteCommand(options) {
+	return {
+		command: ["delete <path>", "rm <path>"],
+		describe: "Delete file or directory",
+		builder: {
+			path: {
+				type: "string",
+				demandOption: true,
+				description: "Path to delete"
+			},
+			recursive: {
+				alias: "r",
+				type: "boolean",
+				default: false,
+				description: "Delete directory recursively"
+			}
+		},
+		handler: async (argv) => {
+			const afs = await require_types.resolveAFS(options);
+			const canonicalPath = require_path_utils.cliPathToCanonical(argv.path);
+			const result = await afs.delete(canonicalPath, { recursive: argv.recursive });
+			options.onResult({
+				command: "delete",
+				result,
+				format: require_delete.formatDeleteOutput
+			});
+		}
+	};
+}
+
+//#endregion
+exports.createDeleteCommand = createDeleteCommand;

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

@@ -0,0 +1,18 @@
+import { CommandFactoryOptions } from "./types.cjs";
+import { CommandModule } from "yargs";
+
+//#region src/core/commands/delete.d.ts
+/**
+ * Delete command arguments
+ */
+interface DeleteArgs {
+  path: string;
+  recursive: boolean;
+}
+/**
+ * Create delete command factory
+ */
+declare function createDeleteCommand(options: CommandFactoryOptions): CommandModule<unknown, DeleteArgs>;
+//#endregion
+export { DeleteArgs, createDeleteCommand };
+//# sourceMappingURL=delete.d.cts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"delete.d.cts","names":[],"sources":["../../../src/core/commands/delete.ts"],"mappings":";;;;;AAuBA;;UARiB,UAAA;EACf,IAAA;EACA,SAAA;AAAA;;;;iBAMc,mBAAA,CACd,OAAA,EAAS,qBAAA,GACR,aAAA,UAAuB,UAAA"}

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

@@ -0,0 +1,18 @@
+import { CommandFactoryOptions } from "./types.mjs";
+import { CommandModule } from "yargs";
+
+//#region src/core/commands/delete.d.ts
+/**
+ * Delete command arguments
+ */
+interface DeleteArgs {
+  path: string;
+  recursive: boolean;
+}
+/**
+ * Create delete command factory
+ */
+declare function createDeleteCommand(options: CommandFactoryOptions): CommandModule<unknown, DeleteArgs>;
+//#endregion
+export { DeleteArgs, createDeleteCommand };
+//# sourceMappingURL=delete.d.mts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"delete.d.mts","names":[],"sources":["../../../src/core/commands/delete.ts"],"mappings":";;;;;AAuBA;;UARiB,UAAA;EACf,IAAA;EACA,SAAA;AAAA;;;;iBAMc,mBAAA,CACd,OAAA,EAAS,qBAAA,GACR,aAAA,UAAuB,UAAA"}

package/dist/core/commands/delete.mjs

@@ -0,0 +1,42 @@
+import { formatDeleteOutput } from "../formatters/delete.mjs";
+import { cliPathToCanonical } from "../../path-utils.mjs";
+import "../path-utils.mjs";
+import { resolveAFS } from "./types.mjs";
+
+//#region src/core/commands/delete.ts
+/**
+* Create delete command factory
+*/
+function createDeleteCommand(options) {
+	return {
+		command: ["delete <path>", "rm <path>"],
+		describe: "Delete file or directory",
+		builder: {
+			path: {
+				type: "string",
+				demandOption: true,
+				description: "Path to delete"
+			},
+			recursive: {
+				alias: "r",
+				type: "boolean",
+				default: false,
+				description: "Delete directory recursively"
+			}
+		},
+		handler: async (argv) => {
+			const afs = await resolveAFS(options);
+			const canonicalPath = cliPathToCanonical(argv.path);
+			const result = await afs.delete(canonicalPath, { recursive: argv.recursive });
+			options.onResult({
+				command: "delete",
+				result,
+				format: formatDeleteOutput
+			});
+		}
+	};
+}
+
+//#endregion
+export { createDeleteCommand };
+//# sourceMappingURL=delete.mjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"delete.mjs","names":[],"sources":["../../../src/core/commands/delete.ts"],"sourcesContent":["/**\n * delete Command - Core Implementation\n *\n * Deletes files/directories. Accepts AFS instance directly.\n * Returns AFSDeleteResult directly (no custom type).\n */\n\nimport type { CommandModule } from \"yargs\";\nimport { formatDeleteOutput } from \"../formatters/index.js\";\nimport { cliPathToCanonical } from \"../path-utils.js\";\nimport { type CommandFactoryOptions, resolveAFS } from \"./types.js\";\n\n/**\n * Delete command arguments\n */\nexport interface DeleteArgs {\n  path: string;\n  recursive: boolean;\n}\n\n/**\n * Create delete command factory\n */\nexport function createDeleteCommand(\n  options: CommandFactoryOptions,\n): CommandModule<unknown, DeleteArgs> {\n  return {\n    command: [\"delete <path>\", \"rm <path>\"],\n    describe: \"Delete file or directory\",\n    builder: {\n      path: {\n        type: \"string\",\n        demandOption: true,\n        description: \"Path to delete\",\n      },\n      recursive: {\n        alias: \"r\",\n        type: \"boolean\",\n        default: false,\n        description: \"Delete directory recursively\",\n      },\n    },\n    handler: async (argv) => {\n      const afs = await resolveAFS(options);\n      const canonicalPath = cliPathToCanonical(argv.path);\n      const result = await afs.delete(canonicalPath, { recursive: argv.recursive });\n      options.onResult({\n        command: \"delete\",\n        result,\n        format: formatDeleteOutput,\n      });\n    },\n  };\n}\n"],"mappings":";;;;;;;;;AAuBA,SAAgB,oBACd,SACoC;AACpC,QAAO;EACL,SAAS,CAAC,iBAAiB,YAAY;EACvC,UAAU;EACV,SAAS;GACP,MAAM;IACJ,MAAM;IACN,cAAc;IACd,aAAa;IACd;GACD,WAAW;IACT,OAAO;IACP,MAAM;IACN,SAAS;IACT,aAAa;IACd;GACF;EACD,SAAS,OAAO,SAAS;GACvB,MAAM,MAAM,MAAM,WAAW,QAAQ;GACrC,MAAM,gBAAgB,mBAAmB,KAAK,KAAK;GACnD,MAAM,SAAS,MAAM,IAAI,OAAO,eAAe,EAAE,WAAW,KAAK,WAAW,CAAC;AAC7E,WAAQ,SAAS;IACf,SAAS;IACT;IACA,QAAQ;IACT,CAAC;;EAEL"}

package/dist/core/commands/exec.cjs

@@ -0,0 +1,98 @@
+const require_exec = require('../formatters/exec.cjs');
+const require_path_utils = require('../../path-utils.cjs');
+require('../path-utils.cjs');
+const require_types = require('./types.cjs');
+const require_exec_args = require('../helpers/exec-args.cjs');
+
+//#region src/core/commands/exec.ts
+/**
+* Fetch action metadata (description, inputSchema)
+*/
+async function fetchActionMeta(afs, path) {
+	const canonicalPath = require_path_utils.cliPathToCanonical(path);
+	try {
+		const readResult = await afs.read(canonicalPath);
+		const meta = readResult.data?.meta ?? {};
+		const content = readResult.data?.content ?? {};
+		const firstAction = readResult.data?.actions?.[0];
+		return {
+			description: meta.description ?? content.description ?? firstAction?.description ?? readResult.data?.summary,
+			inputSchema: meta.inputSchema ?? content.inputSchema ?? firstAction?.inputSchema
+		};
+	} catch {
+		return {};
+	}
+}
+/**
+* Create exec command factory
+*
+* This command has special handling:
+* 1. Factory function caches inputSchema
+* 2. Builder pre-parses argv to get action path
+* 3. Dynamically adds options from inputSchema
+*/
+function createExecCommand(options) {
+	let cachedSchema;
+	let resolvedExecAction;
+	return {
+		command: "exec <executable_path>",
+		describe: "Execute an action",
+		builder: async (yargs) => {
+			const execIndex = options.argv.indexOf("exec");
+			const actionArg = execIndex >= 0 ? options.argv[execIndex + 1] : void 0;
+			if (actionArg && typeof actionArg === "string" && !actionArg.startsWith("-")) {
+				resolvedExecAction = actionArg;
+				const actionMeta = await fetchActionMeta(await require_types.resolveAFS(options), actionArg);
+				cachedSchema = actionMeta.inputSchema;
+				const description = actionMeta.description || "Execute an action";
+				yargs.usage(`afs exec ${actionArg}\n\n${description}`);
+				const hasArgsOption = options.argv.includes("--args");
+				if (cachedSchema?.properties) for (const [name, propSchema] of Object.entries(cachedSchema.properties)) {
+					const prop = propSchema;
+					let description$1 = prop.description || "";
+					if (prop.type === "object" && prop.properties) {
+						const subKeys = Object.keys(prop.properties).join(", ");
+						description$1 += `${description$1 ? " " : ""}(JSON object with: ${subKeys})`;
+					}
+					const optConfig = {
+						type: require_exec_args.schemaTypeToYargs(prop.type),
+						description: description$1 || void 0,
+						group: "Action Parameters:"
+					};
+					if (prop.default !== void 0) optConfig.default = prop.default;
+					if (!hasArgsOption && cachedSchema.required?.includes(name)) {
+						if (!(prop.sensitive === true || Array.isArray(prop.env))) optConfig.demandOption = true;
+					}
+					yargs.option(name, optConfig);
+				}
+			}
+			return yargs.positional("executable_path", {
+				type: "string",
+				demandOption: true,
+				description: "Action path to execute"
+			}).option("args", {
+				type: "string",
+				description: "JSON arguments: --args '{\"key\": \"value\"}'"
+			}).strict(false);
+		},
+		handler: async (argv) => {
+			const afs = await require_types.resolveAFS(options);
+			const execPath = resolvedExecAction ?? argv.executable_path;
+			const schema = cachedSchema ?? (await fetchActionMeta(afs, execPath)).inputSchema;
+			const argvForParsing = { ...argv };
+			delete argvForParsing.executable_path;
+			delete argvForParsing.executablePath;
+			const execArgs = require_exec_args.parseExecArgs(argvForParsing, schema);
+			const canonicalPath = require_path_utils.cliPathToCanonical(execPath);
+			const result = await afs.exec(canonicalPath, execArgs, {});
+			options.onResult({
+				command: "exec",
+				result,
+				format: require_exec.formatExecOutput
+			});
+		}
+	};
+}
+
+//#endregion
+exports.createExecCommand = createExecCommand;

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

@@ -0,0 +1,26 @@
+import { CommandFactoryOptions } from "./types.cjs";
+import { parseExecArgs, parseValueBySchema } from "../helpers/exec-args.cjs";
+import { CommandModule } from "yargs";
+
+//#region src/core/commands/exec.d.ts
+/**
+ * Exec command base arguments (known fields)
+ * Note: Dynamic options are added from inputSchema at runtime
+ */
+interface ExecArgs {
+  executable_path: string;
+  args?: string;
+  [key: string]: unknown;
+}
+/**
+ * Create exec command factory
+ *
+ * This command has special handling:
+ * 1. Factory function caches inputSchema
+ * 2. Builder pre-parses argv to get action path
+ * 3. Dynamically adds options from inputSchema
+ */
+declare function createExecCommand(options: CommandFactoryOptions): CommandModule<unknown, ExecArgs>;
+//#endregion
+export { ExecArgs, createExecCommand };
+//# sourceMappingURL=exec.d.cts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"exec.d.cts","names":[],"sources":["../../../src/core/commands/exec.ts"],"mappings":";;;;;AAsEA;;;;AAAA,UA5CiB,QAAA;EACf,eAAA;EACA,IAAA;EAAA,CACC,GAAA;AAAA;;;;;;;;;iBAyCa,iBAAA,CACd,OAAA,EAAS,qBAAA,GACR,aAAA,UAAuB,QAAA"}

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

@@ -0,0 +1,26 @@
+import { CommandFactoryOptions } from "./types.mjs";
+import { parseExecArgs, parseValueBySchema } from "../helpers/exec-args.mjs";
+import { CommandModule } from "yargs";
+
+//#region src/core/commands/exec.d.ts
+/**
+ * Exec command base arguments (known fields)
+ * Note: Dynamic options are added from inputSchema at runtime
+ */
+interface ExecArgs {
+  executable_path: string;
+  args?: string;
+  [key: string]: unknown;
+}
+/**
+ * Create exec command factory
+ *
+ * This command has special handling:
+ * 1. Factory function caches inputSchema
+ * 2. Builder pre-parses argv to get action path
+ * 3. Dynamically adds options from inputSchema
+ */
+declare function createExecCommand(options: CommandFactoryOptions): CommandModule<unknown, ExecArgs>;
+//#endregion
+export { ExecArgs, createExecCommand };
+//# sourceMappingURL=exec.d.mts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"exec.d.mts","names":[],"sources":["../../../src/core/commands/exec.ts"],"mappings":";;;;;AAsEA;;;;AAAA,UA5CiB,QAAA;EACf,eAAA;EACA,IAAA;EAAA,CACC,GAAA;AAAA;;;;;;;;;iBAyCa,iBAAA,CACd,OAAA,EAAS,qBAAA,GACR,aAAA,UAAuB,QAAA"}

package/dist/core/commands/exec.mjs

@@ -0,0 +1,99 @@
+import { formatExecOutput } from "../formatters/exec.mjs";
+import { cliPathToCanonical } from "../../path-utils.mjs";
+import "../path-utils.mjs";
+import { resolveAFS } from "./types.mjs";
+import { parseExecArgs, parseValueBySchema, schemaTypeToYargs } from "../helpers/exec-args.mjs";
+
+//#region src/core/commands/exec.ts
+/**
+* Fetch action metadata (description, inputSchema)
+*/
+async function fetchActionMeta(afs, path) {
+	const canonicalPath = cliPathToCanonical(path);
+	try {
+		const readResult = await afs.read(canonicalPath);
+		const meta = readResult.data?.meta ?? {};
+		const content = readResult.data?.content ?? {};
+		const firstAction = readResult.data?.actions?.[0];
+		return {
+			description: meta.description ?? content.description ?? firstAction?.description ?? readResult.data?.summary,
+			inputSchema: meta.inputSchema ?? content.inputSchema ?? firstAction?.inputSchema
+		};
+	} catch {
+		return {};
+	}
+}
+/**
+* Create exec command factory
+*
+* This command has special handling:
+* 1. Factory function caches inputSchema
+* 2. Builder pre-parses argv to get action path
+* 3. Dynamically adds options from inputSchema
+*/
+function createExecCommand(options) {
+	let cachedSchema;
+	let resolvedExecAction;
+	return {
+		command: "exec <executable_path>",
+		describe: "Execute an action",
+		builder: async (yargs) => {
+			const execIndex = options.argv.indexOf("exec");
+			const actionArg = execIndex >= 0 ? options.argv[execIndex + 1] : void 0;
+			if (actionArg && typeof actionArg === "string" && !actionArg.startsWith("-")) {
+				resolvedExecAction = actionArg;
+				const actionMeta = await fetchActionMeta(await resolveAFS(options), actionArg);
+				cachedSchema = actionMeta.inputSchema;
+				const description = actionMeta.description || "Execute an action";
+				yargs.usage(`afs exec ${actionArg}\n\n${description}`);
+				const hasArgsOption = options.argv.includes("--args");
+				if (cachedSchema?.properties) for (const [name, propSchema] of Object.entries(cachedSchema.properties)) {
+					const prop = propSchema;
+					let description$1 = prop.description || "";
+					if (prop.type === "object" && prop.properties) {
+						const subKeys = Object.keys(prop.properties).join(", ");
+						description$1 += `${description$1 ? " " : ""}(JSON object with: ${subKeys})`;
+					}
+					const optConfig = {
+						type: schemaTypeToYargs(prop.type),
+						description: description$1 || void 0,
+						group: "Action Parameters:"
+					};
+					if (prop.default !== void 0) optConfig.default = prop.default;
+					if (!hasArgsOption && cachedSchema.required?.includes(name)) {
+						if (!(prop.sensitive === true || Array.isArray(prop.env))) optConfig.demandOption = true;
+					}
+					yargs.option(name, optConfig);
+				}
+			}
+			return yargs.positional("executable_path", {
+				type: "string",
+				demandOption: true,
+				description: "Action path to execute"
+			}).option("args", {
+				type: "string",
+				description: "JSON arguments: --args '{\"key\": \"value\"}'"
+			}).strict(false);
+		},
+		handler: async (argv) => {
+			const afs = await resolveAFS(options);
+			const execPath = resolvedExecAction ?? argv.executable_path;
+			const schema = cachedSchema ?? (await fetchActionMeta(afs, execPath)).inputSchema;
+			const argvForParsing = { ...argv };
+			delete argvForParsing.executable_path;
+			delete argvForParsing.executablePath;
+			const execArgs = parseExecArgs(argvForParsing, schema);
+			const canonicalPath = cliPathToCanonical(execPath);
+			const result = await afs.exec(canonicalPath, execArgs, {});
+			options.onResult({
+				command: "exec",
+				result,
+				format: formatExecOutput
+			});
+		}
+	};
+}
+
+//#endregion
+export { createExecCommand };
+//# sourceMappingURL=exec.mjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"exec.mjs","names":["description"],"sources":["../../../src/core/commands/exec.ts"],"sourcesContent":["/**\n * exec Command - Core Implementation\n *\n * Executes actions on AFS paths. Accepts AFS instance directly.\n * Returns AFSExecResult directly (no custom type).\n *\n * NOTE: The yargs positional is named \"executable_path\" to avoid name collisions\n * with action inputSchema properties. Common schema property names like \"path\",\n * \"action\", \"name\" etc. won't collide with this compound internal name.\n */\n\nimport type { AFS } from \"@aigne/afs\";\nimport type { CommandModule, Options } from \"yargs\";\nimport { formatExecOutput } from \"../formatters/index.js\";\nimport { parseExecArgs, parseValueBySchema, schemaTypeToYargs } from \"../helpers/exec-args.js\";\nimport { cliPathToCanonical } from \"../path-utils.js\";\nimport type { JSONSchema } from \"../types.js\";\nimport { type CommandFactoryOptions, resolveAFS } from \"./types.js\";\n\n// Re-export helpers for backward compatibility\nexport { parseExecArgs, parseValueBySchema };\n\n/**\n * Exec command base arguments (known fields)\n * Note: Dynamic options are added from inputSchema at runtime\n */\nexport interface ExecArgs {\n  executable_path: string;\n  args?: string;\n  [key: string]: unknown;\n}\n\n/**\n * Fetch action metadata (description, inputSchema)\n */\nasync function fetchActionMeta(\n  afs: AFS,\n  path: string,\n): Promise<{ description?: string; inputSchema?: JSONSchema }> {\n  const canonicalPath = cliPathToCanonical(path);\n\n  try {\n    const readResult = await afs.read(canonicalPath);\n    const meta = readResult.data?.meta ?? {};\n    const content = readResult.data?.content ?? {};\n    // Actions list entries may carry inputSchema in the actions array\n    const firstAction = readResult.data?.actions?.[0];\n\n    return {\n      description: (meta.description ??\n        content.description ??\n        firstAction?.description ??\n        readResult.data?.summary) as string | undefined,\n      inputSchema: (meta.inputSchema ?? content.inputSchema ?? firstAction?.inputSchema) as\n        | JSONSchema\n        | undefined,\n    };\n  } catch {\n    return {};\n  }\n}\n\n/**\n * Create exec command factory\n *\n * This command has special handling:\n * 1. Factory function caches inputSchema\n * 2. Builder pre-parses argv to get action path\n * 3. Dynamically adds options from inputSchema\n */\nexport function createExecCommand(\n  options: CommandFactoryOptions,\n): CommandModule<unknown, ExecArgs> {\n  // Cache schema in closure for reuse between builder and handler\n  let cachedSchema: JSONSchema | undefined;\n  // Store the pre-parsed exec target path\n  let resolvedExecAction: string | undefined;\n\n  return {\n    command: \"exec <executable_path>\",\n    describe: \"Execute an action\",\n    builder: async (yargs) => {\n      // Pre-parse argv to get the action path (first positional after \"exec\")\n      const execIndex = options.argv.indexOf(\"exec\");\n      const actionArg = execIndex >= 0 ? options.argv[execIndex + 1] : undefined;\n\n      if (actionArg && typeof actionArg === \"string\" && !actionArg.startsWith(\"-\")) {\n        resolvedExecAction = actionArg;\n        // Fetch action metadata\n        const afs = await resolveAFS(options);\n        const actionMeta = await fetchActionMeta(afs, actionArg);\n        cachedSchema = actionMeta.inputSchema;\n\n        // Set custom usage with path and description\n        const description = actionMeta.description || \"Execute an action\";\n        yargs.usage(`afs exec ${actionArg}\\n\\n${description}`);\n\n        // Check if --args is provided - if so, don't require individual options\n        const hasArgsOption = options.argv.includes(\"--args\");\n\n        if (cachedSchema?.properties) {\n          // Add dynamic options from schema\n          for (const [name, propSchema] of Object.entries(cachedSchema.properties)) {\n            const prop = propSchema as JSONSchema;\n            let description = prop.description || \"\";\n\n            // For object-type properties with sub-properties, show them in the description\n            if (prop.type === \"object\" && prop.properties) {\n              const subKeys = Object.keys(prop.properties).join(\", \");\n              description += `${description ? \" \" : \"\"}(JSON object with: ${subKeys})`;\n            }\n\n            const optConfig: Options = {\n              type: schemaTypeToYargs(prop.type),\n              description: description || undefined,\n              group: \"Action Parameters:\",\n            };\n\n            if (prop.default !== undefined) {\n              optConfig.default = prop.default;\n            }\n\n            // Only require options when --args is not provided.\n            // Skip demandOption for fields with sensitive/env metadata — these\n            // can be resolved through credential collection (browser, env vars,\n            // credential store) rather than CLI args.\n            if (!hasArgsOption && cachedSchema.required?.includes(name)) {\n              const hasAlternateResolution =\n                (prop as Record<string, unknown>).sensitive === true ||\n                Array.isArray((prop as Record<string, unknown>).env);\n              if (!hasAlternateResolution) {\n                optConfig.demandOption = true;\n              }\n            }\n\n            yargs.option(name, optConfig);\n          }\n        }\n      }\n\n      return yargs\n        .positional(\"executable_path\", {\n          type: \"string\",\n          demandOption: true,\n          description: \"Action path to execute\",\n        })\n        .option(\"args\", {\n          type: \"string\",\n          description: 'JSON arguments: --args \\'{\"key\": \"value\"}\\'',\n        })\n        .strict(false);\n    },\n    handler: async (argv) => {\n      const afs = await resolveAFS(options);\n      // Use pre-parsed action path from builder\n      const execPath = resolvedExecAction ?? argv.executable_path;\n      // Use cached schema or fetch again\n      const schema = cachedSchema ?? (await fetchActionMeta(afs, execPath)).inputSchema;\n\n      // Strip positional \"executable_path\" from argv before parsing exec args\n      const argvForParsing: Record<string, unknown> = { ...argv };\n      delete argvForParsing.executable_path;\n      // yargs also creates a camelCase alias \"executablePath\" — remove it too\n      delete argvForParsing.executablePath;\n\n      // Parse exec arguments with schema\n      const execArgs = parseExecArgs(argvForParsing, schema);\n\n      const canonicalPath = cliPathToCanonical(execPath);\n      const result = await afs.exec(canonicalPath, execArgs, {});\n      options.onResult({\n        command: \"exec\",\n        result,\n        format: formatExecOutput,\n      });\n    },\n  };\n}\n"],"mappings":";;;;;;;;;;AAmCA,eAAe,gBACb,KACA,MAC6D;CAC7D,MAAM,gBAAgB,mBAAmB,KAAK;AAE9C,KAAI;EACF,MAAM,aAAa,MAAM,IAAI,KAAK,cAAc;EAChD,MAAM,OAAO,WAAW,MAAM,QAAQ,EAAE;EACxC,MAAM,UAAU,WAAW,MAAM,WAAW,EAAE;EAE9C,MAAM,cAAc,WAAW,MAAM,UAAU;AAE/C,SAAO;GACL,aAAc,KAAK,eACjB,QAAQ,eACR,aAAa,eACb,WAAW,MAAM;GACnB,aAAc,KAAK,eAAe,QAAQ,eAAe,aAAa;GAGvE;SACK;AACN,SAAO,EAAE;;;;;;;;;;;AAYb,SAAgB,kBACd,SACkC;CAElC,IAAI;CAEJ,IAAI;AAEJ,QAAO;EACL,SAAS;EACT,UAAU;EACV,SAAS,OAAO,UAAU;GAExB,MAAM,YAAY,QAAQ,KAAK,QAAQ,OAAO;GAC9C,MAAM,YAAY,aAAa,IAAI,QAAQ,KAAK,YAAY,KAAK;AAEjE,OAAI,aAAa,OAAO,cAAc,YAAY,CAAC,UAAU,WAAW,IAAI,EAAE;AAC5E,yBAAqB;IAGrB,MAAM,aAAa,MAAM,gBADb,MAAM,WAAW,QAAQ,EACS,UAAU;AACxD,mBAAe,WAAW;IAG1B,MAAM,cAAc,WAAW,eAAe;AAC9C,UAAM,MAAM,YAAY,UAAU,MAAM,cAAc;IAGtD,MAAM,gBAAgB,QAAQ,KAAK,SAAS,SAAS;AAErD,QAAI,cAAc,WAEhB,MAAK,MAAM,CAAC,MAAM,eAAe,OAAO,QAAQ,aAAa,WAAW,EAAE;KACxE,MAAM,OAAO;KACb,IAAIA,gBAAc,KAAK,eAAe;AAGtC,SAAI,KAAK,SAAS,YAAY,KAAK,YAAY;MAC7C,MAAM,UAAU,OAAO,KAAK,KAAK,WAAW,CAAC,KAAK,KAAK;AACvD,uBAAe,GAAGA,gBAAc,MAAM,GAAG,qBAAqB,QAAQ;;KAGxE,MAAM,YAAqB;MACzB,MAAM,kBAAkB,KAAK,KAAK;MAClC,aAAaA,iBAAe;MAC5B,OAAO;MACR;AAED,SAAI,KAAK,YAAY,OACnB,WAAU,UAAU,KAAK;AAO3B,SAAI,CAAC,iBAAiB,aAAa,UAAU,SAAS,KAAK,EAIzD;UAAI,EAFD,KAAiC,cAAc,QAChD,MAAM,QAAS,KAAiC,IAAI,EAEpD,WAAU,eAAe;;AAI7B,WAAM,OAAO,MAAM,UAAU;;;AAKnC,UAAO,MACJ,WAAW,mBAAmB;IAC7B,MAAM;IACN,cAAc;IACd,aAAa;IACd,CAAC,CACD,OAAO,QAAQ;IACd,MAAM;IACN,aAAa;IACd,CAAC,CACD,OAAO,MAAM;;EAElB,SAAS,OAAO,SAAS;GACvB,MAAM,MAAM,MAAM,WAAW,QAAQ;GAErC,MAAM,WAAW,sBAAsB,KAAK;GAE5C,MAAM,SAAS,iBAAiB,MAAM,gBAAgB,KAAK,SAAS,EAAE;GAGtE,MAAM,iBAA0C,EAAE,GAAG,MAAM;AAC3D,UAAO,eAAe;AAEtB,UAAO,eAAe;GAGtB,MAAM,WAAW,cAAc,gBAAgB,OAAO;GAEtD,MAAM,gBAAgB,mBAAmB,SAAS;GAClD,MAAM,SAAS,MAAM,IAAI,KAAK,eAAe,UAAU,EAAE,CAAC;AAC1D,WAAQ,SAAS;IACf,SAAS;IACT;IACA,QAAQ;IACT,CAAC;;EAEL"}