docs(scaffolding): --package-manager accepts bun - #73
Merged
Conversation
The page carried a warning that the flag takes pnpm or npm only. connectum#246 adds `bun`, so that warning becomes false the moment it lands -- and it is the kind of statement a reader acts on, since it tells them to install by hand afterwards. Replaced with what is actually true and useful: the two flags are independent. `--package-manager` decides what installs and runs scripts, `--runtime` decides what executes the TypeScript, either accepts bun, and they need not agree. Both crossings have CI cells. The page already documents unreleased behaviour -- the published CLI 1.2.0 has only `proto`, no `init` -- so this ships in the same release as the flag.
12 tasks
intech
added a commit
to Connectum-Framework/connectum
that referenced
this pull request
Aug 5, 2026
…trix (#247) ## Summary Quality pass over #246, which merged while this was being prepared. Four independent reviews (reuse / simplification / efficiency / altitude) converged on the same defect: the by-name selection of bun cells survived in the script that owns the combination table. **The diff removes more than it adds — 30 insertions, 64 deletions.** ## Type of change - [ ] Bug fix (non-breaking) - [ ] New feature (non-breaking) - [ ] Breaking change (documented in migration guide) - [x] Documentation / chore / internal ## Test plan - [x] `pnpm build && pnpm typecheck && pnpm test` pass locally - [x] `pnpm lint` passes locally - [x] Relevant examples in `examples/` exercised (if applicable) — N/A, no example touched; instead both bun cells were run locally via `node scripts/scaffold-check.mjs --combo bun,bun-pm` (`bun` 19.6s ok, `bun-pm` 7.8s ok), which is the path this PR changes. - [x] **Negative-tested the replacement assertion**: deleting `"bun"` from `PACKAGE_MANAGERS` makes the new test fail (137 tests, 1 failure); restoring it passes. The test it replaces stayed green through that deletion. - [x] `node scripts/scaffold-check.mjs --list` output inspected — descriptors `{name, needsBun}` for all 10 combinations. - [x] Workflow YAML parsed; job names verified byte-identical (`init bun-pm`, …) so required checks in branch protection are unaffected. ## Parity coverage - [ ] Parity coverage added - [x] **Parity N/A** — this PR touches only build/CI tooling (`scripts/scaffold-check.mjs`, the scaffold-matrix workflow), one code comment, and unit tests. No server, transport, interceptor or protocol code is changed, so no observable RPC behaviour differs on either transport. ## Related issues / changes - Follows #246 (`--package-manager bun`), which merged before this pass was ready. - Companion docs change: Connectum-Framework/docs#73. --- ## Detail ### The by-name selection survived in the file that owns the table #246 removed `matrix.combo == 'bun'` from the workflow but left `COMBOS.filter(c => c.name === "bun")` in the script. So `scaffold-check --runtime bun` ran **one of the two** bun cells while CI ran both; `bun-pm` was reachable locally only by naming it explicitly. That breaks the guarantee the file's own header makes — that a green local run means a green CI run *by construction*. Both consumers now select on `needsBun` through a single derived `BUN_COMBOS`, and the singular wording in the help and error text is corrected. ### `--list` emits descriptors instead of names This removes more code than it adds: the `--list-needs-bun` mode, its flag, its help line, the second job output, the second `echo`, and the `contains(fromJSON(...))` expression all disappear. The condition becomes a plain `if: matrix.combo.needsBun`. It also closes a latent trap: had the `fromJSON` ever been dropped in an edit, `contains` would have degraded to a **substring** match, where `bun` also matches `bun-pm`. Measured, so nobody re-optimises it later: the two Node spawns this replaces cost **0.089s combined — 0.4% of the `discover` job**. This is a simplification, not a speed-up. ### The new test guarded the wrong invariant The README test passed a literal to `transformBase`, which never calls `resolveConfig` — so it pinned the **type union** while `--package-manager bun` actually depends on the **runtime array**. ### Also - Added the `concurrency` group every other workflow in this repo has — this one let superseded runs finish, ~370 job-seconds each. - Trimmed the buf-packaging archaeology from the `pnpm-workspace.yaml` comment (11 lines → 6). That detail goes stale exactly like the wrong comment #246 replaced. - Dropped the separate changeset: `connectum init` is unreleased and its own changeset already enumerates `bun`. ### Deliberately not done Deriving `PackageManager` from a const tuple. It closes a real gap — a union member forgotten in the validation array is accepted silently — but the same gap exists in **all five** option lists, and the current shape is the established pattern. Changing one of five trades a small hole for an inconsistency. Worth its own change. Two further recommendations were declined with reasons: folding `bun-pm` into the neighbouring cell (would reintroduce by-name selection to save 21 job-seconds) and turning `if (packageManager === "pnpm")` into a capability table (the altitude review itself concluded the current depth is right).
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Companion to Connectum-Framework/connectum#246.
The drift this prevents
The page carries a warning I wrote earlier:
connectum#246 adds
bun, so that becomes false the moment it lands. It is also the kind of statement a reader acts on — it tells them to install by hand afterwards, which would now be needless work.What replaces it
The thing that is actually true and worth knowing: the two flags are independent.
--package-managerdecides what installs dependencies and runs scripts;--runtimedecides what executes your TypeScript. Either acceptsbun, and they do not have to agree —bun installlays out an ordinarynode_modules, so a bun-installed project runs on Node.js and an npm-installed one runs on Bun. Both crossings have CI cells (bunandbun-pmin the scaffold matrix).The flag table gains
buntoo.Sequencing
The page already documents unreleased behaviour — the published
@connectum/cli@1.2.0exposes onlyproto, with noinit— so this ships in the same release as the flag itself. Verified by installing the published package and running--help.