chore(ci): harden release pipeline and CLI artifact validation

[dubscode]

Summary

• switch from split release/publish to an atomic semantic-release workflow on main
• add release concurrency and token wiring for GitHub + npm publishing
• add built CLI integration tests and include them in the quality gate
• enforce commitlint via husky commit-msg hook (required scope)
• expand docs and clarify consumer vs repo-development CLI invocation

Key Changes

• Added workflows:
  • .github/workflows/pr-quality.yml
  • .github/workflows/release.yml
• Added release/commit tooling:
  • .releaserc.json
  • CHANGELOG.md
  • commitlint.config.cjs
  • .husky/commit-msg
• Added CLI dist tests:
  • tests/cli/cli.dist.test.ts
  • vitest.cli-dist.config.ts
• Updated:
  • package.json scripts/deps (quality, test:cli:dist, release:dry-run --no-ci)
  • README.md and docs/usage/*

Validation

• pnpm run quality
• commitlint sample pass: feat(cli): add help output
• commitlint sample fail: feat: missing scope
• pnpm run release:dry-run on feature branch confirms plugin chain loads; no publish occurs off main

[Copilot]

Pull request overview

This PR hardens the project’s CI/release pipeline and adds a built-CLI artifact validation step, while expanding end-user usage documentation for the library and CLI.

Changes:

• Add an atomic semantic-release-driven release workflow (GitHub + npm) with concurrency control.
• Introduce built CLI dist integration tests and wire them into the PR quality gate.
• Add commit message enforcement via commitlint + husky, plus new/expanded usage docs.

Reviewed changes

Copilot reviewed 15 out of 17 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
vitest.cli-dist.config.ts	Adds a dedicated Vitest config for built-CLI dist tests.
tests/cli/cli.dist.test.ts	Validates the built CLI’s --help output and unknown-command behavior.
src/cli/index.ts	Improves CLI UX with help/suggestions after errors and a help subcommand.
package.json	Adds quality, test:cli:dist, semantic-release/commitlint/husky scripts and dev deps; splits Biome lint vs format checking.
pnpm-lock.yaml	Locks new dev dependencies (semantic-release, commitlint, husky, etc.).
docs/usage/cli.md	Adds CLI reference and invocation modes (consumer vs repo).
docs/usage/imports.md	Documents package imports and API surface areas.
docs/usage/environment.md	Documents validated env vars and example .env.
docs/usage/integration-recipes.md	Adds practical integration workflows/recipes.
README.md	Updates quickstart/docs links, clarifies CLI usage, adds commit convention notes.
commitlint.config.cjs	Enforces Conventional Commits with a required scope.
.husky/commit-msg	Runs commitlint on commit messages via husky hook.
CHANGELOG.md	Adds a changelog file for semantic-release to maintain.
.releaserc.json	Configures semantic-release plugins (changelog, npm, git, GitHub).
.github/workflows/release.yml	Adds main-branch release workflow with quality gate + semantic-release publish.
.github/workflows/pr-quality.yml	Adds PR quality workflow running lint/format/typecheck/tests/build/cli-dist tests.
.gitignore	Adds .dispatch ignore entry.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

You can also share your feedback on Copilot code review. Take the survey.