fix(setup): run Charter through the package manager in the generated workflow (#380)

[stackbilt-admin]

Closes #380

Problem

The workflow that charter setup --ci github / charter bootstrap --ci github generates (getGithubWorkflow in setup.ts) runs Charter as a bare npx charter …. If @stackbilt/cli is not installed, charter resolves to the unrelated registry package (0.0.2, which has no bin).

Fix

New workflowCharterCommand(pm) in setup.ts, used for all six steps:

• pnpm: pnpm exec charter …
• npm: npm exec --no --package=@stackbilt/cli -- charter …
• Yarn: the template supports only npm and pnpm (detectPackageManager returns 'npm' | 'pnpm'), so I did not add Yarn support. A Yarn repo gets the npm form, as before.

Why this npm form

I tested each candidate for real with npm 10.8.2 (what Node 20 ships in CI) and npm 11.17.0, using a clean npm_config_prefix/npm_config_cache and no global Charter.

form	@stackbilt/cli installed locally	not installed
npx charter --version (old)	—	fetches charter, then could not determine executable to run
npx --no-install @stackbilt/cli --version	charter v2.1.0	npx canceled due to missing packages and no YES option, exit 1
npm exec --no -- @stackbilt/cli --version	charter v2.1.0	same refusal, exit 1
npm exec --no --package=@stackbilt/cli -- charter --version	charter v2.1.0	same refusal, exit 1

All three new forms behave the same. I picked the --package=… -- charter one for two reasons:

• --no-install is the deprecated spelling. npm 11 warns Unknown cli config "--install" when it is passed through npm exec.
• Doctor's gate-enforcement check (invokesCharterValidate in doctor-gate-enforcement.ts) looks for charter validate … --ci. @stackbilt/cli validate would not match, so doctor would warn that a repo using the generated workflow has no CI gate. This form keeps charter validate in the step, and doctor-gate-enforcement.ts (being changed in fix(hook): resolve Charter through the repo package manager in the pre-commit hook (#366) #379) stays untouched.

setup and bootstrap add @stackbilt/cli to devDependencies (not under --no-dependency-sync, nor without a root package.json), so the install step provides it. With no local CLI the npm form still queries the registry for @stackbilt/cli metadata before refusing, but installs and runs nothing.

Known-template table (#374)

• The new npm and pnpm templates are the current safe entries in KNOWN_WORKFLOWS.
• The previous current templates (003ec8d) are now historical entries. Permissions and triggers are unchanged, so they stay safe: true (silent refresh), with an accurate origin and a refreshChanges that says what the refresh changes.
• Both 003ec8d texts were added to fixtures/charter-governance-history.json with "safe": true.
• The guard tests check that a safe historical template matches the current one up to jobs: and differs from it only in how Charter is run. Unsafe ones are checked as before.
• The new entries' origin is #380 (the commit hash isn't known before merge), so the origin regex now also accepts #\d+.

#379 (#366, the hook) is not merged. Its package-manager logic is resolved at runtime in the hook's shell script, and there was no shared TS helper to reuse.

Tests

• setup.test.ts:
  • Every Charter run: line uses the package-manager form, and none uses npx.
  • checkGateEnforcement() returns PASS for the generated npm and pnpm workflows.
  • The existing assertions are updated.
• workflow-mcp-backup.test.ts: the known-list and fixture checks above, and silent-refresh tests through bootstrap --yes and setup for the 003ec8d npm and pnpm templates.
• Built CLI in a scratch dir: setup --ci github --yes writes npm exec --no --package=@stackbilt/cli -- charter … steps.
• Full suite run serially: 1765 pass. The 3 failures are the known Windows-only ones (bootstrap bootstrap: phases 6/7 collect warnings without printing them; absoluteAiDirArg misses Windows paths on POSIX #307, context-refresh, serve-context).

Docs: docs/ci-integration.md notes how the steps run Charter and that the previous template is refreshed silently.

🤖 Generated with Claude Code