forgemap 0.1.0-dev.21-66ff114 → 0.1.0-dev.23-9e4d2ae

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (4) hide show
  1. package/README.md +63 -44
  2. package/dist/bin/forgemap.mjs +808 -54
  3. package/dist/bin/forgemap.mjs.map +1 -1
  4. package/package.json +3 -1
package/README.md CHANGED
@@ -20,16 +20,18 @@ $ forgemap clone kirchDev/laravel-pbac
20
20
  ✔ Cloned kirchDev/laravel-pbac → ~/projects/comGithub/kirchDev/laravel-pbac
21
21
  ```
22
22
 
23
- That's it. Every repo lands at a predictable `<root>/<forge.dir>/<owner>/<repo>` path, and `forgemap path <slug>` gives you that path back for `cd "$(forgemap path …)"` from anywhere.
23
+ That's it. Every repo lands at a predictable `<root>/<forge.dir>/<owner>/<repo>` path, and `forgemap cd <slug>` jumps into any of them from anywhere — exact slug, fuzzy match, or interactive picker.
24
24
 
25
25
  ## ✨ Features
26
26
 
27
27
  - **🗂️ Predictable layout** — every clone goes to `<root>/<forge.dir>/<owner>/<repo>`, configured once.
28
28
  - **🚪 Flexible slug syntax** — `owner/repo`, `forge:owner/repo`, full HTTPS URLs, or SSH (`git@…:…`).
29
29
  - **🔍 Fuzzy search** — `forgemap search <term>` finds local repos by owner or repo name (powered by [Fuse.js](https://www.fusejs.io/)).
30
- - **🤖 Forge-aware** — uses `gh` for GitHub today; GitLab / Gitea / Codeberg adapters planned.
30
+ - **🤖 Forge-aware** — `type: 'github'` shells out to `gh`; `type: 'git'` uses plain `git clone` with no extra dependencies.
31
+ - **🔁 Mass sync + status** — `forgemap sync` fetches every clone in parallel, `forgemap status` shows branch / dirty / ahead / behind per repo.
32
+ - **🛡️ Preflight validate** — `forgemap validate` checks the config schema and required CLIs before you discover a problem mid-clone.
31
33
  - **🧰 Typed config** — `forgemap.config.ts` with `defineForgeMapConfig()` and walk-up discovery.
32
- - **🚀 Shell-friendly** — `forgemap path <slug>` is a pure resolver, perfect for `cd "$(…)"` aliases.
34
+ - **🚀 Shell-friendly** — `forgemap cd <slug>` (via `shell-init`) actually changes directory.
33
35
 
34
36
  ## 📦 Installation
35
37
 
@@ -39,8 +41,15 @@ npm install -g forgemap
39
41
  pnpm add -g forgemap
40
42
  ```
41
43
 
42
- > [!IMPORTANT]
43
- > `forgemap clone` shells out to the [GitHub CLI](https://cli.github.com/) (`gh`). Install it once and run `gh auth login` so cloning works against private repos.
44
+ **Requirements**
45
+
46
+ - Node 24+
47
+ - `git` on `PATH`
48
+ - [`gh`](https://cli.github.com/) (GitHub CLI) — only when a `type: 'github'` forge is configured
49
+
50
+ Run `forgemap validate` after setup for an exact rundown of what's needed for your config.
51
+
52
+ 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.
44
53
 
45
54
  ## 🚀 Quick start
46
55
 
@@ -49,43 +58,26 @@ pnpm add -g forgemap
49
58
  cd ~/projects
50
59
  forgemap config init
51
60
 
52
- # 2. Clone — any slug form works.
61
+ # 2. Wire up the shell integration once — adds real `forgemap cd`.
62
+ eval "$(forgemap shell-init)" # zsh/bash, add to ~/.zshrc to persist
63
+ # fish: forgemap shell-init fish | source
64
+
65
+ # 3. Clone — any slug form works.
53
66
  forgemap clone kirchDev/laravel-pbac
54
67
  forgemap clone github:TitusKirch/forgemap
55
68
  forgemap clone https://github.com/foo/bar
56
69
 
57
- # 3. Jump into a repo from anywhere.
58
- cd "$(forgemap path kirchDev/laravel-pbac)"
59
- ```
60
-
61
- Add a shell alias to make the jump even shorter:
62
-
63
- ```bash
64
- fcd() { cd "$(forgemap path "$1")"; }
65
- fcd kirchDev/laravel-pbac
70
+ # 4. Jump into a repo from anywhere.
71
+ forgemap cd kirchDev/laravel-pbac # exact slug → direct cd
72
+ forgemap cd laravel # fuzzy single match → direct cd
73
+ forgemap cd kirch # multiple matches → interactive picker
74
+ forgemap cd # no arg → picker over every clone
66
75
  ```
67
76
 
68
- ### Real `cd` via shell integration (recommended)
69
-
70
- Source the shell wrapper once:
71
-
72
- ```bash
73
- # zsh/bash — drop into ~/.zshrc or ~/.bashrc
74
- eval "$(forgemap shell-init)"
75
-
76
- # fish
77
- forgemap shell-init fish | source
78
- ```
79
-
80
- After that, `forgemap cd <slug>` actually changes directory:
81
-
82
- ```bash
83
- forgemap cd laravel # cd straight into kirchDev/laravel-pbac (single match)
84
- forgemap cd kirch # multiple matches → interactive picker
85
- forgemap cd # no arg → picker over every cloned repo
86
- ```
87
-
88
- All other `forgemap` subcommands pass through to the real binary unchanged.
77
+ `forgemap cd` resolves the slug, walks/picks across your cloned repos,
78
+ and actually changes directory because the shell wrapper from
79
+ `shell-init` intercepts it before the binary runs. Every other
80
+ subcommand falls through to the real binary unchanged.
89
81
 
90
82
  ### Search and pick on demand
91
83
 
@@ -106,6 +98,26 @@ forgemap open kirchDev/laravel-pbac
106
98
  - **macOS** → `open <path>` (Finder)
107
99
  - **Linux** → `xdg-open <path>`
108
100
 
101
+ ### Mass operations across every clone
102
+
103
+ ```bash
104
+ forgemap sync # git fetch --all --prune, 4 in parallel
105
+ forgemap sync --pull # git pull --ff-only (skips dirty trees)
106
+ forgemap sync --forge work --query api # restrict scope
107
+
108
+ forgemap status # tree: branch / dirty / ahead↑ / behind↓ / last commit
109
+ forgemap status --format json # structured for jq + scripts
110
+ ```
111
+
112
+ ### Preflight your config
113
+
114
+ ```bash
115
+ forgemap validate # pretty checklist with ✓ / ! / ✗ per check
116
+ forgemap validate --json | jq # machine-readable for pre-commit hooks
117
+ ```
118
+
119
+ 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.
120
+
109
121
  ## ⚙️ Configuration
110
122
 
111
123
  `forgemap config init` writes a `forgemap.config.ts` like this:
@@ -118,24 +130,28 @@ export default defineForgeMapConfig({
118
130
  defaultForge: 'github',
119
131
  forges: {
120
132
  github: {
121
- type: 'github',
133
+ type: 'github', // uses `gh repo clone`
122
134
  host: 'github.com',
123
135
  dir: 'comGithub'
124
136
  },
125
137
  work: {
126
- type: 'gitlab',
138
+ type: 'git', // plain `git clone` — no gh needed
127
139
  host: 'gitlab.acme.com',
128
- dir: 'comGitlabAcme'
140
+ dir: 'comGitlabAcme',
141
+ protocol: 'ssh' // optional, ssh is the default
129
142
  }
130
143
  }
131
144
  });
132
145
  ```
133
146
 
134
- | Key | What it controls |
135
- | :------------- | :---------------------------------------------------------------------------------------------- |
136
- | `root` | Base directory for all clones. Relative paths resolve against the config file's directory. |
137
- | `defaultForge` | Forge alias used when a slug is just `owner/repo` (no host or forge prefix). |
138
- | `forges.<name>` | Map of forge aliases. Each entry has `type`, `host`, and `dir` (subdirectory under `root`). |
147
+ | Key | What it controls |
148
+ | :------------------- | :-------------------------------------------------------------------------------------------------------- |
149
+ | `root` | Base directory for all clones. Relative paths resolve against the config file's directory. |
150
+ | `defaultForge` | Forge alias used when a slug is just `owner/repo` (no host or forge prefix). |
151
+ | `forges.<name>.type` | `'github'` (shells out to `gh`) or `'git'` (plain `git clone`). `gitlab` / `gitea` / `codeberg` reserved. |
152
+ | `forges.<name>.host` | Hostname used to map full URLs and (for `git`) build the clone URL. |
153
+ | `forges.<name>.dir` | Subdirectory under `root` where this forge's clones live. |
154
+ | `forges.<name>.protocol` | `git`-type only. `'ssh'` (default) or `'https'`. Override per call with `--ssh` / `--https`. |
139
155
 
140
156
  The config file is discovered by walking up from your current directory. Override with `--config <path>` or the `FORGEMAP_CONFIG` env var.
141
157
 
@@ -177,8 +193,11 @@ pnpm install
177
193
  pnpm test # vitest
178
194
  pnpm typecheck # tsc --noEmit
179
195
  pnpm check # lint + format
196
+ pnpm bench # microbench scanRepos / cache hit / cache rebuild
180
197
  ```
181
198
 
199
+ Tune the bench layout via env vars (`FORGEMAP_BENCH_FORGES`, `FORGEMAP_BENCH_OWNERS`, `FORGEMAP_BENCH_REPOS`, `FORGEMAP_BENCH_RUNS`).
200
+
182
201
  ## 🤝 Contributing
183
202
 
184
203
  PRs welcome. Conventional Commits required (enforced via commitlint). Husky runs lint-staged on every commit.