[stackbilt-admin]

Closes #366

Problem

Since #365, the generated pre-commit hook runs npx charter doctor --adf-only --ci --staged … before <pm> run verify:adf. It has always run npx charter for tidy and adf evidence too.

Under Yarn Plug'n'Play there is no node_modules/.bin, so npx misses the installed CLI and falls back to the unrelated registry package charter (0.0.2, which has no bin). The gate fails before yarn run verify:adf runs. In any repo without Charter installed, the same fallback fetches that package.

Fix (scope: the pre-commit hook only)

Package manager, picked once per hook run

HOOK_CLI_RESOLVE_BLOCK takes the first candidate whose marker exists and whose binary is on PATH. This is #365's cascade with PnP in front:

1. Yarn Plug'n'Play: .pnp.cjs, .pnp.js, or .yarnrc.yml with nodeLinker: pnp → yarn
2. pnpm-lock.yaml → pnpm
3. yarn.lock → yarn
4. npm otherwise

If the first marker it finds has no binary on PATH, the hook warns and names the runner it uses instead. Under PnP the warning adds corepack enable.

How Charter runs

charter_cli runs exactly $CHARTER_RUN, and every Run: hint prints that same command. The strings come from HOOK_CLI_COMMANDS. "Local" means node_modules/.bin/charter or charter.cmd exists; "global" means a charter on PATH.

Package manager	Local	Global only	Neither
Yarn PnP	yarn charter	yarn charter (no fallback: there is no node_modules to check)	yarn charter
Yarn, node_modules linker	yarn charter (yarn --silent charter on Yarn 1)	charter, run directly	nothing
pnpm	pnpm exec charter	pnpm exec charter (it searches PATH)	nothing
npm	npm exec --no --no-update-notifier --fetch-retries=0 -- @stackbilt/cli	charter, run directly	nothing

"Nothing" means the hook calls neither Charter nor the package manager. It prints the devDependency hint once, skips tidy, and fails the gate. It prints no Run: command, since none would work.

One --version probe per commit

HOOK_CLI_PROBE_BLOCK runs once, before any other Charter call, and keeps stderr.

• Not resolvable (no binary found, or exit 127): the devDependency hint, once.
• A binary exists but --version fails: Charter is installed but failed to run: plus the first error line. No devDependency hint.
• Output without charter v<digit>: a warning that the charter found is not @stackbilt/cli, and nothing else runs.
• charter v0.x / v1.x: one warning to "Upgrade @stackbilt/cli to 2.x (as a devDependency, or your global install)". charter v10.0.0 is not flagged.
• A doctor that ran and reported findings: no hint.

Network and timing

The hook never installs a package and never runs a downloaded one. The only network use left is Corepack downloading Yarn or pnpm on first use.

Measured offline, with npm 11.17, the registry at 127.0.0.1:9, a real @stackbilt/cli@2.1.0 and a real hook run:

Setup	Time	Registry requests	Result
Local install	6-7 s	none	doctor ran and reported a finding; no hint
No install at all	0 s	none	hint once, no Run: line
Global charter v1.9.3 only	2 s	none	one upgrade warning

Tidy notes

Tidy's dry-run stderr is now kept. A note about a staged file it leaves alone (an unmanaged CLAUDE.md, verified against the real CLI) is shown under [pre-commit] adf tidy notes:. In that case, and when the dry run fails, the hook no longer prints "Vendor config files are clean."

This was a pre-existing bug. It is fixed in the shared template and in the repo's own .githooks/pre-commit.

Other changes

• PnP detection has one source: PNP_MARKER_FILES and YARNRC_PNP_LINKER_ERE. The JS form, yarnrcPnpLinkerRegExp(), uses [ \t\r\f\v], so like grep it never matches across a newline.
• charter doctor reports a pre-hook: pre-commit gate fails under Yarn Plug'n'Play (npx charter can't resolve the PnP binary) #366 hook as INFO in PnP repos.
• hook --help lists the cascade, the commands, and how global installs are handled.
• Unchanged: the CHARTER_HOOK_SCOPED_DOCTOR token flow and setup.ts. The CI workflow is fixed separately in Generated CI workflow still runs bare npx charter (breaks under Yarn PnP / without a local install) #380 / fix(setup): run Charter through the package manager in the generated workflow (#380) #388.

Existing installs

Installed hooks do not update themselves. Re-run charter hook install --pre-commit. It is required under Yarn PnP and recommended everywhere else. The CHANGELOG, docs/cli-reference.md and docs/upgrading-to-2.0.md say so.

Tests

• hook-pm.test.ts runs the real hook under sh, with stubs for yarn, pnpm, npx, npm and charter on PATH that record their argv. No network. It covers:
  • the cascade, including PnP plus pnpm-lock, and both lockfiles with only yarn installed;
  • .pnp.cjs and .pnp.js alone, plus two mutation tests;
  • local, global and neither for npm, non-PnP Yarn and pnpm;
  • Yarn PnP never using a global install;
  • one probe per commit;
  • the broken, foreign and 1.x cases, and v10 / v2 / v3-beta not being flagged;
  • an unresolved CLI, which gets no Run: line;
  • Run: lines matching the command that actually ran;
  • tidy notes, and no "clean" message after a failed dry run;
  • hook grep and the JS regex agreeing on 15 inputs.
• doctor-pnp-source.test.ts mocks the hook module's PnP exports, so a doctor that hard-codes detection fails.
• hook.test.ts covers the doctor rows. integration/precommit-hook.test.ts redefines charter_cli ahead of the probe.
• Full serial suite, after merging main e55afd7: 1893 passed. The 3 failures are the known Windows-only path-separator cases (bootstrap bootstrap: phases 6/7 collect warnings without printing them; absoluteAiDirArg misses Windows paths on POSIX #307, context-refresh, serve-context).

🤖 Generated with Claude Code