refactor: replace prepublishOnly with explicit publish workflow (#46)

Co-authored-by: Claude Sonnet 4.5 <noreply@anthropic.com>

Author: roottool

.github/workflows/publish.yml

@@ -38,6 +38,9 @@ jobs:
       - name: Initialize
         uses: ./.github/actions/setup-environment
 
+      - name: Validate and build package
+        run: bun run prepare:publish
+
       - name: Setup Node.js
         uses: actions/setup-node@395ad3262231945c25e8478fd5baf05154b1d79f # v6.1.0
         with:

CONTRIBUTING.md

@@ -92,6 +92,12 @@ bun run test         # All tests must pass
 bun run build        # Build must succeed
 ```
 
+For local validation before pushing (mimics publish workflow):
+
+```bash
+bun run prepare:publish     # Runs all checks: type checking, tests, build, package validation
+```
+
 ### 3. Testing
 
 - Write tests for all new functionality

README.md

@@ -252,6 +252,13 @@ export interface ParseIssue {
 v0.x focuses exclusively on establishing and clarifying the FormData boundary.
 No inference or convenience features will be added within v0.x.
 
+## Contributing
+
+Contributions are welcome! Please see:
+
+- [CONTRIBUTING.md](CONTRIBUTING.md) - Contributor guide
+- [docs/PUBLISHING.md](docs/PUBLISHING.md) - Publishing guide (for maintainers)
+
 ## License
 
 MIT

docs/PUBLISHING.md

@@ -0,0 +1,79 @@
+# Publishing Process
+
+> **For Maintainers**: This guide describes the NPM publishing workflow for safe-formdata.
+
+safe-formdata uses an explicit, transparent publishing workflow that aligns with the library's design principles.
+
+## Table of Contents
+
+- [Local Validation](#local-validation)
+- [Workflow Overview](#workflow-overview)
+- [Why prepublishOnly was removed](#why-prepublishonly-was-removed)
+
+---
+
+## Local Validation
+
+Before creating a release PR, validate locally:
+
+```bash
+bun run prepare:publish
+```
+
+This runs:
+
+1. TypeScript type checking (`check:type:source`)
+2. Test suite with coverage (`test:coverage`)
+3. Build (`build`)
+4. Package validation (`check:package`: publint + attw)
+
+---
+
+## Workflow Overview
+
+1. **Prepare Release PR**: Bump version → Create release branch → Open PR for review
+2. **Review & Merge**: Maintainer reviews and merges release PR to main
+3. **Publish**: Manual trigger of publish workflow → All checks run → NPM publish
+
+The publish workflow is defined in `.github/workflows/publish.yml` and runs the following steps:
+
+1. Setup environment (Bun + dependencies)
+2. **Validate and build package** (`bun run prepare:publish`)
+3. Setup Node.js for NPM
+4. Publish to NPM with provenance
+5. Create and push git tag
+6. Create GitHub Release (draft)
+
+---
+
+## Why prepublishOnly was removed
+
+Previous versions used `npm run prepublishOnly` in package.json, which ran automatically during `npm publish`.
+This violated the boundary principle: **explicit over implicit**.
+
+The publish workflow now declares all validation steps explicitly:
+
+- TypeScript type checking
+- Test execution
+- Build process
+- Package validation
+- NPM publication
+
+This ensures the publishing process is **transparent** and **traceable** in the workflow file.
+
+### Design principles alignment
+
+| Principle                     | Implementation                                                                      |
+| ----------------------------- | ----------------------------------------------------------------------------------- |
+| **Explicit over implicit**    | `prepare:publish` is called explicitly in the workflow, not triggered automatically |
+| **Security over convenience** | All validation steps are visible and traceable                                      |
+| **Boundary-focused**          | Clear separation between development and publishing processes                       |
+| **No silent fixes**           | No hidden automation; every step is declared                                        |
+
+---
+
+## Related Files
+
+- [`.github/workflows/publish.yml`](../.github/workflows/publish.yml) - Publish workflow implementation
+- [`package.json`](../package.json) - Package configuration and scripts
+- [`CONTRIBUTING.md`](../CONTRIBUTING.md) - Contributor guide

package.json

@@ -57,7 +57,7 @@
 		"test:coverage": "vitest run --coverage",
 		"build": "tsup",
 		"check:package": "publint && attw --pack . --ignore-rules cjs-resolves-to-esm",
-		"prepublishOnly": "bun run check:type:source && bun run test:coverage && bun run build && bun run check:package"
+		"prepare:publish": "npm-run-all2 check:type:source test:coverage build check:package"
 	},
 	"devDependencies": {
 		"@arethetypeswrong/cli": "0.18.2",