hamza-ali-shahjahan/hamzaish

/tidy —— 清理阶段

每个仓库都会积累腐化：指向已移动或被 gitignore 忽略文件的链接、不小心提交的密钥、没人引用的资源、安装时报 404 的依赖。 这些事情平时看不见——它们会在最糟糕的时候冒出来（读者遇到 404、CI 失败、密钥泄露）。/tidy 是让你主动发现并清除这些腐化的阶段。

这是一个阶段，不是一道关卡。快速的守卫（check-changelog、check-assets）会在每次推送时拦截；/tidy 是范围更广、报告优先的扫描，你会在需要清理时运行它。

如何运行

bun run tidy                      # 当前仓库 → 总结 + 推荐下一步
bun run tidy <path>               # 特定仓库
bun run tidy --all ~/Claude       # 某个文件夹下的每个 git 仓库 → 一个汇总表格
bun run tidy --links              # 深入一个类别（--secrets --files --deps）

它会扫描四种腐化类型，首先显示范围（每个类别的计数），这样你永远不会看到一堆输出：

	捕获内容
🔗 链接	指向缺失文件的 markdown/HTML 链接，或仅解析到被 gitignore 忽略的目标（在作者的磁盘上能工作，对其他人则返回 404）
🔑 密钥	高置信度的已提交密钥模式（AWS、Stripe、GitHub、Google、Slack、私钥块）——标记为待审查，而不是自动判定
🗑 死文件	已提交但没有任何地方引用的图片/资源——可以安全删除
📦 依赖	package.json 中在 npm 上无法解析的依赖（已废弃的 @inngest/sdk 这类）

流程（报告 → 建议 → 询问 → 修复）

1. 运行它。 显示汇总表——每个类别每个仓库的范围。
2. 建议。 指出哪些类别重要及其原因（一个断链是读者的 404；一个标记的密钥需要轮换；一个无法解析的依赖破坏每次安装）。
3. 询问。 让操作者选择要清理的内容。永远不要替用户做决定。
4. 确认后修复——先计划，再应用。 bun run tidy --fix <repo> 会打印出确切的变更计划（哪些断链会被解除链接）而不写入任何内容；重新运行并加上 --apply 来执行这些修改。这样你总是先看到每个更改。自动修复的范围是精心限定的：它只解除断链或被 gitignore 忽略的文本链接（[text](bad) → text）。密钥、依赖、图片/HTML 链接以及文件删除永远不会被自动应用——它们会作为手动操作列出，并附有指导（轮换密钥、选择正确的包），因为修复它们需要判断，而不仅仅是行编辑。使用 --all 检查多个仓库，然后一次对一个仓库执行 --fix。

原则

• 始终报告优先。 价值在于看到腐化，然后再动手。
• 不要用它来阻塞流程。 /tidy 很慢（需要网络依赖检查）且范围很广——把它作为一个阶段，而不是推送拦截器。狭窄的守卫仍然是关卡。
• 密钥是审查级别的。 模式匹配只是提示你去查看，而不是最终判决——如果真的找到，修复方法是轮换密钥，而不是简单地删除一行。
• 跳过冻结目录（_archive/、node_modules/）——它们不在你的清理范围内。
• 引擎是可移植的。 scripts/tidy.ts 可以针对任何仓库路径运行——这就是为什么一次扫描 100 多个仓库只需要一条命令。