@aigne/afs-cli 1.11.0-beta.3 → 1.11.0-beta.4

package/README.md

@@ -1,29 +1,125 @@
 # @aigne/afs-cli
 
-AFS 命令行工具
+AFS 命令行工具 - AFS-UI 的文本投影 (reference implementation)
+
+## 安装
+
+```bash
+npm install -g @aigne/afs-cli
+# 或
+pnpm add -g @aigne/afs-cli
+```
+
+## 快速开始
+
+```bash
+# 配置挂载点
+afs mount add /src fs:///path/to/project/src
+afs mount add /docs fs:///path/to/docs
+
+# 列出目录
+afs list /src
+
+# 读取文件
+afs read /src/index.ts
+
+# 搜索内容
+afs search /src "TODO"
+```
+
+## 配置文件
+
+AFS CLI 使用 `.afs-config/config.toml` 配置挂载点和服务器设置。
+
+### 配置文件位置
+
+```
+~/.afs-config/config.toml          # 用户级 (最低优先级)
+<project>/.afs-config/config.toml  # 项目级
+<subdir>/.afs-config/config.toml   # 子目录级 (最高优先级)
+```
+
+### 配置示例
+
+```toml
+# 本地文件系统
+[[mounts]]
+path = "/src"
+uri = "fs:///Users/dev/project/src"
+description = "项目源码"
+
+# Git 仓库
+[[mounts]]
+path = "/upstream"
+uri = "git:///path/to/repo?branch=main"
+access_mode = "readonly"
+
+# SQLite 数据库
+[[mounts]]
+path = "/db"
+uri = "sqlite:///path/to/app.db"
+
+# 远程 AFS 服务器
+[[mounts]]
+path = "/remote"
+uri = "https://afs.example.com/afs"
+
+# HTTP 服务器配置
+[serve]
+host = "localhost"
+port = 3000
+path = "/afs"
+readonly = false
+cors = false
+max_body_size = 10485760  # 10MB
+```
 
 ## 命令
 
+### 文件操作
+
 | 命令 | 功能 |
 |------|------|
 | `afs list [path]` (别名: `ls`) | 列出目录内容 |
 | `afs read <path>` | 读取文件内容 |
 | `afs write <path> [--content]` | 写入文件 (--content 或 stdin) |
-| `afs stat <path>` | 获取文件/目录信息 |
+| `afs stat <path>` | 获取文件/目录元信息 |
+| `afs search <path> <query>` | 搜索文件内容 |
 | `afs exec <path> <action>` | 执行操作 |
+
+### 挂载管理
+
+| 命令 | 功能 |
+|------|------|
 | `afs mount list` (别名: `ls`) | 列出挂载配置 |
 | `afs mount add <path> <uri>` | 添加挂载 |
 | `afs mount remove <path>` (别名: `rm`) | 移除挂载 |
 | `afs mount validate` | 验证挂载配置 |
-| `afs explain [topic]` | 解释概念 (mount, uri, /path) |
-| `afs serve` | 启动 HTTP 服务器暴露 AFS 提供者 |
 
-## HTTP 服务器和远程挂载
+### 其他命令
+
+| 命令 | 功能 |
+|------|------|
+| `afs explain [topic]` | 解释概念 (命令或路径) |
+| `afs serve` | 启动 HTTP 服务器 |
+
+## 支持的 URI 方案
 
-### 启动 AFS HTTP 服务器
+| 方案 | 示例 | 说明 |
+|------|------|------|
+| `fs://` | `fs:///path/to/dir` | 本地文件系统 |
+| `git://` | `git:///path/to/repo?branch=main` | Git 仓库 |
+| `sqlite://` | `sqlite:///path/to/db.sqlite` | SQLite 数据库 |
+| `json://` | `json:///path/to/config.json` | JSON/YAML 文件 |
+| `http://` | `http://localhost:3000/afs` | HTTP 远程 AFS |
+| `https://` | `https://api.example.com/afs` | HTTPS 远程 AFS |
+
+## HTTP 服务器
+
+### 启动服务器
 
 ```bash
-# 启动服务器，暴露所有配置的挂载
+# 使用配置文件中的设置启动
 afs serve
 
 # 自定义主机和端口
@@ -39,7 +135,22 @@ afs serve --cors
 afs serve --path /api/afs
 ```
 
-### 挂载远程 AFS 服务器
+### 服务器选项
+
+| 选项 | 默认值 | 说明 |
+|------|--------|------|
+| `--host` | localhost | 监听主机地址 |
+| `--port` | 3000 | 监听端口 |
+| `--path` | /afs | 服务路径前缀 |
+| `--readonly` | false | 只读模式 |
+| `--cors` | false | 启用 CORS |
+| `--maxBodySize` | 10MB | 最大请求体大小 |
+
+### 配置优先级
+
+`命令行参数 > config.toml > 默认值`
+
+### 挂载远程服务器
 
 ```bash
 # 添加远程 HTTP 挂载
@@ -48,45 +159,55 @@ afs mount add /remote http://localhost:3000/afs
 # 添加 HTTPS 挂载
 afs mount add /api https://api.example.com/afs
 
-# 带描述的挂载
-afs mount add /remote http://localhost:3000/afs --description "Remote AFS server"
-
 # 访问远程挂载
 afs list /remote
 afs read /remote/file.txt
 ```
 
-### 支持的 URI 方案
-
-| 方案 | 示例 | 说明 |
-|------|------|------|
-| `fs://` | `fs:///path/to/dir` | 本地文件系统 |
-| `git://` | `git:///path/to/repo` | Git 仓库 |
-| `sqlite://` | `sqlite:///path/to/db.sqlite` | SQLite 数据库 |
-| `json://` | `json:///path/to/config.json` | JSON/YAML 文件 |
-| `http://` | `http://localhost:3000/afs` | HTTP 远程 AFS |
-| `https://` | `https://api.example.com/afs` | HTTPS 远程 AFS |
-
 ## 输出模式
 
 ```bash
 # 默认: Machine Truth (LLM/脚本友好)
-afs list /modules/fs
+afs list /src
+# 输出: 每行一个路径
 
 # JSON 结构化输出
-afs list /modules/fs --json
+afs list /src --json
 
-# LLM 优化输出
-afs list /modules/fs --view=llm
+# LLM 优化输出 (token 高效)
+afs list /src --view=llm
 
-# 人类友好输出
-afs list /modules/fs --view=human
+# 人类友好输出 (树形结构)
+afs list /src --view=human
 ```
 
-## 运行模式
+### 输出模式对比
+
+| 模式 | 特点 | 适用场景 |
+|------|------|----------|
+| default | 每行一个路径，pipe-safe | 脚本、grep、awk |
+| json | 结构化 JSON | 程序解析 |
+| llm | 语义事实，token 高效 | LLM/Agent |
+| human | 树形结构，带图标 | 人类阅读 |
+
+## explain 命令
+
+explain 是 AFS CLI 的一等公民，专为 LLM/Agent 设计：
+
+```bash
+# 解释命令行为
+afs explain afs ls
 
-- **直接模式** (默认): 直接调用 `@aigne/afs` 库
-- **daemon 模式** (`--daemon`): 通过 afsd 代理，支持状态持久化
+# 解释 AFS 对象
+afs explain /src/index.ts
+
+# JSON 输出 (供 agent 缓存)
+afs explain --json afs read
+```
+
+**explain vs help**:
+- `help`: 解决"我怎么用" - 面向人类
+- `explain`: 解决"它到底做了什么" - 面向 LLM/Agent，输出稳定可解析
 
 ## 退出码
 
@@ -97,3 +218,60 @@ afs list /modules/fs --view=human
 | 2 | 参数错误 |
 | 3 | 资源未找到 |
 | 4 | 权限拒绝 |
+| 5 | 运行时错误 |
+
+## 使用场景
+
+### 本地开发
+
+```bash
+# 配置项目挂载
+afs mount add /src fs://$(pwd)/src
+afs mount add /docs fs://$(pwd)/docs
+
+# 启动开发服务器供团队访问
+afs serve --host 0.0.0.0 --port 3000
+```
+
+### CI/CD 测试
+
+```bash
+# 启动测试数据服务器
+afs serve --readonly --port 8080 &
+
+# 测试用例访问
+curl http://localhost:8080/afs/rpc \
+  -d '{"method":"read","params":{"path":"/test-fixtures/data.json"}}'
+```
+
+### 临时文件共享
+
+```bash
+# 快速共享当前目录
+afs mount add /share fs://$(pwd)
+afs serve --host 0.0.0.0
+
+# 其他人访问
+afs mount add /remote-share http://your-ip:3000/afs
+afs list /remote-share
+```
+
+### 使用配置文件
+
+```bash
+# 创建配置
+cat > .afs-config/config.toml << 'EOF'
+[[mounts]]
+path = "/data"
+uri = "fs:///var/data"
+
+[serve]
+host = "0.0.0.0"
+port = 8080
+readonly = true
+cors = true
+EOF
+
+# 直接启动，无需参数
+afs serve
+```

package/dist/cli.cjs

@@ -2,6 +2,8 @@
 const require_rolldown_runtime = require('./_virtual/rolldown_runtime.cjs');
 const require_version = require('./version.cjs');
 const require_exec = require('./commands/exec.cjs');
+const require_loader = require('./config/loader.cjs');
+const require_index = require('./ui/index.cjs');
 const require_mount = require('./commands/mount.cjs');
 const require_explain = require('./commands/explain.cjs');
 const require_ls = require('./commands/ls.cjs');
@@ -12,6 +14,7 @@ const require_stat = require('./commands/stat.cjs');
 const require_write = require('./commands/write.cjs');
 require('./commands/index.cjs');
 const require_errors = require('./errors.cjs');
+const require_screen = require('./explorer/screen.cjs');
 let yargs = require("yargs");
 yargs = require_rolldown_runtime.__toESM(yargs);
 let yargs_helpers = require("yargs/helpers");
@@ -31,19 +34,58 @@ let yargs_helpers = require("yargs/helpers");
 * - afs write <path>           Write file content (--content or stdin)
 * - afs exec <path> <action>   Execute operation
 * - afs serve                  Start HTTP server to expose AFS
+* - afs explore [path]         Interactive TUI file explorer
 *
-* Output modes:
-* - Default: Machine Truth (LLM/script friendly)
+* Output modes (default: human):
+* - --view=human: Human friendly format with colors (default)
+* - --view=llm: LLM optimized output (token-efficient)
+* - --view=default: Machine truth (script/pipe friendly)
 * - --json: Structured JSON
-* - --view=llm: LLM optimized output
-* - --view=human: Human friendly format
 */
 function getViewType(argv) {
 	if (argv.json) return "json";
 	if (argv.view) return argv.view;
-	return "default";
+	return "human";
+}
+let headerShown = false;
+/**
+* Show header if in human view mode and not already shown
+*/
+async function maybeShowHeader(view) {
+	if (view !== "human" || headerShown || !require_index.shouldShowHeader()) return;
+	headerShown = true;
+	try {
+		require_index.printHeader({
+			version: require_version.VERSION,
+			mountCount: (await new require_loader.ConfigLoader().load(process.cwd())).mounts.length
+		});
+	} catch {
+		require_index.printHeader({
+			version: require_version.VERSION,
+			mountCount: 0
+		});
+	}
+}
+async function showHeaderIfNeeded() {
+	const args = process.argv.slice(2);
+	if ((args.length === 0 || args.includes("--help") || args.includes("-h") || args.length === 1 && [
+		"help",
+		"mount",
+		"explain"
+	].includes(args[0])) && require_index.shouldShowHeader()) try {
+		require_index.printHeader({
+			version: require_version.VERSION,
+			mountCount: (await new require_loader.ConfigLoader().load(process.cwd())).mounts.length
+		});
+	} catch {
+		require_index.printHeader({
+			version: require_version.VERSION,
+			mountCount: 0
+		});
+	}
 }
 async function main() {
+	await showHeaderIfNeeded();
 	const cli = (0, yargs.default)((0, yargs_helpers.hideBin)(process.argv)).scriptName("afs").version(require_version.VERSION).alias("version", "V").help("help").alias("help", "h").usage("$0 <command> [options]").option("json", {
 		type: "boolean",
 		description: "Output in JSON format",
@@ -55,7 +97,8 @@ async function main() {
 			"llm",
 			"human"
 		],
-		description: "Output view format",
+		default: "human",
+		description: "Output format (llm for AI agents, default for scripts)",
 		global: true
 	}).command(["list [path]", "ls [path]"], "List directory contents", (yargs$2) => yargs$2.positional("path", {
 		type: "string",
@@ -77,29 +120,32 @@ async function main() {
 		type: "string",
 		description: "Glob pattern to filter entries (e.g., *.ts, **/*.js)"
 	}), async (argv) => {
+		const view = getViewType(argv);
+		await maybeShowHeader(view);
 		const result = await require_ls.lsCommand(await require_runtime.createRuntime(), argv.path, {
 			maxDepth: argv.depth,
 			limit: argv.limit,
 			maxChildren: argv["max-children"],
 			pattern: argv.pattern
 		});
-		const view = getViewType(argv);
 		console.log(require_ls.formatLsOutput(result, view));
 	}).command("stat <path>", "Get file or directory info", (yargs$2) => yargs$2.positional("path", {
 		type: "string",
 		demandOption: true,
 		description: "Path to stat"
 	}), async (argv) => {
-		const result = await require_stat.statCommand(await require_runtime.createRuntime(), argv.path);
 		const view = getViewType(argv);
+		await maybeShowHeader(view);
+		const result = await require_stat.statCommand(await require_runtime.createRuntime(), argv.path);
 		console.log(require_stat.formatStatOutput(result, view));
 	}).command("read <path>", "Read file content", (yargs$2) => yargs$2.positional("path", {
 		type: "string",
 		demandOption: true,
 		description: "Path to read"
 	}), async (argv) => {
-		const result = await require_read.readCommand(await require_runtime.createRuntime(), argv.path);
 		const view = getViewType(argv);
+		await maybeShowHeader(view);
+		const result = await require_read.readCommand(await require_runtime.createRuntime(), argv.path);
 		console.log(require_read.formatReadOutput(result, view));
 	}).command("write <path>", "Write content to file (from --content or stdin)", (yargs$2) => yargs$2.positional("path", {
 		type: "string",
@@ -113,6 +159,8 @@ async function main() {
 		default: false,
 		description: "Append to file instead of overwrite"
 	}), async (argv) => {
+		const view = getViewType(argv);
+		await maybeShowHeader(view);
 		let content;
 		if (argv.content !== void 0) content = argv.content;
 		else {
@@ -121,7 +169,6 @@ async function main() {
 			content = Buffer.concat(chunks).toString("utf-8");
 		}
 		const result = await require_write.writeCommand(await require_runtime.createRuntime(), argv.path, content, { append: argv.append });
-		const view = getViewType(argv);
 		console.log(require_write.formatWriteOutput(result, view));
 		if (!result.success) process.exit(require_errors.ExitCode.RUNTIME_ERROR);
 	}).command("exec <path> [action]", "Execute operation on path", (yargs$2) => yargs$2.positional("path", {
@@ -136,14 +183,16 @@ async function main() {
 		type: "string",
 		description: "JSON parameters for the action"
 	}), async (argv) => {
+		const view = getViewType(argv);
+		await maybeShowHeader(view);
 		const params = argv.params ? JSON.parse(argv.params) : {};
 		const result = await require_exec.execCommand(await require_runtime.createRuntime(), argv.path, argv.action, params);
-		const view = getViewType(argv);
 		console.log(require_exec.formatExecOutput(result, view));
 		if (!result.success) process.exit(require_errors.ExitCode.RUNTIME_ERROR);
 	}).command("mount", "Manage mount configurations", (yargs$2) => yargs$2.command(["list", "ls"], "List all mounts", () => {}, async (argv) => {
-		const result = await require_mount.mountListCommand(process.cwd());
 		const view = getViewType(argv);
+		await maybeShowHeader(view);
+		const result = await require_mount.mountListCommand(process.cwd());
 		console.log(require_mount.formatMountListOutput(result.mounts, view));
 	}).command("add <path> <uri>", "Add a new mount (path=virtual path, uri=data source)", (yargs$3) => yargs$3.positional("path", {
 		type: "string",
@@ -157,11 +206,16 @@ async function main() {
 		type: "string",
 		description: "Human-readable description for this mount"
 	}), async (argv) => {
+		const view = getViewType(argv);
+		await maybeShowHeader(view);
 		const result = await require_mount.mountAddCommand(process.cwd(), argv.path, argv.uri, { description: argv.description });
-		if (getViewType(argv) === "json") console.log(JSON.stringify(result, null, 2));
-		else if (result.success) console.log(`Added mount ${argv.path}`);
-		else {
-			console.error(result.message);
+		if (view === "json") console.log(JSON.stringify(result, null, 2));
+		else if (result.success) {
+			const msg = view === "human" ? `${require_index.colors.success("Added mount")} ${require_index.colors.cyan(result.normalizedPath)}` : `Added mount ${result.normalizedPath}`;
+			console.log(msg);
+		} else {
+			const msg = view === "human" ? require_index.colors.error(result.message) : result.message;
+			console.error(msg);
 			process.exit(require_errors.ExitCode.RUNTIME_ERROR);
 		}
 	}).command(["remove <path>", "rm <path>"], "Remove a mount", (yargs$3) => yargs$3.positional("path", {
@@ -169,20 +223,33 @@ async function main() {
 		demandOption: true,
 		description: "Virtual path to remove (e.g., /src)"
 	}), async (argv) => {
+		const view = getViewType(argv);
+		await maybeShowHeader(view);
 		const result = await require_mount.mountRemoveCommand(process.cwd(), argv.path);
-		if (getViewType(argv) === "json") console.log(JSON.stringify(result, null, 2));
-		else if (result.success) console.log(`Removed mount ${argv.path}`);
-		else {
-			console.error(result.message);
+		if (view === "json") console.log(JSON.stringify(result, null, 2));
+		else if (result.success) {
+			const msg = view === "human" ? `${require_index.colors.success("Removed mount")} ${require_index.colors.cyan(argv.path)}` : `Removed mount ${argv.path}`;
+			console.log(msg);
+		} else {
+			const msg = view === "human" ? require_index.colors.error(result.message) : result.message;
+			console.error(msg);
 			process.exit(require_errors.ExitCode.RUNTIME_ERROR);
 		}
 	}).command("validate", "Validate mount configuration", () => {}, async (argv) => {
+		const view = getViewType(argv);
+		await maybeShowHeader(view);
 		const result = await require_mount.mountValidateCommand(process.cwd());
-		if (getViewType(argv) === "json") console.log(JSON.stringify(result, null, 2));
-		else if (result.valid) console.log("Configuration is valid");
-		else {
-			console.error("Configuration has errors:");
-			for (const error of result.errors) console.error(`  - ${error}`);
+		if (view === "json") console.log(JSON.stringify(result, null, 2));
+		else if (result.valid) {
+			const msg = view === "human" ? require_index.colors.success("Configuration is valid") : "Configuration is valid";
+			console.log(msg);
+		} else {
+			const titleMsg = view === "human" ? require_index.colors.error("Configuration has errors:") : "Configuration has errors:";
+			console.error(titleMsg);
+			for (const error of result.errors) {
+				const errMsg = view === "human" ? `  ${require_index.colors.dim("-")} ${require_index.colors.error(error)}` : `  - ${error}`;
+				console.error(errMsg);
+			}
 			process.exit(require_errors.ExitCode.RUNTIME_ERROR);
 		}
 	}).demandCommand(1, "Please specify a mount subcommand"), () => {}).command("explain [topic]", "Explain AFS concepts or AFS object", (yargs$2) => yargs$2.positional("topic", {
@@ -190,6 +257,7 @@ async function main() {
 		description: "Topic (mount, path, uri) or AFS path (e.g., /modules/src)"
 	}), async (argv) => {
 		const view = getViewType(argv);
+		await maybeShowHeader(view);
 		const topic = argv.topic;
 		if (topic?.startsWith("/")) {
 			const result = await require_explain.explainPathCommand(await require_runtime.createRuntime(), topic);
@@ -222,6 +290,7 @@ async function main() {
 		type: "number",
 		description: "Maximum request body size in bytes (default: 10MB)"
 	}), async (argv) => {
+		await maybeShowHeader(getViewType(argv));
 		const result = await require_serve.serveCommand({
 			host: argv.host,
 			port: argv.port,
@@ -232,6 +301,19 @@ async function main() {
 		});
 		console.log(require_serve.formatServeOutput(result));
 		await new Promise(() => {});
+	}).command("explore [path]", "Interactive TUI file explorer (PC Tools style)", (yargs$2) => yargs$2.positional("path", {
+		type: "string",
+		default: "/",
+		description: "Starting path to explore"
+	}), async (argv) => {
+		const configLoader = new require_loader.ConfigLoader();
+		const config = await configLoader.load(process.cwd());
+		await require_screen.createExplorerScreen({
+			runtime: await require_runtime.createRuntime(process.cwd(), { configLoader }),
+			startPath: argv.path,
+			version: require_version.VERSION,
+			mountCount: config.mounts.length
+		});
 	}).demandCommand(1, "Please specify a command").strict();
 	try {
 		await cli.parse();