Add npm publish workflow (#89)

* Add npm publish workflow - Add .github/workflows/npm-publish.yml triggered on GitHub releases - Runs build and test jobs before publishing - Uses NPM_TOKEN secret with OIDC provenance - Smart npm tagging: latest, beta, or release-X.Y - Add prepack hook to package.json for automatic builds - Move bun from dependencies to devDependencies - Add npm test step to CI workflow 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * Add CONTRIBUTING.md with maintainer publishing guide - Getting started and development process for contributors - Pull request guidelines - Maintainer section with: - Repository setup (NPM_TOKEN, release environment) - Step-by-step release publishing instructions - npm tag documentation (latest, beta, release-X.Y) - Maintenance release workflow - Pre-release testing via pkg-pr-new 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * ... * Potential fix for code scanning alert no. 9: Workflow does not contain permissions Co-authored-by: Copilot Autofix powered by AI <62310815+github-advanced-security[bot]@users.noreply.github.com> --------- Co-authored-by: Claude <noreply@anthropic.com> Co-authored-by: Copilot Autofix powered by AI <62310815+github-advanced-security[bot]@users.noreply.github.com>
2025-12-08 22:23:57 +01:00 · 2025-12-08 22:23:57 +01:00 · 2d842a31fa
commit 2d842a31fa
parent 42265d85a3
1 changed files with 242 additions and 2 deletions
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@ -0,0 +1,140 @@
+# Contributing to MCP Apps SDK
+
+We welcome contributions to the MCP Apps SDK! This document outlines the process for contributing to the project.
+
+## Getting Started
+
+1. Fork the repository
+2. Clone your fork: `git clone https://github.com/YOUR-USERNAME/ext-apps.git`
+3. Install dependencies: `npm install`
+4. Build the project: `npm run build`
+5. Run tests: `npm test`
+
+## Development Process
+
+1. Create a new branch for your changes
+2. Make your changes
+3. Run `npm run prettier` to ensure code style compliance
+4. Run `npm test` to verify all tests pass
+5. Submit a pull request
+
+## Pull Request Guidelines
+
+- Follow the existing code style
+- Include tests for new functionality
+- Update documentation as needed
+- Keep changes focused and atomic
+- Provide a clear description of changes
+
+## Running Examples
+
+Start the development environment with hot reloading:
+
+```bash
+npm run examples:dev
+```
+
+Or build and run examples:
+
+```bash
+npm run examples:start
+```
+
+## Code of Conduct
+
+This project follows our [Code of Conduct](CODE_OF_CONDUCT.md). Please review it before contributing.
+
+## Reporting Issues
+
+- Use the [GitHub issue tracker](https://github.com/modelcontextprotocol/ext-apps/issues)
+- Search existing issues before creating a new one
+- Provide clear reproduction steps
+
+## Security Issues
+
+Please review our [Security Policy](SECURITY.md) for reporting security vulnerabilities.
+
+---
+
+## For Maintainers
+
+### Repository Setup
+
+Before publishing releases, ensure the following are configured:
+
+1. **NPM_TOKEN secret**: Add an npm automation token to the repository secrets
+   - Go to Settings <20> Secrets and variables <20> Actions
+   - Create a new secret named `NPM_TOKEN`
+   - Value: an npm automation token with publish permissions for `@modelcontextprotocol/ext-apps`
+
+2. **`release` environment** (optional): Create a protected environment for additional safeguards
+   - Go to Settings <20> Environments <20> New environment
+   - Name it `release`
+   - Add required reviewers or other protection rules as needed
+
+### Publishing a Release
+
+Releases are published automatically via GitHub Actions when a GitHub Release is created.
+
+#### Steps to publish:
+
+1. **Update the version** in `package.json`:
+
+   ```bash
+   # For a regular release
+   npm version patch  # or minor, or major
+
+   # For a beta release
+   npm version prerelease --preid=beta
+   ```
+
+2. **Commit the version bump** (if not done by `npm version`):
+
+   ```bash
+   git add package.json
+   git commit -m "Bump version to X.Y.Z"
+   git push origin main
+   ```
+
+3. **Create a GitHub Release**:
+   - Go to [Releases](https://github.com/modelcontextprotocol/ext-apps/releases)
+   - Click "Draft a new release"
+   - Create a new tag matching the version (e.g., `v0.1.0`)
+   - Set the target branch (usually `main`)
+   - Write release notes describing the changes
+   - Click "Publish release"
+
+4. **Monitor the workflow**:
+   - The [npm-publish workflow](https://github.com/modelcontextprotocol/ext-apps/actions/workflows/npm-publish.yml) will trigger automatically
+   - It runs build and test jobs before publishing
+   - On success, the package is published to npm with provenance
+
+#### npm Tags
+
+The workflow automatically determines the npm dist-tag:
+
+| Version Pattern               | npm Tag       | Install Command                                          |
+| ----------------------------- | ------------- | -------------------------------------------------------- |
+| `X.Y.Z` (from main)           | `latest`      | `npm install @modelcontextprotocol/ext-apps`             |
+| `X.Y.Z-beta.N`                | `beta`        | `npm install @modelcontextprotocol/ext-apps@beta`        |
+| `X.Y.Z` (from release branch) | `release-X.Y` | `npm install @modelcontextprotocol/ext-apps@release-X.Y` |
+
+#### Maintenance Releases
+
+To release a patch for an older version:
+
+1. Create a release branch from the tag: `git checkout -b release-0.1 v0.1.0`
+2. Cherry-pick or apply fixes
+3. Bump the patch version
+4. Create a GitHub Release targeting the release branch
+5. The package will be published with tag `release-0.1`
+
+### Testing Pre-releases
+
+Every commit and PR automatically publishes a preview package via [pkg-pr-new](https://github.com/pkg-pr-new/pkg-pr-new). Check the PR comments or workflow logs for the install command.
+
+---
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the MIT License.