feat: initialize NPM package and add publishing workflow

Author: Spomky

.github/workflows/npm-publish.yml

@@ -0,0 +1,68 @@
+name: Publish NPM Package
+
+on:
+  push:
+    tags:
+      - 'v*.*.*'
+      - '[0-9]+.[0-9]+.[0-9]+'
+
+jobs:
+  publish-npm:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          registry-url: 'https://registry.npmjs.org'
+
+      - name: Extract version from tag
+        id: get_version
+        run: |
+          TAG_NAME="${GITHUB_REF#refs/tags/}"
+          # Remove 'v' prefix if present
+          VERSION="${TAG_NAME#v}"
+          echo "version=$VERSION" >> $GITHUB_OUTPUT
+          echo "Publishing version: $VERSION"
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run tests
+        run: npm test
+
+      - name: Update package version
+        working-directory: ./src/stimulus/assets
+        run: |
+          npm version ${{ steps.get_version.outputs.version }} --no-git-tag-version
+          echo "Updated package.json to version ${{ steps.get_version.outputs.version }}"
+
+      - name: Publish to NPM
+        working-directory: ./src/stimulus/assets
+        run: npm publish --provenance
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+
+      - name: Create GitHub Release
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const tag = context.ref.replace('refs/tags/', '');
+            const version = tag.replace(/^v/, '');
+
+            await github.rest.repos.createRelease({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              tag_name: tag,
+              name: `@web-auth/webauthn-stimulus v${version}`,
+              body: `Published version ${version} to NPM: https://www.npmjs.com/package/@web-auth/webauthn-stimulus/v/${version}`,
+              draft: false,
+              prerelease: version.includes('-')
+            });

src/stimulus/PUBLISHING.md

@@ -0,0 +1,121 @@
+# Publishing the NPM Package @web-auth/webauthn-stimulus
+
+## Automatic Publishing (Recommended)
+
+The package is automatically published to NPM when a Git tag is created. The GitHub Actions workflow triggers automatically.
+
+### Process:
+
+1. Create a Git tag with the version number:
+   ```bash
+   git tag 5.2.3
+   git push origin 5.2.3
+   ```
+
+2. The GitHub Actions workflow will:
+   - Detect the new tag
+   - Install dependencies
+   - Run tests
+   - Update the version in package.json
+   - Publish to NPM
+   - Create a GitHub release
+
+## Manual Publishing
+
+If you need to publish manually (e.g., for testing):
+
+### Prerequisites:
+- NPM account with write access to the `@web-auth/webauthn-stimulus` package
+- Configured NPM token or local NPM authentication
+
+### Steps:
+
+1. **Navigate to the project root:**
+   ```bash
+   cd /path/to/webauthn-framework
+   ```
+
+2. **Install dependencies:**
+   ```bash
+   npm ci
+   ```
+
+3. **Run tests:**
+   ```bash
+   # Tests must be run from the root because the project uses npm workspaces
+   npm test
+   # OR use castor (recommended):
+   # php castor.php js
+   ```
+
+4. **Update the version:**
+   ```bash
+   cd src/stimulus/assets
+   # Replace X.Y.Z with the desired version (must match the Git tag)
+   npm version X.Y.Z --no-git-tag-version
+   cd ../../..
+   ```
+
+5. **Log in to NPM (if necessary):**
+   ```bash
+   npm login
+   # OR with a token:
+   # export NPM_TOKEN=your-npm-token
+   # echo "//registry.npmjs.org/:_authToken=${NPM_TOKEN}" > ~/.npmrc
+   ```
+
+6. **Publish to NPM:**
+   ```bash
+   cd src/stimulus/assets
+   npm publish --access public
+   cd ../../..
+   ```
+
+7. **Verify the publication:**
+   ```bash
+   npm view @web-auth/webauthn-stimulus
+   ```
+
+### Important notes on workspaces:
+
+The project uses **npm workspaces**, so:
+- Development dependencies (Babel, Jest, etc.) are in the root `package.json`
+- Tests must be run from the root with `npm test`
+- The package itself is in `src/stimulus/assets/` and that's where you publish from
+
+### Test Publishing (dry-run):
+
+To test the publication without actually publishing:
+
+```bash
+cd src/stimulus/assets
+npm pack --dry-run
+```
+
+This will show what would be included in the package without publishing it.
+
+### Unpublish a Publication (within 72h):
+
+If you need to cancel a publication:
+
+```bash
+npm unpublish @web-auth/webauthn-stimulus@X.Y.Z
+```
+
+⚠️ **Warning**: This should only be used in case of a critical error.
+
+## Important Notes:
+
+- The version in `package.json` is `0.0.0-dev` by default
+- It is replaced by the tag version during publication
+- The package is published from `src/stimulus/assets/`
+- Only files listed in the `files` property of `package.json` are included
+- Tests must pass before publication (enforced by CI/CD)
+
+## Post-Publication Verification:
+
+1. Check on NPM: https://www.npmjs.com/package/@web-auth/webauthn-stimulus
+2. Test installation in a project:
+   ```bash
+   npm install @web-auth/webauthn-stimulus@X.Y.Z
+   ```