forgemap 0.1.0-dev.22-d31fc67 → 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 +62 -46
  2. package/dist/bin/forgemap.mjs +808 -54
  3. package/dist/bin/forgemap.mjs.map +1 -1
  4. package/package.json +2 -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,11 +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**
44
45
 
45
- > [!TIP]
46
- > 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.
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.
47
53
 
48
54
  ## 🚀 Quick start
49
55
 
@@ -52,43 +58,26 @@ pnpm add -g forgemap
52
58
  cd ~/projects
53
59
  forgemap config init
54
60
 
55
- # 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.
56
66
  forgemap clone kirchDev/laravel-pbac
57
67
  forgemap clone github:TitusKirch/forgemap
58
68
  forgemap clone https://github.com/foo/bar
59
69
 
60
- # 3. Jump into a repo from anywhere.
61
- cd "$(forgemap path kirchDev/laravel-pbac)"
62
- ```
63
-
64
- Add a shell alias to make the jump even shorter:
65
-
66
- ```bash
67
- fcd() { cd "$(forgemap path "$1")"; }
68
- 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
69
75
  ```
70
76
 
71
- ### Real `cd` via shell integration (recommended)
72
-
73
- Source the shell wrapper once:
74
-
75
- ```bash
76
- # zsh/bash — drop into ~/.zshrc or ~/.bashrc
77
- eval "$(forgemap shell-init)"
78
-
79
- # fish
80
- forgemap shell-init fish | source
81
- ```
82
-
83
- After that, `forgemap cd <slug>` actually changes directory:
84
-
85
- ```bash
86
- forgemap cd laravel # cd straight into kirchDev/laravel-pbac (single match)
87
- forgemap cd kirch # multiple matches → interactive picker
88
- forgemap cd # no arg → picker over every cloned repo
89
- ```
90
-
91
- 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.
92
81
 
93
82
  ### Search and pick on demand
94
83
 
@@ -109,6 +98,26 @@ forgemap open kirchDev/laravel-pbac
109
98
  - **macOS** → `open <path>` (Finder)
110
99
  - **Linux** → `xdg-open <path>`
111
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
+
112
121
  ## ⚙️ Configuration
113
122
 
114
123
  `forgemap config init` writes a `forgemap.config.ts` like this:
@@ -121,24 +130,28 @@ export default defineForgeMapConfig({
121
130
  defaultForge: 'github',
122
131
  forges: {
123
132
  github: {
124
- type: 'github',
133
+ type: 'github', // uses `gh repo clone`
125
134
  host: 'github.com',
126
135
  dir: 'comGithub'
127
136
  },
128
137
  work: {
129
- type: 'gitlab',
138
+ type: 'git', // plain `git clone` — no gh needed
130
139
  host: 'gitlab.acme.com',
131
- dir: 'comGitlabAcme'
140
+ dir: 'comGitlabAcme',
141
+ protocol: 'ssh' // optional, ssh is the default
132
142
  }
133
143
  }
134
144
  });
135
145
  ```
136
146
 
137
- | Key | What it controls |
138
- | :------------- | :---------------------------------------------------------------------------------------------- |
139
- | `root` | Base directory for all clones. Relative paths resolve against the config file's directory. |
140
- | `defaultForge` | Forge alias used when a slug is just `owner/repo` (no host or forge prefix). |
141
- | `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`. |
142
155
 
143
156
  The config file is discovered by walking up from your current directory. Override with `--config <path>` or the `FORGEMAP_CONFIG` env var.
144
157
 
@@ -180,8 +193,11 @@ pnpm install
180
193
  pnpm test # vitest
181
194
  pnpm typecheck # tsc --noEmit
182
195
  pnpm check # lint + format
196
+ pnpm bench # microbench scanRepos / cache hit / cache rebuild
183
197
  ```
184
198
 
199
+ Tune the bench layout via env vars (`FORGEMAP_BENCH_FORGES`, `FORGEMAP_BENCH_OWNERS`, `FORGEMAP_BENCH_REPOS`, `FORGEMAP_BENCH_RUNS`).
200
+
185
201
  ## 🤝 Contributing
186
202
 
187
203
  PRs welcome. Conventional Commits required (enforced via commitlint). Husky runs lint-staged on every commit.