@aigne/afs-cli 1.11.0-beta.11 → 1.11.0-beta.13

package/dist/core/commands/vault.mjs

@@ -0,0 +1,289 @@
+import { formatVaultDeleteOutput, formatVaultGetOutput, formatVaultInitOutput, formatVaultListOutput, formatVaultSetOutput } from "../formatters/vault.mjs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+//#region src/core/commands/vault.ts
+/**
+* vault Command - Core Implementation
+*
+* Vault management commands for encrypted secret storage.
+* Subcommands: init, get, set, list, delete.
+*/
+/** Default vault file location */
+const DEFAULT_VAULT_DIR = ".afs-config";
+const DEFAULT_VAULT_FILE = "vault.enc";
+function defaultVaultPath() {
+	return join(homedir(), DEFAULT_VAULT_DIR, DEFAULT_VAULT_FILE);
+}
+/**
+* Resolve master key using the vault's key resolution chain:
+* OS keychain → AFS_VAULT_KEY env var → passphrase prompt.
+*/
+async function loadMasterKey() {
+	const { resolveMasterKey } = await import("../../providers/vault/dist/index.mjs");
+	return resolveMasterKey();
+}
+/**
+* Create vault command factory (with subcommands)
+*/
+function createVaultCommand(options) {
+	return {
+		command: "vault",
+		describe: "Encrypted secret storage",
+		builder: (yargs) => yargs.command(createVaultInitSubcommand(options)).command(createVaultGetSubcommand(options)).command(createVaultSetSubcommand(options)).command(createVaultListSubcommand(options)).command(createVaultDeleteSubcommand(options)).demandCommand(1, "Please specify a subcommand").alias("help", "h"),
+		handler: () => {}
+	};
+}
+function createVaultInitSubcommand(options) {
+	return {
+		command: "init",
+		describe: "Initialize a new encrypted vault",
+		builder: {
+			path: {
+				type: "string",
+				description: "Path for vault file",
+				default: defaultVaultPath()
+			},
+			migrate: {
+				type: "boolean",
+				description: "Migrate existing credentials.toml into vault",
+				default: true
+			}
+		},
+		handler: async (argv) => {
+			const vaultPath = argv.path ?? defaultVaultPath();
+			const { generateMasterKey, writeEncryptedVault, vaultFileExists } = await import("../../providers/vault/dist/index.mjs");
+			if (await vaultFileExists(vaultPath)) throw new Error(`Vault already exists at ${vaultPath}. Delete it first to re-initialize.`);
+			const masterKey = generateMasterKey();
+			await writeEncryptedVault(vaultPath, { secrets: {} }, masterKey);
+			const { storeKeychain } = await import("../../providers/vault/dist/index.mjs");
+			const stored = await storeKeychain(masterKey);
+			let migrated = 0;
+			if (argv.migrate !== false) migrated = await migrateFromToml(vaultPath, masterKey);
+			const hexKey = masterKey.toString("hex");
+			options.onResult({
+				command: "vault init",
+				result: {
+					success: true,
+					vaultPath,
+					migrated,
+					keychainStored: stored
+				},
+				format: (result, view) => {
+					const base = formatVaultInitOutput(result, view);
+					if (view === "json") return base;
+					const lines = [base];
+					if (stored) lines.push("\nMaster key stored in OS keychain.");
+					else lines.push(`\nMaster key (save this securely — it cannot be recovered):\n${hexKey}`, `\nSet it as: export AFS_VAULT_KEY=${hexKey}`);
+					return lines.join("");
+				}
+			});
+		}
+	};
+}
+/**
+* Migrate credentials.toml entries into the vault.
+* Returns count of migrated credential groups.
+*/
+async function migrateFromToml(vaultPath, masterKey) {
+	const { readFile } = await import("node:fs/promises");
+	const { parse } = await import("smol-toml");
+	const { AFSVault } = await import("../../providers/vault/dist/index.mjs");
+	const tomlPath = join(homedir(), DEFAULT_VAULT_DIR, "credentials.toml");
+	let content;
+	try {
+		content = await readFile(tomlPath, "utf-8");
+	} catch {
+		return 0;
+	}
+	let data;
+	try {
+		data = parse(content);
+	} catch {
+		return 0;
+	}
+	const vault = new AFSVault({
+		vaultPath,
+		masterKey,
+		accessMode: "readwrite"
+	});
+	let count = 0;
+	for (const [group, values] of Object.entries(data)) {
+		if (typeof values !== "object" || values === null || Array.isArray(values)) continue;
+		const safeGroup = group.replace(/^[a-z0-9]+:\/\//, "").replace(/[^a-zA-Z0-9._-]/g, "-").replace(/-+/g, "-").replace(/^-|-$/g, "");
+		if (!safeGroup) continue;
+		for (const [key, val] of Object.entries(values)) if (typeof val === "string") await vault.setSecret(safeGroup, key, val);
+		count++;
+	}
+	return count;
+}
+function createVaultGetSubcommand(options) {
+	return {
+		command: "get <group> <name>",
+		describe: "Read a secret value",
+		builder: {
+			group: {
+				type: "string",
+				demandOption: true,
+				description: "Secret group (e.g., aws, github)"
+			},
+			name: {
+				type: "string",
+				demandOption: true,
+				description: "Secret name (e.g., token, access-key-id)"
+			},
+			"vault-path": {
+				type: "string",
+				description: "Path to vault file"
+			}
+		},
+		handler: async (argv) => {
+			const { AFSVault } = await import("../../providers/vault/dist/index.mjs");
+			const value = await new AFSVault({
+				vaultPath: argv["vault-path"] ?? defaultVaultPath(),
+				masterKey: await loadMasterKey(),
+				accessMode: "readonly"
+			}).getSecret(argv.group, argv.name);
+			if (value === void 0) throw new Error(`Secret not found: ${argv.group}/${argv.name}`);
+			options.onResult({
+				command: "vault get",
+				result: {
+					group: argv.group,
+					name: argv.name,
+					value
+				},
+				format: formatVaultGetOutput
+			});
+		}
+	};
+}
+function createVaultSetSubcommand(options) {
+	return {
+		command: "set <group> <name> <value>",
+		describe: "Store a secret",
+		builder: {
+			group: {
+				type: "string",
+				demandOption: true,
+				description: "Secret group (e.g., aws, github)"
+			},
+			name: {
+				type: "string",
+				demandOption: true,
+				description: "Secret name (e.g., token, access-key-id)"
+			},
+			value: {
+				type: "string",
+				demandOption: true,
+				description: "Secret value"
+			},
+			"vault-path": {
+				type: "string",
+				description: "Path to vault file"
+			}
+		},
+		handler: async (argv) => {
+			const { AFSVault } = await import("../../providers/vault/dist/index.mjs");
+			await new AFSVault({
+				vaultPath: argv["vault-path"] ?? defaultVaultPath(),
+				masterKey: await loadMasterKey(),
+				accessMode: "readwrite"
+			}).setSecret(argv.group, argv.name, argv.value);
+			options.onResult({
+				command: "vault set",
+				result: {
+					group: argv.group,
+					name: argv.name
+				},
+				format: formatVaultSetOutput
+			});
+		}
+	};
+}
+function createVaultListSubcommand(options) {
+	return {
+		command: ["list [group]", "ls [group]"],
+		describe: "List secrets",
+		builder: {
+			group: {
+				type: "string",
+				description: "Secret group to list (omit for all groups)"
+			},
+			"vault-path": {
+				type: "string",
+				description: "Path to vault file"
+			}
+		},
+		handler: async (argv) => {
+			const { AFSVault } = await import("../../providers/vault/dist/index.mjs");
+			const secrets = await new AFSVault({
+				vaultPath: argv["vault-path"] ?? defaultVaultPath(),
+				masterKey: await loadMasterKey(),
+				accessMode: "readonly"
+			}).listSecrets(argv.group);
+			options.onResult({
+				command: "vault list",
+				result: {
+					group: argv.group,
+					secrets
+				},
+				format: formatVaultListOutput
+			});
+		}
+	};
+}
+function createVaultDeleteSubcommand(options) {
+	return {
+		command: ["delete <group> [name]", "rm <group> [name]"],
+		describe: "Delete a secret or group",
+		builder: {
+			group: {
+				type: "string",
+				demandOption: true,
+				description: "Secret group"
+			},
+			name: {
+				type: "string",
+				description: "Secret name (omit to delete entire group)"
+			},
+			"vault-path": {
+				type: "string",
+				description: "Path to vault file"
+			}
+		},
+		handler: async (argv) => {
+			const { AFSVault } = await import("../../providers/vault/dist/index.mjs");
+			const vault = new AFSVault({
+				vaultPath: argv["vault-path"] ?? defaultVaultPath(),
+				masterKey: await loadMasterKey(),
+				accessMode: "readwrite"
+			});
+			let deleted;
+			if (argv.name) deleted = await vault.deleteSecret(argv.group, argv.name);
+			else {
+				const secrets = await vault.listSecrets(argv.group);
+				if (secrets.length === 0) deleted = false;
+				else {
+					for (const secretPath of secrets) {
+						const secretName = secretPath.split("/").pop();
+						await vault.deleteSecret(argv.group, secretName);
+					}
+					deleted = true;
+				}
+			}
+			options.onResult({
+				command: "vault delete",
+				result: {
+					group: argv.group,
+					name: argv.name,
+					deleted
+				},
+				format: formatVaultDeleteOutput
+			});
+		}
+	};
+}
+
+//#endregion
+export { createVaultCommand };
+//# sourceMappingURL=vault.mjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"vault.mjs","names":[],"sources":["../../../src/core/commands/vault.ts"],"sourcesContent":["/**\n * vault Command - Core Implementation\n *\n * Vault management commands for encrypted secret storage.\n * Subcommands: init, get, set, list, delete.\n */\n\nimport { homedir } from \"node:os\";\nimport { join } from \"node:path\";\nimport type { Argv, CommandModule } from \"yargs\";\nimport {\n  formatVaultDeleteOutput,\n  formatVaultGetOutput,\n  formatVaultInitOutput,\n  formatVaultListOutput,\n  formatVaultSetOutput,\n} from \"../formatters/vault.js\";\nimport type { CommandFactoryOptions } from \"./types.js\";\n\n/** Default vault file location */\nconst DEFAULT_VAULT_DIR = \".afs-config\";\nconst DEFAULT_VAULT_FILE = \"vault.enc\";\n\nfunction defaultVaultPath(): string {\n  return join(homedir(), DEFAULT_VAULT_DIR, DEFAULT_VAULT_FILE);\n}\n\n/**\n * Resolve master key using the vault's key resolution chain:\n * OS keychain → AFS_VAULT_KEY env var → passphrase prompt.\n */\nasync function loadMasterKey(): Promise<Buffer> {\n  const { resolveMasterKey } = await import(\"@aigne/afs-vault\");\n  return resolveMasterKey();\n}\n\n/**\n * Create vault command factory (with subcommands)\n */\nexport function createVaultCommand(options: CommandFactoryOptions): CommandModule {\n  return {\n    command: \"vault\",\n    describe: \"Encrypted secret storage\",\n    builder: (yargs: Argv) =>\n      yargs\n        .command(createVaultInitSubcommand(options))\n        .command(createVaultGetSubcommand(options))\n        .command(createVaultSetSubcommand(options))\n        .command(createVaultListSubcommand(options))\n        .command(createVaultDeleteSubcommand(options))\n        .demandCommand(1, \"Please specify a subcommand\")\n        .alias(\"help\", \"h\"),\n    handler: () => {},\n  };\n}\n\n// ── init ──────────────────────────────────────────────────────────────\n\ninterface VaultInitArgs {\n  path?: string;\n  migrate?: boolean;\n}\n\nfunction createVaultInitSubcommand(\n  options: CommandFactoryOptions,\n): CommandModule<unknown, VaultInitArgs> {\n  return {\n    command: \"init\",\n    describe: \"Initialize a new encrypted vault\",\n    builder: {\n      path: {\n        type: \"string\",\n        description: \"Path for vault file\",\n        default: defaultVaultPath(),\n      },\n      migrate: {\n        type: \"boolean\",\n        description: \"Migrate existing credentials.toml into vault\",\n        default: true,\n      },\n    },\n    handler: async (argv) => {\n      const vaultPath = argv.path ?? defaultVaultPath();\n\n      const { generateMasterKey, writeEncryptedVault, vaultFileExists } = await import(\n        \"@aigne/afs-vault\"\n      );\n\n      if (await vaultFileExists(vaultPath)) {\n        throw new Error(`Vault already exists at ${vaultPath}. Delete it first to re-initialize.`);\n      }\n\n      const masterKey = generateMasterKey();\n\n      // Create empty vault\n      await writeEncryptedVault(vaultPath, { secrets: {} }, masterKey);\n\n      // Try to store in OS keychain\n      const { storeKeychain } = await import(\"@aigne/afs-vault\");\n      const stored = await storeKeychain(masterKey);\n\n      let migrated = 0;\n\n      // Migrate from credentials.toml if requested\n      if (argv.migrate !== false) {\n        migrated = await migrateFromToml(vaultPath, masterKey);\n      }\n\n      const hexKey = masterKey.toString(\"hex\");\n\n      options.onResult({\n        command: \"vault init\",\n        result: { success: true, vaultPath, migrated, keychainStored: stored },\n        format: (result, view) => {\n          const base = formatVaultInitOutput(result, view);\n          if (view === \"json\") return base;\n          const lines = [base];\n          if (stored) {\n            lines.push(\"\\nMaster key stored in OS keychain.\");\n          } else {\n            lines.push(\n              `\\nMaster key (save this securely — it cannot be recovered):\\n${hexKey}`,\n              `\\nSet it as: export AFS_VAULT_KEY=${hexKey}`,\n            );\n          }\n          return lines.join(\"\");\n        },\n      });\n    },\n  };\n}\n\n/**\n * Migrate credentials.toml entries into the vault.\n * Returns count of migrated credential groups.\n */\nasync function migrateFromToml(vaultPath: string, masterKey: Buffer): Promise<number> {\n  const { readFile } = await import(\"node:fs/promises\");\n  const { parse } = await import(\"smol-toml\");\n  const { AFSVault } = await import(\"@aigne/afs-vault\");\n\n  const tomlPath = join(homedir(), DEFAULT_VAULT_DIR, \"credentials.toml\");\n\n  let content: string;\n  try {\n    content = await readFile(tomlPath, \"utf-8\");\n  } catch {\n    return 0; // No credentials.toml — nothing to migrate\n  }\n\n  let data: Record<string, unknown>;\n  try {\n    data = parse(content) as Record<string, unknown>;\n  } catch {\n    return 0; // Corrupted file — skip migration\n  }\n\n  const vault = new AFSVault({ vaultPath, masterKey, accessMode: \"readwrite\" });\n  let count = 0;\n\n  for (const [group, values] of Object.entries(data)) {\n    if (typeof values !== \"object\" || values === null || Array.isArray(values)) continue;\n    // Sanitize group name for vault\n    const safeGroup = group\n      .replace(/^[a-z0-9]+:\\/\\//, \"\")\n      .replace(/[^a-zA-Z0-9._-]/g, \"-\")\n      .replace(/-+/g, \"-\")\n      .replace(/^-|-$/g, \"\");\n    if (!safeGroup) continue;\n\n    for (const [key, val] of Object.entries(values as Record<string, unknown>)) {\n      if (typeof val === \"string\") {\n        await vault.setSecret(safeGroup, key, val);\n      }\n    }\n    count++;\n  }\n\n  return count;\n}\n\n// ── get ──────────────────────────────────────────────────────────────\n\ninterface VaultGetArgs {\n  group: string;\n  name: string;\n  \"vault-path\"?: string;\n}\n\nfunction createVaultGetSubcommand(\n  options: CommandFactoryOptions,\n): CommandModule<unknown, VaultGetArgs> {\n  return {\n    command: \"get <group> <name>\",\n    describe: \"Read a secret value\",\n    builder: {\n      group: {\n        type: \"string\",\n        demandOption: true,\n        description: \"Secret group (e.g., aws, github)\",\n      },\n      name: {\n        type: \"string\",\n        demandOption: true,\n        description: \"Secret name (e.g., token, access-key-id)\",\n      },\n      \"vault-path\": {\n        type: \"string\",\n        description: \"Path to vault file\",\n      },\n    },\n    handler: async (argv) => {\n      const { AFSVault } = await import(\"@aigne/afs-vault\");\n      const vaultPath = argv[\"vault-path\"] ?? defaultVaultPath();\n      const masterKey = await loadMasterKey();\n      const vault = new AFSVault({ vaultPath, masterKey, accessMode: \"readonly\" });\n\n      const value = await vault.getSecret(argv.group, argv.name);\n      if (value === undefined) {\n        throw new Error(`Secret not found: ${argv.group}/${argv.name}`);\n      }\n\n      options.onResult({\n        command: \"vault get\",\n        result: { group: argv.group, name: argv.name, value },\n        format: formatVaultGetOutput,\n      });\n    },\n  };\n}\n\n// ── set ──────────────────────────────────────────────────────────────\n\ninterface VaultSetArgs {\n  group: string;\n  name: string;\n  value: string;\n  \"vault-path\"?: string;\n}\n\nfunction createVaultSetSubcommand(\n  options: CommandFactoryOptions,\n): CommandModule<unknown, VaultSetArgs> {\n  return {\n    command: \"set <group> <name> <value>\",\n    describe: \"Store a secret\",\n    builder: {\n      group: {\n        type: \"string\",\n        demandOption: true,\n        description: \"Secret group (e.g., aws, github)\",\n      },\n      name: {\n        type: \"string\",\n        demandOption: true,\n        description: \"Secret name (e.g., token, access-key-id)\",\n      },\n      value: {\n        type: \"string\",\n        demandOption: true,\n        description: \"Secret value\",\n      },\n      \"vault-path\": {\n        type: \"string\",\n        description: \"Path to vault file\",\n      },\n    },\n    handler: async (argv) => {\n      const { AFSVault } = await import(\"@aigne/afs-vault\");\n      const vaultPath = argv[\"vault-path\"] ?? defaultVaultPath();\n      const masterKey = await loadMasterKey();\n      const vault = new AFSVault({ vaultPath, masterKey, accessMode: \"readwrite\" });\n\n      await vault.setSecret(argv.group, argv.name, argv.value);\n\n      options.onResult({\n        command: \"vault set\",\n        result: { group: argv.group, name: argv.name },\n        format: formatVaultSetOutput,\n      });\n    },\n  };\n}\n\n// ── list ─────────────────────────────────────────────────────────────\n\ninterface VaultListArgs {\n  group?: string;\n  \"vault-path\"?: string;\n}\n\nfunction createVaultListSubcommand(\n  options: CommandFactoryOptions,\n): CommandModule<unknown, VaultListArgs> {\n  return {\n    command: [\"list [group]\", \"ls [group]\"],\n    describe: \"List secrets\",\n    builder: {\n      group: {\n        type: \"string\",\n        description: \"Secret group to list (omit for all groups)\",\n      },\n      \"vault-path\": {\n        type: \"string\",\n        description: \"Path to vault file\",\n      },\n    },\n    handler: async (argv) => {\n      const { AFSVault } = await import(\"@aigne/afs-vault\");\n      const vaultPath = argv[\"vault-path\"] ?? defaultVaultPath();\n      const masterKey = await loadMasterKey();\n      const vault = new AFSVault({ vaultPath, masterKey, accessMode: \"readonly\" });\n\n      const secrets = await vault.listSecrets(argv.group);\n\n      options.onResult({\n        command: \"vault list\",\n        result: { group: argv.group, secrets },\n        format: formatVaultListOutput,\n      });\n    },\n  };\n}\n\n// ── delete ───────────────────────────────────────────────────────────\n\ninterface VaultDeleteArgs {\n  group: string;\n  name?: string;\n  \"vault-path\"?: string;\n}\n\nfunction createVaultDeleteSubcommand(\n  options: CommandFactoryOptions,\n): CommandModule<unknown, VaultDeleteArgs> {\n  return {\n    command: [\"delete <group> [name]\", \"rm <group> [name]\"],\n    describe: \"Delete a secret or group\",\n    builder: {\n      group: {\n        type: \"string\",\n        demandOption: true,\n        description: \"Secret group\",\n      },\n      name: {\n        type: \"string\",\n        description: \"Secret name (omit to delete entire group)\",\n      },\n      \"vault-path\": {\n        type: \"string\",\n        description: \"Path to vault file\",\n      },\n    },\n    handler: async (argv) => {\n      const { AFSVault } = await import(\"@aigne/afs-vault\");\n      const vaultPath = argv[\"vault-path\"] ?? defaultVaultPath();\n      const masterKey = await loadMasterKey();\n      const vault = new AFSVault({ vaultPath, masterKey, accessMode: \"readwrite\" });\n\n      let deleted: boolean;\n      if (argv.name) {\n        deleted = await vault.deleteSecret(argv.group, argv.name);\n      } else {\n        // Delete entire group by listing all secrets and deleting each\n        const secrets = await vault.listSecrets(argv.group);\n        if (secrets.length === 0) {\n          deleted = false;\n        } else {\n          for (const secretPath of secrets) {\n            const secretName = secretPath.split(\"/\").pop()!;\n            await vault.deleteSecret(argv.group, secretName);\n          }\n          deleted = true;\n        }\n      }\n\n      options.onResult({\n        command: \"vault delete\",\n        result: { group: argv.group, name: argv.name, deleted },\n        format: formatVaultDeleteOutput,\n      });\n    },\n  };\n}\n"],"mappings":"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"}

package/dist/core/commands/write.cjs

@@ -36,10 +36,22 @@ function createWriteCommand(options) {
 				type: "string",
 				description: "Content to write"
 			},
-			append: {
-				type: "boolean",
-				description: "Append to file instead of overwriting",
-				default: false
+			mode: {
+				type: "string",
+				choices: [
+					"replace",
+					"append",
+					"prepend",
+					"patch",
+					"create",
+					"update"
+				],
+				description: "Write mode",
+				default: "replace"
+			},
+			patch: {
+				type: "string",
+				description: "JSON array of patch operations (for mode=patch)"
 			},
 			meta: {
 				type: "string",
@@ -50,13 +62,14 @@ function createWriteCommand(options) {
 		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)");
+			if (argv.content === void 0 && !metadata && argv.mode !== "patch") 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 });
+			if (argv.patch) writeData.patches = JSON.parse(argv.patch);
+			const result = await afs.write(canonicalPath, writeData, { mode: argv.mode });
 			options.onResult({
 				command: "write",
 				result,

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

@@ -8,7 +8,8 @@ import { CommandModule } from "yargs";
 interface WriteArgs {
   path: string;
   content?: string;
-  append: boolean;
+  mode: "replace" | "append" | "prepend" | "patch" | "create" | "update";
+  patch?: string;
   meta?: string[];
 }
 /**

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

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

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

@@ -8,7 +8,8 @@ import { CommandModule } from "yargs";
 interface WriteArgs {
   path: string;
   content?: string;
-  append: boolean;
+  mode: "replace" | "append" | "prepend" | "patch" | "create" | "update";
+  patch?: string;
   meta?: string[];
 }
 /**

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

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

package/dist/core/commands/write.mjs

@@ -36,10 +36,22 @@ function createWriteCommand(options) {
 				type: "string",
 				description: "Content to write"
 			},
-			append: {
-				type: "boolean",
-				description: "Append to file instead of overwriting",
-				default: false
+			mode: {
+				type: "string",
+				choices: [
+					"replace",
+					"append",
+					"prepend",
+					"patch",
+					"create",
+					"update"
+				],
+				description: "Write mode",
+				default: "replace"
+			},
+			patch: {
+				type: "string",
+				description: "JSON array of patch operations (for mode=patch)"
 			},
 			meta: {
 				type: "string",
@@ -50,13 +62,14 @@ function createWriteCommand(options) {
 		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)");
+			if (argv.content === void 0 && !metadata && argv.mode !== "patch") 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 });
+			if (argv.patch) writeData.patches = JSON.parse(argv.patch);
+			const result = await afs.write(canonicalPath, writeData, { mode: argv.mode });
 			options.onResult({
 				command: "write",
 				result,

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

@@ -1 +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"}
+{"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  mode: \"replace\" | \"append\" | \"prepend\" | \"patch\" | \"create\" | \"update\";\n  patch?: string;\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      mode: {\n        type: \"string\",\n        choices: [\"replace\", \"append\", \"prepend\", \"patch\", \"create\", \"update\"] as const,\n        description: \"Write mode\",\n        default: \"replace\" as const,\n      },\n      patch: {\n        type: \"string\",\n        description: \"JSON array of patch operations (for mode=patch)\",\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 or using patch mode\n      if (argv.content === undefined && !metadata && argv.mode !== \"patch\") {\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      if (argv.patch) {\n        writeData.patches = JSON.parse(argv.patch);\n      }\n\n      const result = await afs.write(canonicalPath, writeData, { mode: argv.mode });\n      options.onResult({\n        command: \"write\",\n        result,\n        format: (res, view) => formatWriteOutput(res, view, { fields }),\n      });\n    },\n  };\n}\n"],"mappings":";;;;;;;;;AA2BA,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,MAAM;IACJ,MAAM;IACN,SAAS;KAAC;KAAW;KAAU;KAAW;KAAS;KAAU;KAAS;IACtE,aAAa;IACb,SAAS;IACV;GACD,OAAO;IACL,MAAM;IACN,aAAa;IACd;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,YAAY,KAAK,SAAS,QAC3D,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;AAEnB,OAAI,KAAK,MACP,WAAU,UAAU,KAAK,MAAM,KAAK,MAAM;GAG5C,MAAM,SAAS,MAAM,IAAI,MAAM,eAAe,WAAW,EAAE,MAAM,KAAK,MAAM,CAAC;AAC7E,WAAQ,SAAS;IACf,SAAS;IACT;IACA,SAAS,KAAK,SAAS,kBAAkB,KAAK,MAAM,EAAE,QAAQ,CAAC;IAChE,CAAC;;EAEL"}

package/dist/core/executor/index.cjs

@@ -4,6 +4,28 @@ let yargs = require("yargs");
 yargs = require_rolldown_runtime.__toESM(yargs);
 
 //#region src/core/executor/index.ts
+/** Known command names and aliases for suggestion matching. */
+const KNOWN_COMMANDS = [
+	"ls",
+	"list",
+	"read",
+	"cat",
+	"write",
+	"delete",
+	"rm",
+	"stat",
+	"exec",
+	"explain",
+	"search",
+	"grep",
+	"find",
+	"mount",
+	"serve",
+	"explore",
+	"service",
+	"connect",
+	"vault"
+];
 /**
 * AFS Command Executor
 *
@@ -43,6 +65,8 @@ var AFSCommandExecutor = class {
 				commandResult = result;
 			}
 		};
+		let failMsg;
+		let failErr;
 		let parser = (0, yargs.default)(normalizedArgs).scriptName("afs").usage("$0 <command> [options]").option("json", {
 			type: "boolean",
 			description: "Output in JSON format",
@@ -66,34 +90,42 @@ var AFSCommandExecutor = class {
 			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);
+		}).help(true).alias("h", "help").version(this.options.version || "unknown").alias("v", "version").demandCommand().strictCommands().exitProcess(false).fail((msg, err) => {
+			failErr = err || new Error(msg || "Unknown error");
+			failMsg = msg;
+		});
 		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;
+			await parser.parseAsync(normalizedArgs, {}, (_e, _, o) => {
 				output = o;
 			});
-			if (error) return {
-				success: false,
-				command: normalizedArgs[0] || "unknown",
-				result: void 0,
-				formatted: output,
-				error: { message: error.message }
-			};
-			if (parsed.help) return {
+			if (failErr) {
+				const formatted$1 = await this.formatFailure(normalizedArgs, failMsg, parser);
+				return {
+					success: false,
+					command: normalizedArgs[0] || "unknown",
+					result: void 0,
+					formatted: formatted$1,
+					error: { message: failMsg || failErr.message }
+				};
+			}
+			if (output) 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;
+			if (!commandResult) {
+				const formatted$1 = await this.formatFailure(normalizedArgs, void 0, parser);
+				return {
+					success: false,
+					command: normalizedArgs[0] || "unknown",
+					result: void 0,
+					formatted: formatted$1,
+					error: { message: `Unknown command: "${normalizedArgs[0] || ""}"` }
+				};
+			}
+			const view = outputOptions.json ? "json" : outputOptions.yaml ? "yaml" : commandResult.viewOverride ?? outputOptions.view;
 			const formatted = commandResult.format(commandResult.result, view, { path: this.extractPath(normalizedArgs) });
 			if (commandResult.error) return {
 				success: false,
@@ -120,6 +152,31 @@ var AFSCommandExecutor = class {
 		}
 	}
 	/**
+	* Format a friendly error message for unknown/invalid commands.
+	*/
+	async formatFailure(args, failMsg, parser) {
+		const cmd = args[0] || "";
+		const lines = [];
+		if (cmd && failMsg?.includes("Unknown command")) {
+			lines.push(`Unknown command: "${cmd}"`);
+			const suggestions = suggestCommands(cmd);
+			if (suggestions.length > 0) {
+				lines.push("");
+				lines.push(`Did you mean?`);
+				for (const s of suggestions) lines.push(`  afs ${s}`);
+			}
+		} else if (failMsg) lines.push(failMsg);
+		else lines.push(`Unknown command: "${cmd}"`);
+		lines.push("");
+		try {
+			const helpText = await parser.getHelp();
+			lines.push(helpText);
+		} catch {
+			lines.push("Run \"afs --help\" to see available commands.");
+		}
+		return lines.join("\n");
+	}
+	/**
 	* Normalize argv to an array of strings
 	*/
 	normalizeArgv(argv) {
@@ -191,6 +248,25 @@ var AFSCommandExecutor = class {
 		}
 	}
 };
+/** Levenshtein distance between two strings. */
+function levenshtein(a, b) {
+	const m = a.length;
+	const n = b.length;
+	const dp = Array.from({ length: m + 1 }, () => Array(n + 1).fill(0));
+	for (let i = 0; i <= m; i++) dp[i][0] = i;
+	for (let j = 0; j <= n; j++) dp[0][j] = j;
+	for (let i = 1; i <= m; i++) for (let j = 1; j <= n; j++) dp[i][j] = a[i - 1] === b[j - 1] ? dp[i - 1][j - 1] : 1 + Math.min(dp[i - 1][j], dp[i][j - 1], dp[i - 1][j - 1]);
+	return dp[m][n];
+}
+/** Suggest known commands similar to the given input. */
+function suggestCommands(input) {
+	const lower = input.toLowerCase();
+	return KNOWN_COMMANDS.map((cmd) => ({
+		cmd,
+		dist: levenshtein(lower, cmd),
+		maxLen: Math.max(lower.length, cmd.length)
+	})).filter((x) => x.dist > 0 && x.dist < x.maxLen * .5).sort((a, b) => a.dist - b.dist).map((x) => x.cmd).slice(0, 3);
+}
 
 //#endregion
 exports.AFSCommandExecutor = AFSCommandExecutor;

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

@@ -55,6 +55,10 @@ declare class AFSCommandExecutor {
    * @returns Execution result with formatted output
    */
   execute(argv: string | string[]): Promise<ExecuteResult>;
+  /**
+   * Format a friendly error message for unknown/invalid commands.
+   */
+  private formatFailure;
   /**
    * Normalize argv to an array of strings
    */

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

@@ -1 +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"}
+{"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;EA6DiC;EA3DhD,GAAA;EA2D+C;EAzD/C,GAAA;EAyCQ;EAvCR,OAAA;AAAA;;;;;;;;;;;;;cAsCW,kBAAA;EAAA,QACH,GAAA;EAAA,QACA,OAAA;cAEI,GAAA,GAAM,GAAA,EAAK,OAAA,GAAU,eAAA;;;;;;;;;EAa3B,OAAA,CAAQ,IAAA,sBAA0B,OAAA,CAAQ,aAAA;;;;UAuJlC,aAAA;;;;UAwCN,aAAA;;;;UAoCA,QAAA;;;;UA2CA,oBAAA;;;;UA+BA,WAAA;AAAA"}

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

@@ -55,6 +55,10 @@ declare class AFSCommandExecutor {
    * @returns Execution result with formatted output
    */
   execute(argv: string | string[]): Promise<ExecuteResult>;
+  /**
+   * Format a friendly error message for unknown/invalid commands.
+   */
+  private formatFailure;
   /**
    * Normalize argv to an array of strings
    */

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.mts","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"}
+{"version":3,"file":"index.d.mts","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;EA6DiC;EA3DhD,GAAA;EA2D+C;EAzD/C,GAAA;EAyCQ;EAvCR,OAAA;AAAA;;;;;;;;;;;;;cAsCW,kBAAA;EAAA,QACH,GAAA;EAAA,QACA,OAAA;cAEI,GAAA,GAAM,GAAA,EAAK,OAAA,GAAU,eAAA;;;;;;;;;EAa3B,OAAA,CAAQ,IAAA,sBAA0B,OAAA,CAAQ,aAAA;;;;UAuJlC,aAAA;;;;UAwCN,aAAA;;;;UAoCA,QAAA;;;;UA2CA,oBAAA;;;;UA+BA,WAAA;AAAA"}