@shuiyangsuan/cli 0.0.2 → 0.0.4

package/README.md

@@ -45,6 +45,9 @@ by delete my-folder/
 # 使用别名
 by rm file.txt
 by del file.txt
+
+# 无参数调用（使用配置文件中的 defaultPatterns）
+by delete
 ```
 
 ### Glob 模式匹配
@@ -70,7 +73,7 @@ by delete "*.tmp" "*.cache" "dist/**"
 by delete "*.tmp" --force
 by delete "*.tmp" -f
 
-# 预览模式，仅查看将要删除的内容
+# 预览模式，仅显示将要删除的内容
 by delete "*.tmp" --dry-run
 by delete "*.tmp" -n
 
@@ -96,6 +99,198 @@ by delete "*.tmp" "*.log" --force --verbose
 by delete "dist" "build" ".next" --dry-run
 ```
 
+## 🔧 编程模式
+
+本 CLI 工具支持以编程方式调用，方便在其他 Node.js 项目中使用。
+
+### 安装
+
+```bash
+npm install @shuiyangsuan/cli
+```
+
+### 基础用法
+
+```typescript
+import { executeDelete, readConfig } from '@shuiyangsuan/cli';
+
+// 读取配置
+const config = await readConfig();
+
+// 执行删除
+const result = await executeDelete(['node_modules', 'dist'], config, {
+	force: true, // 强制删除，不提示确认
+	verbose: true, // 详细输出
+});
+
+console.log(`成功删除 ${result.deletedCount} 个文件`);
+console.log('删除的文件:', result.deletedFiles);
+```
+
+### 预览模式
+
+```typescript
+import { executeDelete, readConfig } from '@shuiyangsuan/cli';
+
+const config = await readConfig();
+
+// 预览将要删除的内容，不实际删除
+const result = await executeDelete(['**/*.log', 'dist'], config, {
+	dryRun: true,
+	verbose: true,
+});
+
+console.log('将要删除的文件:', result.deletedFiles);
+```
+
+### 仅收集文件列表
+
+```typescript
+import { collectFilesToDelete } from '@shuiyangsuan/cli';
+
+// 仅收集匹配的文件列表，不执行删除
+const files = await collectFilesToDelete(['**/*.ts', '**/*.js'], {});
+
+console.log('匹配的文件:');
+files.forEach((file) => console.log(`  - ${file}`));
+```
+
+### 在构建脚本中使用
+
+```typescript
+// build.ts
+import { executeDelete, readConfig } from '@shuiyangsuan/cli';
+import { execSync } from 'child_process';
+
+async function build() {
+	const config = await readConfig();
+
+	// 清理旧的构建产物
+	await executeDelete(['dist', 'build'], config, {
+		force: true,
+		verbose: true,
+	});
+
+	// 执行构建
+	execSync('tsc', { stdio: 'inherit' });
+
+	console.log('构建完成!');
+}
+
+build().catch(console.error);
+```
+
+### 完整示例 - 带错误处理
+
+```typescript
+import { executeDelete, readConfig, type DeleteResult } from '@shuiyangsuan/cli';
+
+async function cleanup() {
+	try {
+		const config = await readConfig();
+
+		const result: DeleteResult = await executeDelete(['node_modules', 'dist', '**/*.log'], config, {
+			force: false, // 需要确认
+			verbose: true, // 详细输出
+		});
+
+		console.log('✅ 清理完成!');
+		console.log(`成功：${result.deletedCount}, 失败：${result.failedCount}`);
+
+		if (result.errors.length > 0) {
+			console.error('错误信息:');
+			result.errors.forEach((err) => console.error(`  - ${err}`));
+		}
+	} catch (error) {
+		console.error('清理失败:', (error as Error).message);
+		process.exit(1);
+	}
+}
+
+cleanup();
+```
+
+### API 文档
+
+#### executeDelete(patterns, config, options?)
+
+执行删除操作的主要函数。
+
+**参数：**
+
+- `patterns`: string[] - 要删除的文件或文件夹路径/模式
+- `config`: CliConfig - CLI 配置对象
+- `options`: DeleteOptions (可选) - 删除选项
+
+**返回值：** Promise<DeleteResult>
+
+**DeleteResult 接口：**
+
+```typescript
+{
+  deletedCount: number;    // 成功删除的数量
+  failedCount: number;     // 失败的数量
+  deletedFiles: string[];  // 删除的文件列表
+  errors: string[];        // 错误信息列表
+}
+```
+
+#### DeleteOptions
+
+```typescript
+{
+  force?: boolean;       // 强制删除，不提示确认
+  dryRun?: boolean;      // 预览模式，不实际删除
+  verbose?: boolean;     // 详细输出模式
+  useDefaults?: boolean; // 使用配置文件中的默认模式
+}
+```
+
+#### collectFilesToDelete(patterns, options)
+
+收集匹配的文件列表，但不执行删除。
+
+**参数：**
+
+- `patterns`: string[] - 文件或文件夹路径/模式
+- `options`: DeleteOptions - 删除选项
+
+**返回值：** Promise<string[]>
+
+### 导入类型
+
+```typescript
+import type {
+	DeleteOptions, // 删除选项
+	DeleteResult, // 删除结果
+	CliConfig, // 配置类型
+} from '@shuiyangsuan/cli';
+```
+
+## 📝 配置文件
+
+可以通过配置文件自定义默认行为。
+
+### 配置文件格式
+
+创建 `.clirc.json` 或 `cli.config.json`：
+
+```json
+{
+	"defaultPatterns": ["node_modules/**", "dist/**", "**/.turbo"],
+	"force": false,
+	"dryRun": false,
+	"verbose": true
+}
+```
+
+### 配置项说明
+
+- `defaultPatterns`: 默认的文件匹配模式列表
+- `force`: 是否强制删除（跳过确认）
+- `dryRun`: 预览模式（不实际删除）
+- `verbose`: 详细输出模式
+
 ## 📖 命令说明
 
 ### delete (rm, del)
@@ -103,24 +298,28 @@ by delete "dist" "build" ".next" --dry-run
 删除文件和文件夹，支持 glob 模式匹配。
 
 **语法：**
+
 ```bash
 by delete <patterns...> [options]
 ```
 
 **参数：**
+
 - `<patterns...>` - 要删除的文件或文件夹路径/模式（支持多个）
 
 **选项：**
+
 - `-f, --force` - 强制删除，不提示确认
 - `-n, --dry-run` - 预览模式，仅显示将要删除的内容
 - `-v, --verbose` - 详细输出模式
 - `-d, --use-defaults` - 使用配置文件中的默认模式
 
 **退出码：**
+
 - `0` - 成功
 - `1` - 失败或有错误发生
 
-## 🔧 开发
+## 🧪 开发
 
 ### 环境要求
 
@@ -192,16 +391,13 @@ bun test --coverage
 ```
 
 测试覆盖以下场景：
+
 - ✅ 基础删除功能（单文件、多文件、文件夹）
 - ✅ 预览模式（dry-run）
 - ✅ 强制删除模式
 - ✅ 错误处理
 - ✅ 复杂场景（嵌套目录、特殊字符文件名）
 
-## 📝 配置
-
-可以通过配置文件自定义默认行为（配置功能开发中）。
-
 ## 🤝 贡献
 
 欢迎提交 Issue 和 Pull Request！