dump-shitty-claude-md 0.1.0

package/Cargo.toml

@@ -0,0 +1,20 @@
+[package]
+name = "dump-shitty-claude-md"
+version = "0.1.0"
+edition = "2021"
+description = "Migrate project CLAUDE.md files to AGENTS.md across all repos in your home directory"
+license = "MIT"
+
+[dependencies]
+anyhow = "1"
+clap = { version = "4", features = ["derive"] }
+dialoguer = "0.11"
+dirs = "7.0.0"
+ignore = "0.4"
+serde = { version = "1", features = ["derive"] }
+serde_json = "1"
+trash = "5"
+
+[profile.release]
+lto = true
+strip = true

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Livio Gama
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,97 @@
+# 🗑️ dump-shitty-claude-md
+
+> **One `AGENTS.md` to rule them all — consolidate every agent instruction file in your home directory.**
+
+```bash
+bunx dump-shitty-claude-md
+```
+
+```
+DRY RUN — 290 CLAUDE.md in repos, 25 strays
+✓ dedupe   ~/code/api-server                          identical content → delete CLAUDE.md
+~ merge    ~/code/dashboard                           content differs → append CLAUDE.md into AGENTS.md
+✓ rename   ~/code/cli-tool                            no AGENTS.md — rename
+! skip     ~/code/dotfiles                            CLAUDE.md is a symlink — left alone
+! stray    ~/Desktop/playground/CLAUDE.md               not inside a git repo
+· global   ~/CLAUDE.md                                  protected — left alone
+```
+
+## 🧠 The decision matrix
+
+Every file is classified before anything is touched:
+
+| `CLAUDE.md` | `AGENTS.md` | Action |
+|---|---|---|
+| exists | absent | rename → `AGENTS.md` |
+| exists | identical / whitespace-equal (BOM/CRLF-tolerant) | delete `CLAUDE.md` |
+| exists | superset of `CLAUDE.md` | delete `CLAUDE.md` |
+| exists | subset of `CLAUDE.md` | `CLAUDE.md` replaces `AGENTS.md` |
+| exists | partial overlap | append with a `<!-- merged from CLAUDE.md -->` marker |
+| symlink | any | skip + report |
+| bare repo / FIFO / socket | — | skip + report |
+| outside a git repo | — | never touched (Trash is opt-in) |
+| `~/CLAUDE.md`, `~/.claude/**` | — | protected, never touched |
+
+Also warns on: `@import` syntax, `CLAUDE.local.md`, `AGENTS.local.md`,
+`.claude/CLAUDE.md`, non-UTF8, hardlinks, nested files, dead spellings
+(`claude.md`, `AGENT.md`).
+
+## 🧩 Supported formats
+
+`CLAUDE.md` is always in scope. Everything else is **off by default** — pick
+in the interactive prompt or pass `--migrate` / `--all-formats`:
+
+| File | Tool |
+|---|---|
+| `CLAUDE.md` | Claude Code — ✅ default |
+| `.github/copilot-instructions.md` | GitHub Copilot |
+| `GEMINI.md` | Gemini CLI — only when `.gemini/settings.json` allows `AGENTS.md` |
+| `.cursorrules` `.windsurfrules` `.clinerules` `.roorules` `.kilocoderules` `.rules` | Cursor, Windsurf, Cline, Roo, Kilo, Zed (legacy files) |
+| `.goosehints` | Goose |
+| `WARP.md` | Warp |
+| `CONVENTIONS.md` | Aider |
+| `.cursor/rules`, `.claude/rules`, `.github/instructions`, `.kiro/steering`, `.trae/rules`, `.openhands`, `.junie`, `.amazonq`, … | ❌ report-only — glob/frontmatter semantics `AGENTS.md` can't express |
+
+Multiple files in one repo merge in a single pass — `CLAUDE.md` wins the
+rename, the rest append with provenance markers.
+
+## 🚩 Flags
+
+| Flag | Effect |
+|---|---|
+| *(none)* | dry run — print the plan, touch nothing |
+| `--apply` | migrate files in place |
+| `--pr` | migrate on a branch + push + open PR/MR (`gh` / `glab`) |
+| `--migrate <fmt>` | also migrate formats (`cursor,copilot,gemini,…`) |
+| `--all-formats` | migrate every supported format |
+| `-y` | non-interactive, safe defaults (CLAUDE.md only, worktree) |
+| `--trivial` | lossless actions only — merges report-only |
+| `--trash-strays` | non-repo strays → OS Trash (Put Back-able) |
+| `--json` | machine-readable plan |
+| `PATH`, `--exclude`, `--follow-links` | scan control |
+
+## 🛡️ Safety model
+
+- **Dry run first** — nothing mutates without `--apply` / `--pr`.
+- **No data loss** — content always lands in `AGENTS.md`; committed files recoverable via git.
+- **Protected zones** — `~/CLAUDE.md`, `~/.claude/**`, bare repos, symlinks, strays.
+- **Idempotent** — re-runs converge, no double merges.
+- **Headless-safe** — `GIT_TERMINAL_PROMPT=0`, ssh `BatchMode`: no prompt can hang it.
+
+## Install
+
+`bunx` is the way — no install. The npm package ships prebuilt binaries for
+macOS arm64/x64, Linux x64/arm64 and Windows x64, all cross-compiled and
+published by the GitHub release workflow on every version tag:
+
+```bash
+bunx dump-shitty-claude-md           # dry run
+bunx dump-shitty-claude-md --apply   # migrate
+bunx dump-shitty-claude-md --pr      # migrate via PRs
+```
+
+Alternatives: `npm i -g dump-shitty-claude-md` · `cargo install dump-shitty-claude-md`
+
+## 📝 License
+
+MIT

package/bin/dump-shitty-claude-md.js

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+// Shim: exec the prebuilt binary for this platform.
+// Binaries live in bin/<platform>-<arch>/ — populated by scripts/build-all.sh
+// before npm publish. Source channel for other platforms: crates.io.
+const { spawnSync } = require("child_process");
+const fs = require("fs");
+const path = require("path");
+
+const isWin = process.platform === "win32";
+const exe = `dump-shitty-claude-md${isWin ? ".exe" : ""}`;
+const bin = path.join(
+  __dirname,
+  `${process.platform}-${process.arch}`,
+  exe,
+);
+
+if (!fs.existsSync(bin)) {
+  console.error(
+    `dump-shitty-claude-md: no prebuilt binary for ${process.platform}-${process.arch}.\n` +
+      "Install via cargo instead:  cargo install dump-shitty-claude-md",
+  );
+  process.exit(1);
+}
+
+const r = spawnSync(bin, process.argv.slice(2), { stdio: "inherit" });
+process.exit(r.status ?? (r.error ? 1 : 0));

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "dump-shitty-claude-md",
+  "version": "0.1.0",
+  "description": "Migrate project CLAUDE.md files to AGENTS.md across all repos in your home directory",
+  "keywords": [
+    "claude",
+    "agents-md",
+    "claude-md",
+    "codex",
+    "copilot",
+    "agent",
+    "cli"
+  ],
+  "bin": {
+    "dump-shitty-claude-md": "bin/dump-shitty-claude-md.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "Cargo.toml",
+    "Cargo.lock",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "cargo build --release && mkdir -p bin/$(node -p 'process.platform')-$(node -p 'process.arch') && cp target/release/dump-shitty-claude-md bin/$(node -p 'process.platform')-$(node -p 'process.arch')/",
+    "test": "cargo test"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "os": [
+    "darwin",
+    "linux",
+    "win32"
+  ],
+  "license": "MIT"
+}

package/src/gitops.rs

@@ -0,0 +1,336 @@
+use anyhow::{bail, Context, Result};
+use serde::Serialize;
+use std::path::{Path, PathBuf};
+use std::process::Command;
+
+use crate::plan::{self, Plan, AGENTS};
+
+pub const BRANCH: &str = "chore/consolidate-agent-instructions";
+pub const COMMIT_MSG: &str = "chore: consolidate agent instruction files into AGENTS.md";
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, clap::ValueEnum, Serialize)]
+#[serde(rename_all = "kebab-case")]
+pub enum Strategy {
+    /// Migrate inside a temporary `git worktree` — the checkout is never touched.
+    Worktree,
+    /// Create the branch in the repo itself (requires clean tree), restore after.
+    InPlace,
+}
+
+#[derive(Debug, Default, Serialize)]
+pub struct PrOutcome {
+    pub strategy: Option<Strategy>,
+    pub branch: Option<String>,
+    pub committed: bool,
+    pub pushed: bool,
+    pub pr_url: Option<String>,
+    pub skipped: Option<String>,
+    pub warnings: Vec<String>,
+}
+
+/// Env that makes git/gh fail fast instead of hanging on prompts
+/// (credentials, ssh passphrases, pinentry) in headless runs.
+fn no_prompt_env(cmd: &mut Command) -> &mut Command {
+    cmd.env("GIT_TERMINAL_PROMPT", "0")
+        .env("GIT_SSH_COMMAND", "ssh -oBatchMode=yes")
+        .env("GCM_INTERACTIVE", "Never")
+}
+
+fn git(repo: &Path, args: &[&str]) -> Result<String> {
+    let out = no_prompt_env(Command::new("git").arg("-C").arg(repo).args(args))
+        .output()
+        .context("failed to spawn git")?;
+    if !out.status.success() {
+        bail!(
+            "git {} failed: {}",
+            args.join(" "),
+            String::from_utf8_lossy(&out.stderr).trim()
+        );
+    }
+    Ok(String::from_utf8_lossy(&out.stdout).trim().to_string())
+}
+
+fn git_ok(repo: &Path, args: &[&str]) -> bool {
+    no_prompt_env(Command::new("git").arg("-C").arg(repo).args(args))
+        .output()
+        .map(|o| o.status.success())
+        .unwrap_or(false)
+}
+
+/// True when `git status --porcelain` is empty (no modified or untracked files).
+pub fn is_clean(repo: &Path) -> bool {
+    git(repo, &["status", "--porcelain"])
+        .map(|s| s.is_empty())
+        .unwrap_or(false)
+}
+
+/// Base ref to branch from: `origin/HEAD` after a best-effort fetch, else `HEAD`.
+fn base_ref(repo: &Path) -> String {
+    let _ = git(repo, &["fetch", "origin", "--quiet"]);
+    if git_ok(repo, &["rev-parse", "--verify", "origin/HEAD"]) {
+        "origin/HEAD".into()
+    } else {
+        "HEAD".into()
+    }
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum RemoteKind {
+    Github,
+    Gitlab,
+    Other,
+}
+
+pub fn remote_kind(repo: &Path) -> RemoteKind {
+    let Ok(url) = git(repo, &["remote", "get-url", "origin"]) else {
+        return RemoteKind::Other;
+    };
+    if url.contains("github.") {
+        RemoteKind::Github
+    } else if url.contains("gitlab.") {
+        RemoteKind::Gitlab
+    } else {
+        RemoteKind::Other
+    }
+}
+
+fn cli_available(name: &str) -> bool {
+    Command::new(name)
+        .arg("--version")
+        .output()
+        .map(|o| o.status.success())
+        .unwrap_or(false)
+}
+
+const PR_BODY: &str = "Consolidates agent instruction files (`CLAUDE.md` and friends) into `AGENTS.md`.\n\
+\n\
+Claude Code ≥2.1.277 falls back to `AGENTS.md` when no `CLAUDE.md` exists,\n\
+and Codex, Cursor, Copilot, Zed and friends read it natively —\n\
+so a single file now serves every agent.\n\
+\n\
+Generated by [dump-shitty-claude-md](https://github.com/LivioGama/dump-shitty-claude-md).";
+
+/// `gh pr create`, falling back to the URL of an existing PR for the branch.
+fn create_github_pr(dir: &Path, outcome: &mut PrOutcome) -> Result<()> {
+    if !cli_available("gh") {
+        outcome.warnings.push("gh CLI not found — PR not created".into());
+        return Ok(());
+    }
+    let out = no_prompt_env(
+        Command::new("gh")
+            .arg("pr")
+            .arg("create")
+            .args(["--title", COMMIT_MSG, "--body", PR_BODY, "--head", BRANCH])
+            .current_dir(dir),
+    )
+    .output()
+    .context("failed to spawn gh")?;
+    if out.status.success() {
+        outcome.pr_url = Some(String::from_utf8_lossy(&out.stdout).trim().to_string());
+        return Ok(());
+    }
+    // Create failed — maybe a PR for this branch already exists.
+    let existing = no_prompt_env(
+        Command::new("gh")
+            .args(["pr", "list", "--head", BRANCH, "--json", "url", "--jq"])
+            .arg(".[0].url")
+            .current_dir(dir),
+    )
+    .output()
+    .ok()
+    .filter(|o| o.status.success())
+    .map(|o| String::from_utf8_lossy(&o.stdout).trim().to_string())
+    .filter(|u| !u.is_empty());
+    if let Some(url) = existing {
+        outcome.pr_url = Some(url);
+        outcome.warnings.push("PR already existed for branch".into());
+    } else {
+        outcome.warnings.push(format!(
+            "gh pr create failed: {}",
+            String::from_utf8_lossy(&out.stderr).trim()
+        ));
+    }
+    Ok(())
+}
+
+/// `glab mr create`; the MR URL is scraped from the last http line of output.
+fn create_gitlab_pr(dir: &Path, outcome: &mut PrOutcome) -> Result<()> {
+    if !cli_available("glab") {
+        outcome.warnings.push("glab CLI not found — MR not created".into());
+        return Ok(());
+    }
+    let out = no_prompt_env(
+        Command::new("glab")
+            .args(["mr", "create", "--title", COMMIT_MSG, "--description"])
+            .arg(PR_BODY)
+            .args(["--source-branch", BRANCH, "--yes"])
+            .current_dir(dir),
+    )
+    .output()
+    .context("failed to spawn glab")?;
+    if out.status.success() {
+        let text = String::from_utf8_lossy(&out.stdout);
+        outcome.pr_url = text
+            .lines()
+            .rfind(|l| l.contains("http"))
+            .map(str::trim)
+            .map(str::to_owned);
+    } else {
+        outcome.warnings.push(format!(
+            "glab mr create failed: {}",
+            String::from_utf8_lossy(&out.stderr).trim()
+        ));
+    }
+    Ok(())
+}
+
+fn commit_push_pr(dir: &Path, repo_for_push: &Path, rels: &[PathBuf], outcome: &mut PrOutcome) -> Result<()> {
+    // Per-path best-effort adds: a pathspec that matches neither worktree nor
+    // index (e.g. a source file never tracked at the worktree base) is a hard
+    // error, but there may simply be nothing to stage for that path.
+    let mut paths: Vec<String> = rels
+        .iter()
+        .map(|r| r.to_string_lossy().to_string())
+        .collect();
+    paths.push(AGENTS.into());
+    for p in &paths {
+        let _ = git_ok(dir, &["add", "-A", "--", p]);
+    }
+
+    // Nothing staged → nothing to commit (can happen if files were untracked+ignored).
+    let pathspecs: Vec<&str> = paths.iter().map(String::as_str).collect();
+    let mut args = vec!["status", "--porcelain", "--"];
+    args.extend(pathspecs.iter());
+    if git(dir, &args)?.is_empty() {
+        outcome.warnings.push("nothing staged — files may be gitignored".into());
+        return Ok(());
+    }
+
+    // Index already contains exactly our staged paths — commit it wholesale
+    // (a pathspec here could itself fail to match).
+    git(dir, &["commit", "-m", COMMIT_MSG])?;
+    outcome.committed = true;
+
+    match git(dir, &["push", "-u", "origin", BRANCH]) {
+        Ok(_) => outcome.pushed = true,
+        Err(e) => {
+            outcome.warnings.push(format!("push failed: {e:#}"));
+            return Ok(());
+        }
+    }
+
+    match remote_kind(repo_for_push) {
+        RemoteKind::Github => create_github_pr(dir, outcome),
+        RemoteKind::Gitlab => create_gitlab_pr(dir, outcome),
+        RemoteKind::Other => {
+            outcome
+                .warnings
+                .push("origin is not github/gitlab — PR not created".into());
+            Ok(())
+        }
+    }
+}
+
+/// Source paths of the migrating plans, relative to the repo root.
+fn rel_paths(plans: &[&Plan]) -> Vec<PathBuf> {
+    plans.iter().map(|p| p.file.clone()).collect()
+}
+
+/// Worktree strategy: branch off `origin/HEAD` in a temp worktree, mirror the
+/// working-tree state of all affected files, migrate, commit, push, PR, clean up.
+fn run_worktree(repo: &Path, plans: &[&Plan], outcome: &mut PrOutcome) -> Result<()> {
+    let base = base_ref(repo);
+    let tmp = std::env::temp_dir().join(format!(
+        "dscm-wt-{}-{}",
+        std::process::id(),
+        repo.file_name()
+            .and_then(|n| n.to_str())
+            .unwrap_or("repo")
+    ));
+    let tmp_str = tmp.to_string_lossy().to_string();
+
+    // Branch may already exist from a previous run → retry without -b.
+    if git(repo, &["worktree", "add", "-b", BRANCH, &tmp_str, &base]).is_err() {
+        git(repo, &["worktree", "add", &tmp_str, BRANCH])
+            .context("git worktree add failed")?;
+    }
+    outcome.branch = Some(BRANCH.into());
+
+    let rels = rel_paths(plans);
+    let result = (|| -> Result<()> {
+        // Mirror working-tree state of every affected file into the worktree so
+        // uncommitted edits/untracked files are preserved in the PR.
+        for rel in rels.iter().chain(std::iter::once(&PathBuf::from(AGENTS))) {
+            let src = repo.join(rel);
+            let dst = tmp.join(rel);
+            if src.symlink_metadata().is_ok() {
+                if let Some(parent) = dst.parent() {
+                    std::fs::create_dir_all(parent)?;
+                }
+                std::fs::copy(&src, &dst)
+                    .with_context(|| format!("copy {}", src.display()))?;
+            } else if dst.exists() {
+                std::fs::remove_file(&dst)?;
+            }
+        }
+        for p in plans {
+            plan::apply(&tmp, &p.file, p.action)?;
+        }
+        commit_push_pr(&tmp, repo, &rels, outcome)
+    })();
+
+    let _ = git(repo, &["worktree", "remove", "--force", &tmp_str]);
+    result
+}
+
+/// In-place strategy: branch in the user's checkout (requires clean tree),
+/// migrate, commit, push, PR, then restore the previous branch.
+fn run_in_place(repo: &Path, plans: &[&Plan], outcome: &mut PrOutcome) -> Result<()> {
+    if !is_clean(repo) {
+        bail!("working tree is dirty — use the worktree strategy instead");
+    }
+    let prev = git(repo, &["branch", "--show-current"])?;
+
+    let base = base_ref(repo);
+    if base == "origin/HEAD" {
+        let ahead = git(repo, &["rev-list", "--count", "origin/HEAD..HEAD"])
+            .unwrap_or_else(|_| "0".into());
+        if ahead != "0" {
+            outcome.warnings.push(format!(
+                "HEAD is {ahead} commit(s) ahead of origin/HEAD — PR will include them"
+            ));
+        }
+    }
+
+    if git(repo, &["checkout", "-b", BRANCH]).is_err() {
+        git(repo, &["checkout", BRANCH])?;
+    }
+    outcome.branch = Some(BRANCH.into());
+
+    let result = (|| -> Result<()> {
+        for p in plans {
+            plan::apply(repo, &p.file, p.action)?;
+        }
+        commit_push_pr(repo, repo, &rel_paths(plans), outcome)
+    })();
+
+    if !prev.is_empty() {
+        let _ = git(repo, &["checkout", &prev]);
+    }
+    result
+}
+
+pub fn run(repo: &Path, plans: &[&Plan], strategy: Strategy) -> PrOutcome {
+    let mut outcome = PrOutcome {
+        strategy: Some(strategy),
+        ..Default::default()
+    };
+    let res = match strategy {
+        Strategy::Worktree => run_worktree(repo, plans, &mut outcome),
+        Strategy::InPlace => run_in_place(repo, plans, &mut outcome),
+    };
+    if let Err(e) = res {
+        outcome.warnings.push(format!("{e:#}"));
+    }
+    outcome
+}