feat(cli): bundle the v0.4.0 base spec and release a minor version

[SnowboardTechie]

Summary

• Fixes [CLI] Include the v0.4.0 base spec #1052
• Time to review: 5 minutes

Changes proposed

• Add a minor changeset for @common-grants/cli (0.3.9 → 0.4.0) announcing that the v0.4.0 base spec is bundled and selectable via cg check spec --protocol-version 0.4.0, and that a bare cg check spec now resolves to it.
• Parameterize the protocolVersion accept cases over every bundled version. This adds 0.4.0, closes a pre-existing gap where 0.3.0 had no coverage at all, and replaces three copy-pasted blocks with one.
• Refresh the stale --protocol-version examples in the CLI README (0.1.0) and man page (0.2.0) to 0.4.0.

No source changes. getAvailableBaseVersions() already discovers versions by scanning lib/openapi/ at runtime, so 0.4.0 became selectable the moment the spec file landed.

Context for reviewers

Why this is a release rather than a code change. lib/cli/lib/openapi/openapi.0.4.0.yaml reached main in d4293de, the chore: bump version [skip ci] commit for the core v0.4.0 release — not in a reviewed PR. ci-bump-version.yml runs pnpm --filter @common-grants/cli run build before versioning; the CLI's typespec:clean does rm -rf lib/openapi/* and typespec:openapi regenerates every version core declares, and the workflow then commits with git add ..

Two consequences worth knowing:

1. The v0.4.0 spec has been shipping since @common-grants/cli@0.3.7 with nothing in the CLI changelog. I confirmed it is in the published 0.3.9 tarball and that cg check spec --protocol-version 0.4.0 works against it today.
2. Because getBaseSpecPath() takes availableVersions[0], the default base spec silently moved from 0.3.0 to 0.4.0 in that same patch release.

The default flip is benign: every route 0.4.0 adds (Awards, Organizations) is tagged experimental, and the only required-tagged routes remain the two /common-grants/opportunities GETs. I verified a 0.3.0-compliant spec still passes against the 0.4.0 base. The changeset documents both facts so the 0.4.0 changelog entry is accurate.

About the test. The version list is a literal rather than availableVersions, deliberately — iterating the live list would be self-referential, since a dropped spec file would just shrink the loop and pass silently. As written, each version is pinned: deleting openapi.0.1.0.yaml, openapi.0.3.0.yaml, or openapi.0.4.0.yaml fails that version's own named case, and hardcoding the protocolVersion enum away from availableVersions fails too. I confirmed each by mutation. This matters because every CLI build wipes and regenerates lib/openapi/.

Verification. Full ci-lib-cli.yml gate green locally (core build → cli checks → test:coverage (121 passed) → cli build → pnpm audit). Also: after run build, git status lib/cli/lib/openapi/ is clean, so the four committed specs are byte-for-byte what core 0.4.0 emits.

Packed the CLI and installed it into a scratch directory outside the repo, per the DEVELOPMENT.md pre-release checklist. Against the installed package: --protocol-version 0.4.0 validates, no-flag validates (default resolves to 0.4.0), --protocol-version 0.3.0 still validates, and a bad version reports expected one of "0.4.0"|"0.3.0"|"0.2.0"|"0.1.0".

One incidental note: npm pack fails repo-wide right now (must not have multiple workspaces with the same name) because lib/changelog-emitter's build copies its package.json into dist/. pnpm pack works. Not touched here since it is unrelated to this change, but the DEVELOPMENT.md checklist still says npm pack.

Additional information

Post-merge, ci-bump-version.yml bumps 0.3.9 → 0.4.0 and pushes tag @common-grants/cli@0.4.0; cd-deploy-lib-cli.yml then needs a manual trigger with that tag to publish.

[widal001]

Thanks for making these updates!