forgemap 0.1.0-dev.23-9e4d2ae → 0.1.0-dev.26-b896caf

package/README.md

@@ -1,6 +1,6 @@
 <div align="center">
 
-# 🧰 forgemap
+# 🗺️ forgemap
 
 **One consistent local layout for every repo you clone — across every forge**
 
@@ -29,9 +29,11 @@ That's it. Every repo lands at a predictable `<root>/<forge.dir>/<owner>/<repo>`
 - **🔍 Fuzzy search** — `forgemap search <term>` finds local repos by owner or repo name (powered by [Fuse.js](https://www.fusejs.io/)).
 - **🤖 Forge-aware** — `type: 'github'` shells out to `gh`; `type: 'git'` uses plain `git clone` with no extra dependencies.
 - **🔁 Mass sync + status** — `forgemap sync` fetches every clone in parallel, `forgemap status` shows branch / dirty / ahead / behind per repo.
+- **📥 Import existing trees** — `forgemap import <path>` adopts a folder already laid out as `<server>/<owner>/<repo>`, reconciles each repo against its git remote (spotting moved or deleted remotes), and derives a config.
+- **🧹 Safe cleanup** — `forgemap cleanup` deletes long-idle local clones, but only the ones that are clean, fully pushed, and still exist on their remote — so nothing unbacked-up is ever lost.
 - **🛡️ Preflight validate** — `forgemap validate` checks the config schema and required CLIs before you discover a problem mid-clone.
-- **🧰 Typed config** — `forgemap.config.ts` with `defineForgeMapConfig()` and walk-up discovery.
-- **🚀 Shell-friendly** — `forgemap cd <slug>` (via `shell-init`) actually changes directory.
+- **🧰 Typed config** — `forgemap.config.ts` with `defineForgeMapConfig()`, parent walk-up discovery, and a global fallback.
+- **🚀 Shell-friendly** — `forgemap shell-init --install` wires up real `forgemap cd <slug>` **and** tab-completion in one step.
 
 ## 📦 Installation
 
@@ -58,9 +60,10 @@ Hacking on forgemap itself? See [CONTRIBUTING.md → Trying the CLI locally](CON
 cd ~/projects
 forgemap config init
 
-# 2. Wire up the shell integration once — adds real `forgemap cd`.
-eval "$(forgemap shell-init)"            # zsh/bash, add to ~/.zshrc to persist
-# fish: forgemap shell-init fish | source
+# 2. Wire up the shell integration once — real `forgemap cd` + tab-completion.
+forgemap shell-init --install            # appends loaders to ~/.zshrc (or bashrc/fish)
+source ~/.zshrc                          # re-source once, then it's automatic
+# Prefer manual? eval "$(forgemap shell-init)"   ·   fish: forgemap shell-init fish | source
 
 # 3. Clone — any slug form works.
 forgemap clone kirchDev/laravel-pbac
@@ -109,6 +112,33 @@ forgemap status                      # tree: branch / dirty / ahead↑ / behind
 forgemap status --format json        # structured for jq + scripts
 ```
 
+All tree output (`status`, `search`, `import`) groups as `forge → owner → repo`. Network operations (`sync`, `import`, `cleanup`) run with a hard timeout and non-interactive SSH, so an unreachable host can never wedge a run.
+
+### Adopt an existing layout — `import`
+
+Already have a folder full of repos laid out as `<server>/<owner>/<repo>`? Adopt it without re-cloning:
+
+```bash
+forgemap import ~/projects                  # reconcile + derive/write forgemap.config.ts
+forgemap import ~/projects --no-remote-check # offline: folder-vs-origin only (instant)
+forgemap import ~/projects --fix             # move folders / fix origin URLs to match the remote
+forgemap import ~/projects --no-write-config # only report, don't touch the config
+forgemap import ~/projects --format json
+```
+
+For each repo `import` compares the folder's `<owner>/<repo>` against the git `origin`, checks whether the remote still exists or was moved/renamed (GitHub via a batched `gh` GraphQL query, other forges via `git ls-remote`), and derives `root` + one forge per server directory. Read-only by default — `--fix` is the only thing that touches the filesystem.
+
+### Reclaim disk — `cleanup`
+
+```bash
+forgemap cleanup                     # list deletable clones, then type "yes" to confirm
+forgemap cleanup --dry-run           # show candidates + why every other idle repo is kept
+forgemap cleanup --days 540          # idle threshold in days (default 365)
+forgemap cleanup --include-dirty --include-unpushed   # also delete repos with local-only work (lost!)
+```
+
+A repo is only deleted when it is idle for `--days`+ days (by last **local** commit), has a clean working tree, has nothing unpushed, **and** its remote still exists — so everything removed is provably backed up. Repos without a remote (or with a gone/unreachable one) are never touched; empty owner directories left behind are pruned automatically. Deletion needs an explicit typed `yes` (or `--yes`).
+
 ### Preflight your config
 
 ```bash
@@ -118,6 +148,24 @@ forgemap validate --json | jq        # machine-readable for pre-commit hooks
 
 Validates the schema, required CLI tools (`git` always, `gh` when a `type: 'github'` forge is configured), `gh auth status`, and that the configured root exists.
 
+### Shell integration & completion
+
+```bash
+forgemap shell-init --install        # cd wrapper + completion → your rc file (idempotent)
+forgemap completion --install        # completion only, if you don't want the cd wrapper
+forgemap shell-init                  # print the wrapper (manual: eval "$(…)")
+forgemap completion bash             # print the completion script for bash/zsh/fish
+```
+
+`--install` appends a marker-guarded block to the right rc file (`~/.zshrc`, `~/.bashrc`, or `~/.config/fish/config.fish`) — re-source it once and you're done. Tab-completion suggests every subcommand, and slugs for the commands that take one (`cd`, `clone`, `open`, …).
+
+### Inspect the config
+
+```bash
+forgemap config init                 # write a starter forgemap.config.ts
+forgemap config show                 # print the resolved config + which file it came from
+```
+
 ## ⚙️ Configuration
 
 `forgemap config init` writes a `forgemap.config.ts` like this:
@@ -153,7 +201,10 @@ export default defineForgeMapConfig({
 | `forges.<name>.dir`  | Subdirectory under `root` where this forge's clones live.                                                 |
 | `forges.<name>.protocol` | `git`-type only. `'ssh'` (default) or `'https'`. Override per call with `--ssh` / `--https`.          |
 
-The config file is discovered by walking up from your current directory. Override with `--config <path>` or the `FORGEMAP_CONFIG` env var.
+The config file is discovered by walking **up** from your current directory (so `forgemap cd` works from inside any clone, not just the root), then falling back to a global `$XDG_CONFIG_HOME/forgemap/forgemap.config.*` (i.e. `~/.config/forgemap/`) so commands work from anywhere. Override with `--config <path>` or the `FORGEMAP_CONFIG` env var.
+
+> [!TIP]
+> Already have a directory full of repos? Skip writing this by hand — `forgemap import <path>` derives `root` + `forges` from the existing layout.
 
 ## 🗂️ Layout