🔧 update publish workflow and add comprehensive publishing guide

Author: gwenoleR

.github/workflows/publish.yml

@@ -9,26 +9,26 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      
+
       - name: Setup Node.js
         uses: actions/setup-node@v4
         with:
           node-version: '18.x'
           registry-url: 'https://registry.npmjs.org'
-      
+
       - name: Install dependencies
         run: npm install
-      
+
       - name: Run checks
         run: |
           npm run typecheck
           npm run lint
           npm run format:check
-      
+
       - name: Build
         run: npm run build
-      
+
       - name: Publish
         run: npm publish --access public
         env:
-          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

PUBLISHING.md

@@ -0,0 +1,277 @@
+# Publishing Guide for slskd-client
+
+This guide explains how to publish the `slskd-client` package to npm.
+
+## Prerequisites
+
+1. **npm account**: Create one at [npmjs.com](https://www.npmjs.com/signup)
+2. **npm CLI login**: Run `npm login` in your terminal
+3. **Git repository**: Push your code to GitHub first
+
+## Pre-Publishing Checklist
+
+### 1. Update package.json
+
+Replace the placeholder URLs with your actual GitHub repository:
+
+```json
+{
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/YOUR_USERNAME/slskd-client.git"
+  },
+  "bugs": {
+    "url": "https://github.com/YOUR_USERNAME/slskd-client/issues"
+  },
+  "homepage": "https://github.com/YOUR_USERNAME/slskd-client#readme"
+}
+```
+
+### 2. Verify package name availability
+
+Check if the name `slskd-client` is available:
+
+```bash
+npm view slskd-client
+```
+
+If the package exists, you'll need to either:
+
+- Use a scoped package: `@your-username/slskd-client`
+- Choose a different name
+
+To use a scoped package, update `package.json`:
+
+```json
+{
+  "name": "@your-username/slskd-client"
+}
+```
+
+### 3. Build and test locally
+
+```bash
+# Install dependencies
+npm install
+
+# Run all checks
+npm run typecheck
+npm run lint
+npm run format:check
+npm run build
+
+# Verify the build output
+ls -la dist/
+```
+
+### 4. Test the package locally
+
+```bash
+# Create a test tarball
+npm pack
+
+# This creates a file like slskd-client-1.0.0.tgz
+# Install it in a test project:
+cd /path/to/test-project
+npm install /path/to/slskd-js-client/slskd-client-1.0.0.tgz
+```
+
+## Publishing Steps
+
+### First-time Publishing
+
+1. **Login to npm**:
+
+```bash
+npm login
+```
+
+2. **Verify you're logged in**:
+
+```bash
+npm whoami
+```
+
+3. **Publish the package**:
+
+```bash
+# For public package (free)
+npm publish --access public
+
+# For scoped package
+npm publish --access public
+```
+
+### Subsequent Updates
+
+1. **Update the version** in `package.json`:
+
+```bash
+# Patch version (1.0.0 -> 1.0.1)
+npm version patch
+
+# Minor version (1.0.0 -> 1.1.0)
+npm version minor
+
+# Major version (1.0.0 -> 2.0.0)
+npm version major
+```
+
+This will:
+
+- Update `package.json`
+- Create a git tag
+- Commit the changes
+
+2. **Push the changes**:
+
+```bash
+git push origin main --tags
+```
+
+3. **Publish**:
+
+```bash
+npm publish
+```
+
+## Automated Publishing with GitHub Actions (Optional)
+
+Create `.github/workflows/publish.yml`:
+
+```yaml
+name: Publish to npm
+
+on:
+  release:
+    types: [created]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '18.x'
+          registry-url: 'https://registry.npmjs.org'
+
+      - name: Install dependencies
+        run: npm install
+
+      - name: Run checks
+        run: |
+          npm run typecheck
+          npm run lint
+          npm run format:check
+
+      - name: Build
+        run: npm run build
+
+      - name: Publish
+        run: npm publish --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+```
+
+To use this:
+
+1. Generate an npm access token at [npmjs.com/settings/tokens](https://www.npmjs.com/settings/tokens)
+2. Add it as a secret `NPM_TOKEN` in your GitHub repository settings
+3. Create a GitHub release, and the package will be published automatically
+
+## What Gets Published
+
+The `files` field in `package.json` controls what's included:
+
+```json
+{
+  "files": ["dist", "README.md", "LICENSE"]
+}
+```
+
+Everything else is excluded via `.npmignore`.
+
+## Verify Publication
+
+After publishing, check:
+
+1. **npm registry**: Visit `https://www.npmjs.com/package/slskd-client`
+2. **Install test**:
+
+```bash
+npm install slskd-client
+```
+
+## Unpublishing (Emergency Only)
+
+If you need to unpublish within 72 hours:
+
+```bash
+npm unpublish slskd-client@1.0.0
+```
+
+⚠️ **Warning**: Unpublishing is permanent and not recommended. Consider deprecating instead:
+
+```bash
+npm deprecate slskd-client@1.0.0 "This version has critical bugs, use 1.0.1+"
+```
+
+## Common Issues
+
+### "You do not have permission to publish"
+
+- Check if the package name is already taken
+- Use a scoped package: `@username/slskd-client`
+- Verify you're logged in: `npm whoami`
+
+### "Package name too similar to existing package"
+
+- Choose a more unique name
+- Use a scoped package
+
+### "No README data"
+
+- Ensure `README.md` is in the `files` array in `package.json`
+
+## Post-Publishing
+
+1. **Add badges to README**:
+
+```markdown
+[![npm version](https://badge.fury.io/js/slskd-client.svg)](https://www.npmjs.com/package/slskd-client)
+[![npm downloads](https://img.shields.io/npm/dm/slskd-client.svg)](https://www.npmjs.com/package/slskd-client)
+```
+
+2. **Update CHANGELOG.md** for each release
+
+3. **Monitor issues** on GitHub and npm
+
+## Quick Reference
+
+```bash
+# Check current version
+npm version
+
+# Login
+npm login
+
+# Test build
+npm run build && npm pack
+
+# Publish (patch update)
+npm version patch
+git push origin main --tags
+npm publish
+
+# Check publication
+npm view slskd-client
+```
+
+## Resources
+
+- [npm Documentation](https://docs.npmjs.com/packages-and-modules/contributing-packages-to-the-registry)
+- [npm Publishing Guide](https://docs.npmjs.com/cli/v10/commands/npm-publish)
+- [Semantic Versioning](https://semver.org/)