forgemap 0.4.1-dev-main.74-6f280f6 → 0.4.1-dev-main.86-4ebe4b0

package/README.md

@@ -27,11 +27,11 @@ 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/)).
+- **🔍 Fuzzy search** — `forgemap search <term>` finds local repos 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.
@@ -56,7 +56,7 @@ forgemap cd laravel                      # fuzzy match → jump in; bare `forgem
 `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.
 
 <details>
-<summary><strong>All commands</strong> — clone, cd, search, open, sync/status, import, cleanup, delete, validate, shell-init, config</summary>
+<summary><strong>All commands</strong> — clone, cd, path, search, pick, open, sync/status, import, cleanup, delete, validate, shell-init, config</summary>
 
 ### Clone & jump
 
@@ -71,6 +71,17 @@ forgemap cd kirch                        # multiple matches → interactive pick
 forgemap cd                              # no arg → picker over every clone
 ```
 
+### Print a path — `path`
+
+```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.
+
 ### Search and pick on demand
 
 ```bash
@@ -103,10 +114,14 @@ 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
 ```
 
 `--filter` works on `status`, `sync` and `search`. 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`, `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`