docs: migrate from Scalar to Docusaurus + OpenAPI

.github/workflows/docs-pages.yml

@@ -1,11 +1,11 @@
-name: Docs (Scalar)
+name: Docs (Docusaurus)
 
 on:
   push:
     branches:
       - main
     paths:
-      - "scalar/**"
+      - "website/**"
       - ".github/workflows/docs-pages.yml"
       - "docs/**"
       - "README.md"
@@ -30,6 +30,17 @@ jobs:
       - name: Checkout
         uses: actions/checkout@v4
 
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+
+      - name: Install docs dependencies
+        run: npm --prefix website ci
+
+      - name: Build docs
+        run: npm --prefix website run build
+
       - name: Setup Pages
         uses: actions/configure-pages@v5
         with:
@@ -38,7 +49,7 @@ jobs:
       - name: Upload Artifact
         uses: actions/upload-pages-artifact@v3
         with:
-          path: ./scalar
+          path: ./website/build
 
       - name: Deploy To GitHub Pages
         id: deployment

.github/workflows/docs-preview.yml

@@ -0,0 +1,89 @@
+name: Docs Preview
+
+on:
+  pull_request:
+    branches:
+      - main
+    paths:
+      - "website/**"
+      - "docs/**"
+      - ".github/workflows/docs-preview.yml"
+
+permissions:
+  contents: read
+  pull-requests: write
+
+jobs:
+  build-preview:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+
+      - name: Install docs dependencies
+        run: npm --prefix website ci
+
+      - name: Build docs
+        run: npm --prefix website run build
+
+      - name: Upload preview artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: docs-preview
+          path: website/build
+          if-no-files-found: error
+          retention-days: 7
+
+      - name: Comment preview instructions
+        uses: actions/github-script@v7
+        env:
+          RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
+        with:
+          script: |
+            const marker = '<!-- docs-preview-comment -->';
+            const body = [
+              marker,
+              '✅ Docusaurus preview build is ready.',
+              '',
+              `1. Open the workflow run: ${process.env.RUN_URL}`,
+              '2. Download the `docs-preview` artifact',
+              '3. Unzip and open locally (for example `npx serve <unzipped-dir>`)',
+              '',
+              'This artifact is generated from the PR branch and can be reviewed before merge.',
+            ].join('\n');
+
+            const issue_number = context.issue.number;
+            const { data: comments } = await github.rest.issues.listComments({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number,
+              per_page: 100,
+            });
+
+            const existing = comments.find(
+              (comment) =>
+                comment.user?.type === 'Bot' &&
+                typeof comment.body === 'string' &&
+                comment.body.includes(marker),
+            );
+
+            if (existing) {
+              await github.rest.issues.updateComment({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                comment_id: existing.id,
+                body,
+              });
+            } else {
+              await github.rest.issues.createComment({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                issue_number,
+                body,
+              });
+            }

.github/workflows/release.yml

@@ -15,7 +15,8 @@ jobs:
   release:
     runs-on: ubuntu-latest
     permissions:
-      contents: read
+      contents: write
+      id-token: write
     steps:
       - uses: actions/checkout@v4
 
@@ -49,6 +50,28 @@ jobs:
           fi
           echo "Version OK: $cli_version"
 
+      - name: Verify Tag Matches package.json
+        if: startsWith(github.ref, 'refs/tags/v')
+        run: |
+          tag_version="${GITHUB_REF_NAME#v}"
+          pkg_version="$(node -p "require('./package.json').version")"
+          if [ "$tag_version" != "$pkg_version" ]; then
+            echo "Tag/package mismatch: tag=$tag_version package=$pkg_version"
+            exit 1
+          fi
+          echo "Tag matches package version: $pkg_version"
+
+      - name: Pack npm artifact
+        run: npm pack --pack-destination .
+
+      - name: Create GitHub Release
+        if: startsWith(github.ref, 'refs/tags/v')
+        uses: softprops/action-gh-release@v2
+        with:
+          generate_release_notes: true
+          files: |
+            *.tgz
+
       - name: Publish To npm
         if: ${{ github.event_name == 'push' || github.event.inputs.publish == 'true' }}
         run: npm publish --cache /tmp/npm-cache

README.md

@@ -190,14 +190,14 @@ export BLUEBUBBLES_PASSWORD='your#server#password'
 
 ## Docs
 
-Docs are served via Scalar and deployed to GitHub Pages.
+Docs are served via Docusaurus and deployed to GitHub Pages.
 
 ```bash
 bun run docs:dev
 bun run docs:validate
 ```
 
-GitHub Pages workflow publishes `scalar/index.html` at:
+GitHub Pages workflow publishes `website/build` at:
 
 ```text
 https://anmho.github.io/bluebubbles-cli/