dir-cli

dir-cli 用于检查本地项目的迁移或交接准备状态，并预览可重新生成文件的清理操作。支持识别 Node.js、Python、Java、Rust 和 Go 项目，检查 Git 状态，输出终端、JSON、Markdown 或 HTML 报告。发布包运行时不依赖第三方 npm 包。

English

安装

需要 Node.js 20 或更新版本。检查 Git 仓库或清理 Git 仓库中的文件时，系统 PATH 中还需要有 Git。

npm install -g dir-cli
dir-cli --version
dir-cli --help

从源码目录运行时，先执行 npm ci && npm run build，再执行 npm install -g .。

快速开始

dir-cli check --root /path/to/projects
dir-cli check --root /path/to/projects --format json --output status.json
dir-cli clean all --root /path/to/projects
dir-cli clean node --root /path/to/project --apply
dir-cli report migration --root /path/to/projects --format html --output report.html

clean 默认只预览目标。添加 --apply 后，在交互终端需要输入 yes 才会删除；自动化场景可使用 --apply --yes 跳过交互确认并删除列出的目标。

命令

| 命令 | 用途 | 主要选项 | | ------------------------------------------- | ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------- | | check | 扫描项目并检查 Git 准备状态 | --root 目录、--depth 层数、--include-hidden、--exclude 名称1,名称2、--format plain\|json、--output 文件 | | clean [node\|python\|java\|rust\|go\|all] | 预览或删除清理目标；默认 all | --root 目录、--apply、--yes、--format plain\|json | | report [status\|migration] | 生成准备度报告；默认 status | --root 目录、--depth 层数、--include-hidden、--exclude 名称1,名称2、--format html\|markdown\|json、--output 文件 | | config list\|get 键\|set 键 值\|reset | 读取或修改用户配置 | 见配置 | | locale list\|current\|en\|zh-CN | 查看或修改显示语言 | 英文、简体中文 |

--root 默认是当前目录。check 和 report 会检查根目录本身，默认不限扫描深度；--depth 0 只检查根目录。默认跳过隐藏目录，且始终不遍历目录链接。--exclude 接受以逗号分隔的目录名称，不支持 glob 模式。clean 使用配置中的扫描设置，不接受命令级扫描覆盖选项。clean --dry-run 可显式表示预览，但预览本就是默认行为。

JSON 模式只向标准输出写入 JSON。check 或 report 使用 --output 时，报告写入指定文件，保存提示写入标准错误。

check 的普通输出会显示每个项目的完整路径，便于区分不同目录下的同名项目。

准备状态与退出码

项目满足以下条件时才算就绪：当前分支有名称、跟踪远程分支、没有未提交更改或冲突，且相对上游分支既未领先也未落后。非 Git 项目需要处理。同一 Git 仓库内的多个子项目分别显示。check 和 report 只使用本地 Git 引用，不自动拉取；需要最新远程状态时请先执行 git fetch。

check 的退出码：所有检测到的项目就绪为 0，有项目需要处理为 2，扫描或 Git 出错为 1。report 成功生成报告时返回 0，即使有项目需要处理；扫描或 Git 出错时返回 1。未检测到项目时，准备度在 JSON 中为 null，在人类可读报告中为 N/A。status 与 migration 目前使用相同的报告数据。Markdown 和 HTML 报告会包含扫描错误。

clean 在扫描、规划或删除出错时返回 1。扫描或规划失败时不会开始删除。普通预览以及取消交互确认都不会删除文件。

清理目标与安全边界

| 项目 | 候选目标 | | ------- | ----------------------------------------------------------------------------------------------- | | Node.js | node_modules、dist、.next、.nuxt | | Python | __pycache__（含子目录）、.pytest_cache、dist、build、venv、.venv、*.egg-info 目录 | | Java | target、build、.gradle、out、dist | | Rust | target | | Go | bin、dist、build、coverage.out |

候选目标必须位于已识别的项目内。规划和执行阶段均会拒绝目标路径中的符号链接，以及解析后超出项目范围的路径。Git 已跟踪的目标会被跳过；无法确认 Git 保护时会停止清理。包含嵌套 Git 仓库的目标会被拒绝。执行器在删除前还会再次检查目标。

执行前请检查预览。名为 dist、build 或 bin 的目录可能含有手工编写的文件；选中目标内未跟踪或被 Git 忽略的文件仍可能被删除。若其他进程并发修改目录，Node.js 路径 API 无法彻底消除最后一次检查与删除之间的竞态。因此，仅在没有不可信进程修改目录树时执行清理。

配置

配置文件位于 ~/.dir-cli/config.json（各平台用户主目录），也可通过 DIR_CLI_CONFIG 指定路径。config set 会解析 JSON 值、校验完整配置并原子写入。

| 键 | 默认值 | 含义 | | -------------------- | ------------------------ | --------------------------------- | | locale | en | 显示语言：en 或 zh-CN | | scan.maxDepth | null | 最大扫描深度；null 表示不限深度 | | scan.includeHidden | false | 扫描项目时是否包含隐藏目录 | | scan.excludeDirs | 见 dir-cli config list | 扫描项目时跳过的目录名称 |

dir-cli config list
dir-cli config set scan.maxDepth 5
dir-cli config set scan.includeHidden true
dir-cli locale zh-CN

帮助、摘要、Git 问题说明、清理提示和可读报告支持两种语言。JSON 字段名与问题代码保持英文，便于自动化处理。底层系统错误和部分校验错误可能仍为英文。

开发

npm ci
npm run lint
npm test
npm run test:package
npm audit --omit=dev
npm pack --dry-run --json

npm test 会构建并运行 Node.js 测试。test:package 会把打包产物安装到隔离的临时目录，并运行已安装的 CLI。prepack 构建发布文件；prepublishOnly 运行 lint 和测试。与 2.x 的变化见更新记录。