chore: use NPM trusted publishing with semver tag triggers

[Copilot]

This PR adds an automated NPM publishing workflow that leverages GitHub's trusted publishing feature to securely publish the Koa package whenever a semantic versioning tag is pushed.

Overview

The new .github/workflows/npm-publish.yml workflow automates the release process with enhanced security through NPM provenance, ensuring packages are verifiably linked to their source code.

Key Features

🏷️ Semver Tag Triggers

The workflow triggers only when tags matching semantic versioning format are pushed:

• Standard versions: v1.0.0, v2.10.15
• Pre-releases: v3.0.0-alpha, v3.0.0-beta.1
• Release candidates: v4.0.0-rc.2

Tags without the v prefix, incomplete versions (e.g., v1.0), or non-semver formats are ignored.

🔐 NPM Trusted Publishing

Implements NPM's trusted publishing with provenance:

• --provenance flag: Generates cryptographic attestations linking the published package to the GitHub repository and specific commit
• OIDC authentication: Uses GitHub's OpenID Connect provider instead of long-lived tokens, reducing security risks
• Supply chain transparency: Allows users to verify package authenticity and build provenance

✅ Quality Gates

Before publishing, the workflow automatically:

1. Runs the linter (npm run lint)
2. Executes the full test suite (npm test)
3. Only publishes if all checks pass

This ensures only quality-validated releases reach NPM.

🛠️ Best Practices

• Uses npm ci for reproducible, consistent builds
• Runs on Node.js 20.x LTS
• Uses latest stable GitHub Actions (v4)
• Includes comprehensive inline documentation

Setup Requirements

To use this workflow, repository maintainers need to:

1. Add NPM token to GitHub Secrets

   • Navigate to Settings → Secrets and variables → Actions
   • Create a new secret named NPM_TOKEN with your NPM automation token

2. Configure NPM account for trusted publishing

   • Ensure the NPM account has access to publish the package
   • Verify the package is configured for public access (or remove --access public from the workflow)

Usage

To publish a new version:

# Create a semver tag
git tag v3.0.2
git push origin v3.0.2

The workflow will automatically:

• Trigger on tag push
• Run quality checks
• Publish to NPM with provenance
• Generate attestations linking the package to this repository

Technical Details

The workflow uses three tag patterns to cover common semver formats while working within GitHub Actions' glob pattern limitations:

1. v[0-9]+.[0-9]+.[0-9]+ - Standard semver (v1.0.0)
2. v[0-9]+.[0-9]+.[0-9]+-[a-zA-Z0-9]+ - Pre-release (v1.0.0-alpha)
3. v[0-9]+.[0-9]+.[0-9]+-[a-zA-Z0-9]+.[0-9]+ - Pre-release with number (v1.0.0-beta.1)

Permissions are configured for trusted publishing:

• contents: read - Access repository code
• id-token: write - Generate OIDC tokens for NPM authentication

This implementation enhances the project's release automation while improving security and supply chain transparency for all Koa users.

Original prompt

Create a github action workflow that uses npm trusted publish and triggers this workflow only when a tag is created and the tag name meets the semver format.

---

💬 Share your feedback on Copilot coding agent for the chance to win a $200 gift card! Click here to start the survey.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 99.90%. Comparing base (83128eb) to head (d0e1411).
⚠️ Report is 1 commits behind head on master.

Additional details and impacted files

@@           Coverage Diff           @@
##           master    #1907   +/-   ##
=======================================
  Coverage   99.90%   99.90%           
=======================================
  Files           9        9           
  Lines        2066     2066           
=======================================
  Hits         2064     2064           
  Misses          2        2           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.