hamza-ali-shahjahan/hamzaish

/tidy — the cleanup stage

Rot accumulates in every repo: links that point at moved/gitignored files, a key that slipped into a commit, an asset nothing references, a dependency that 404s on install. None of it is visible day-to-day — it surfaces at the worst time (a reader's 404, a failing CI, a leaked key). /tidy is the stage where you find and clear it on purpose.

This is a stage, not a gate. The fast guards (check-changelog, check-assets) block on every push; /tidy is the broad, report-first sweep you run when it's time to clean.

How to run it

bun run tidy                      # the current repo → summary + recommended next steps
bun run tidy <path>               # a specific repo
bun run tidy --all ~/Claude       # every git repo under a folder → one aggregate table
bun run tidy --links              # drill into one category (--secrets --files --deps)

It scans four kinds of rot and shows the extent first (a count per category) so you never get a wall of output:

	what it catches
🔗 Links	markdown/HTML links to missing files, or that resolve only to a gitignored target (works on the author's disk, 404s for everyone else)
🔑 Secrets	high-confidence committed-key patterns (AWS, Stripe, GitHub, Google, Slack, private-key blocks) — flagged for review, not auto-judged
🗑 Dead files	committed images/assets that nothing references — safe to prune
📦 Deps	package.json dependencies that don't resolve on npm (the dead-@inngest/sdk class)

The flow (report → recommend → ask → fix)

1. Run it. Present the summary table — extent per category, per repo.
2. Recommend. Call out which categories matter and why (a broken link is a reader's 404; a flagged secret needs rotating; an unresolvable dep breaks every install).
3. Ask. Let the operator pick what to clean. Never assume.
4. Fix with confirmation — plan, then apply. bun run tidy --fix <repo> prints the exact change plan (which broken links get de-linked) without writing anything; re-run with --apply to make those edits. So you always see each change first. Auto-fix is narrow on purpose: it only de-links broken/gitignored text links ([text](bad) → text). Secrets, deps, images/HTML links, and file deletions are never auto-applied — they're listed as manual with guidance (rotate a key, pick the right package), because their fix is judgement, not a line-edit. Survey many with --all, then --fix one repo at a time.

Discipline

• Report-first, always. The value is seeing the rot before touching anything.
• Don't gate on it. /tidy is slow (network dep checks) and broad — keep it a stage, not a push-blocker. The narrow guards stay the gate.
• Secrets are review-grade. A pattern match is a prompt to look, not a verdict — and if real, the fix is rotate-the-key, not just delete-the-line.
• Frozen dirs are skipped (_archive/, node_modules/) — they're not yours to tidy.
• The engine is portable. scripts/tidy.ts runs against any repo path — that's what makes the 100+-repo sweep one command.