forgemap 0.4.1 → 0.5.0-dev-main.91-6fe192c

package/README.md

@@ -7,10 +7,11 @@
 [![npm Version](https://img.shields.io/npm/v/forgemap.svg?style=flat-square&color=4f46e5)](https://www.npmjs.com/package/forgemap)
 [![Downloads](https://img.shields.io/npm/dm/forgemap.svg?style=flat-square&color=4f46e5)](https://www.npmjs.com/package/forgemap)
 [![Tests](https://img.shields.io/github/actions/workflow/status/TitusKirch/forgemap/ci.yml?branch=main&style=flat-square&label=tests)](https://github.com/TitusKirch/forgemap/actions/workflows/ci.yml)
-[![Coverage](https://img.shields.io/codecov/c/github/TitusKirch/forgemap?style=flat-square&color=10b981)](https://codecov.io/gh/TitusKirch/forgemap)
 [![Node Version](https://img.shields.io/node/v/forgemap.svg?style=flat-square&color=8993be)](https://www.npmjs.com/package/forgemap)
 [![License: MIT](https://img.shields.io/npm/l/forgemap.svg?style=flat-square&color=10b981)](LICENSE)
 
+![forgemap demo](.github/assets/demo.gif)
+
 </div>
 
 ---
@@ -26,67 +27,67 @@ That's it. Every repo lands at a predictable `<root>/<forge.dir>/<owner>/<repo>`
 
 - **🗂️ Predictable layout** — every clone goes to `<root>/<forge.dir>/<owner>/<repo>`, configured once.
 - **🚪 Flexible slug syntax** — `owner/repo`, `forge:owner/repo`, full HTTPS URLs, or SSH (`git@…:…`).
-- **🔍 Fuzzy search** — `forgemap search <term>` finds local repos by owner or repo name (powered by [Fuse.js](https://www.fusejs.io/)).
+- **🔍 List & fuzzy search** — `forgemap list` shows every local repo, `forgemap list <term>` filters by owner or repo name (powered by [Fuse.js](https://www.fusejs.io/)); `cd`, `path` and `open` take the same fuzzy terms.
 - **🤖 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.
+- **🔁 Mass sync + status** — `forgemap sync` fetches every clone in parallel, `forgemap status` shows branch / dirty / ahead / behind per repo — narrow either to given owners or forges with a repeatable `--filter`.
 - **📥 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.
+- **🧹 Safe cleanup** — `forgemap cleanup` deletes long-idle clones, `forgemap delete <slug>` drops a single one — both only when it is clean, fully pushed, free of stashed work, and still on its 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()`, 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
+## 📦 Install & run
+
+> [!IMPORTANT]
+> Needs **Node 24+** and **`git`** on `PATH`. [`gh`](https://cli.github.com/) (GitHub CLI) is only required when a `type: 'github'` forge is configured — run `forgemap validate` for an exact rundown of what your config needs.
 
 ```bash
-npm install -g forgemap
-# or
-pnpm add -g forgemap
-```
+npm install -g forgemap   # or: pnpm add -g forgemap
 
-**Requirements**
+cd ~/projects                            # the directory that should hold all your repos
+forgemap config init                     # write a starter forgemap.config.ts
+forgemap shell-init --install            # cd wrapper + completion → your rc file (idempotent)
+source ~/.zshrc                          # re-source once, then it's automatic
 
-- Node 24+
-- `git` on `PATH`
-- [`gh`](https://cli.github.com/) (GitHub CLI) — only when a `type: 'github'` forge is configured
+forgemap clone kirchDev/laravel-pbac     # any slug form works: owner/repo, forge:owner/repo, URL, SSH
+forgemap cd laravel                      # fuzzy match → jump in; bare `forgemap cd` opens a picker
+```
 
-Run `forgemap validate` after setup for an exact rundown of what's needed for your config.
+`forgemap cd` resolves the slug, walks/picks across your cloned repos, and actually changes directory because the shell wrapper from `shell-init` intercepts it before the binary runs. Every other subcommand falls through to the real binary unchanged. Hacking on forgemap itself? See [CONTRIBUTING.md → Trying the CLI locally](CONTRIBUTING.md#trying-the-cli-locally) — covers `pnpm setup`, `pnpm link --global .` and the shell-wrapper source.
 
-Hacking on forgemap itself? See [CONTRIBUTING.md → Trying the CLI locally](CONTRIBUTING.md#trying-the-cli-locally) — covers `pnpm setup`, `pnpm link --global .` and the shell-wrapper source.
+<details>
+<summary><strong>All commands</strong> — clone, cd, path, list, pick, open, sync/status, import, cleanup, delete, validate, shell-init, config</summary>
 
-## 🚀 Quick start
+### Clone & jump
 
 ```bash
-# 1. Pick a directory that should hold all your repos and drop a config there.
-cd ~/projects
-forgemap config init
-
-# 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
+forgemap clone kirchDev/laravel-pbac     # default forge
 forgemap clone github:TitusKirch/forgemap
 forgemap clone https://github.com/foo/bar
 
-# 4. Jump into a repo from anywhere.
 forgemap cd kirchDev/laravel-pbac        # exact slug → direct cd
 forgemap cd laravel                      # fuzzy single match → direct cd
 forgemap cd kirch                        # multiple matches → interactive picker
 forgemap cd                              # no arg → picker over every clone
 ```
 
-`forgemap cd` resolves the slug, walks/picks across your cloned repos,
-and actually changes directory because the shell wrapper from
-`shell-init` intercepts it before the binary runs. Every other
-subcommand falls through to the real binary unchanged.
+### Print a path — `path`
 
-### Search and pick on demand
+```bash
+forgemap path kirchDev/laravel-pbac      # → ~/projects/comGithub/kirchDev/laravel-pbac
+forgemap path laravel                    # fuzzy single match → same path
+cd "$(forgemap path laravel)"            # the manual form of `forgemap cd`
+code "$(forgemap path forgemap)"         # feed any tool that takes a directory
+```
+
+Prints where a repo lives — or *would* live, if it isn't cloned yet, which makes it useful for scripting a clone target. An exact `owner/repo` never touches the disk, so a strict slug always wins over a fuzzy match; ambiguous fuzzy terms error with the candidate list rather than guessing.
+
+### List, search and pick on demand
 
 ```bash
-forgemap search forgemap            # pretty tree (one line per match)
-forgemap search forgemap | fzf      # pipe-friendly path output
+forgemap list                       # every repo as a pretty tree
+forgemap list forgemap              # pretty tree (one line per match)
+forgemap list forgemap | fzf        # pipe-friendly path output
 forgemap pick                       # interactive picker (consola prompt)
 forgemap pick kirch                 # picker pre-filtered by fuzzy query
 ```
@@ -94,7 +95,8 @@ forgemap pick kirch                 # picker pre-filtered by fuzzy query
 ### Open the folder in the OS file manager
 
 ```bash
-forgemap open kirchDev/laravel-pbac
+forgemap open kirchDev/laravel-pbac      # exact slug
+forgemap open laravel                    # fuzzy single match → same folder
 ```
 
 - **WSL** → launches `explorer.exe` against `\\wsl$\<distro>\…`, Explorer opens the folder
@@ -110,9 +112,18 @@ forgemap sync --forge work --query api  # restrict scope
 
 forgemap status                      # tree: branch / dirty / ahead↑ / behind↓ / last commit
 forgemap status --format json        # structured for jq + scripts
+
+# --filter keeps only matching owners/forges. Repeatable, OR-combined.
+forgemap status --format json --filter kirchDev --filter TitusKirch
+
+forgemap status --no-cache           # rescan the disk instead of using the cached tree
 ```
 
-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.
+`--filter` works on `status`, `sync` and `list`. It matches an **owner** or a **forge name** exactly (case-insensitive) — unlike `--query`, which is fuzzy.
+
+`status`, `sync` and `cleanup` read a cached repo tree so repeated runs stay fast. Pass `--no-cache` to skip it and walk the disk again — the cache refreshes on its own, so you only need this right after cloning or moving repos by hand.
+
+All tree output (`status`, `list`, `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`
 
@@ -134,10 +145,22 @@ For each repo `import` compares the folder's `<owner>/<repo>` against the git `o
 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!)
+forgemap cleanup --include-dirty --include-unpushed --include-stashed   # 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, has no stashed work, **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`).
+
+### Drop one repo — `delete`
+
+```bash
+forgemap delete kirchDev/laravel-pbac    # gates, then type "yes" to confirm
+forgemap delete github:foo/bar           # forge-qualified slug or full URL
+forgemap delete foo/bar --dry-run        # report the gates; never prompt or delete
+forgemap delete foo/bar --yes            # non-interactive (scripts)
+forgemap delete foo/bar --include-dirty --include-unpushed --include-stashed   # delete local-only work too (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`).
+The targeted counterpart to `cleanup`: same safety gates, no staleness requirement — for the repo you are done with *today*. It runs the identical checks (clean tree, nothing unpushed, no stashed work, remote still exists) and prints the local-only work at stake, naming the branches that carry unpushed commits and the stash count rather than just saying "unpushed". A gone or unreachable remote is a **hard stop that no flag overrides** — that local copy may be the only one left. After deleting, the repo is evicted from the scan cache and emptied owner directories are pruned.
 
 ### Preflight your config
 
@@ -154,6 +177,7 @@ Validates the schema, required CLI tools (`git` always, `gh` when a `type: 'gith
 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 shell-init fish | source    # fish: source the wrapper directly
 forgemap completion bash             # print the completion script for bash/zsh/fish
 ```
 
@@ -166,6 +190,8 @@ forgemap config init                 # write a starter forgemap.config.ts
 forgemap config show                 # print the resolved config + which file it came from
 ```
 
+</details>
+
 ## ⚙️ Configuration
 
 `forgemap config init` writes a `forgemap.config.ts` like this:
@@ -192,6 +218,14 @@ export default defineForgeMapConfig({
 });
 ```
 
+The config is discovered by walking **up** from your current directory (so `forgemap cd` works from inside any clone), then falling back to `~/.config/forgemap/`. 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.
+
+<details>
+<summary><strong>All configuration options</strong></summary>
+
 | Key                  | What it controls                                                                                          |
 | :------------------- | :-------------------------------------------------------------------------------------------------------- |
 | `root`               | Base directory for all clones. Relative paths resolve against the config file's directory.                |
@@ -203,10 +237,10 @@ export default defineForgeMapConfig({
 
 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.
+</details>
 
-## 🗂️ Layout
+<details>
+<summary><strong>Repo layout &amp; slug syntax</strong></summary>
 
 ```
 <root>/
@@ -227,8 +261,6 @@ Example with the default config rooted at `~/projects`:
         └── forgemap/
 ```
 
-## 🚪 Slug syntax
-
 | Form                                | Resolves to                                            |
 | :---------------------------------- | :----------------------------------------------------- |
 | `kirchDev/laravel-pbac`             | Default forge, `kirchDev/laravel-pbac`.                |
@@ -237,7 +269,14 @@ Example with the default config rooted at `~/projects`:
 | `https://github.com/foo/bar.git`    | Same, `.git` suffix stripped.                          |
 | `git@github.com:foo/bar.git`        | SSH form, host matched against `forges[].host`.        |
 
-## 🧪 Testing
+</details>
+
+## 🤝 Contributing
+
+PRs welcome. Conventional Commits required (enforced via commitlint); Husky runs lint-staged on every commit. Run `pnpm check:fix` before pushing — CI will catch what husky missed.
+
+<details>
+<summary><strong>Dev scripts</strong></summary>
 
 ```bash
 pnpm install
@@ -249,12 +288,7 @@ pnpm bench        # microbench scanRepos / cache hit / cache rebuild
 
 Tune the bench layout via env vars (`FORGEMAP_BENCH_FORGES`, `FORGEMAP_BENCH_OWNERS`, `FORGEMAP_BENCH_REPOS`, `FORGEMAP_BENCH_RUNS`).
 
-## 🤝 Contributing
-
-PRs welcome. Conventional Commits required (enforced via commitlint). Husky runs lint-staged on every commit.
-
-> [!TIP]
-> Run `pnpm check:fix` before pushing — CI will catch what husky missed.
+</details>
 
 ## 🛣️ Versioning