feat(cli): hybrid publishing with GitHub releases for binaries (#21)

- Remove @starknetid/vibetracking-core npm dependency
- Download native binaries from GitHub releases on first CLI run
- Cache binaries in ~/.vibetracking/bin/{version}/
- Simplify publishing to 1 npm package instead of 9
- Update release workflow to upload binaries to GitHub releases
- Update CLAUDE.md and publish-cli skill documentation

This avoids npm OIDC/auth issues by hosting binaries on GitHub.
Users still run `bunx vibetracking` - binary downloads automatically.

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

Author: fricoben

.claude/skills/publish-cli/SKILL.md

@@ -1,45 +1,53 @@
 ---
 name: publish-cli
 description: >
-  CLI publishing workflow for npm releases via GitHub Actions.
+  CLI publishing workflow using GitHub releases for binaries and local npm publish.
   Trigger terms: publish, release, npm, cli, version, tag, github actions,
-  vibetracking-core, package, deploy cli.
+  vibetracking, package, deploy cli.
 ---
 
 ## When to Use
 
 - Publishing a new version of the CLI to npm
-- Checking which packages are published
-- Understanding the release workflow
-
-## Published Packages
-
-| Package | Description |
-|---------|-------------|
-| `vibetracking` | Main CLI package |
-| `@starknetid/vibetracking-core` | Native Rust core (auto-selects platform) |
-| `@starknetid/vibetracking-core-darwin-x64` | macOS Intel |
-| `@starknetid/vibetracking-core-darwin-arm64` | macOS Apple Silicon |
-| `@starknetid/vibetracking-core-darwin-universal` | macOS Universal |
-| `@starknetid/vibetracking-core-linux-x64-gnu` | Linux x64 (glibc) |
-| `@starknetid/vibetracking-core-linux-arm64-gnu` | Linux ARM64 (glibc) |
-| `@starknetid/vibetracking-core-win32-x64-msvc` | Windows x64 |
-| `@starknetid/vibetracking-core-win32-arm64-msvc` | Windows ARM64 |
+- Checking the release workflow
+- Understanding the hybrid publishing model
+
+## Architecture: Hybrid Publishing
+
+The CLI uses a hybrid publishing approach:
+
+| Component | Host | Description |
+|-----------|------|-------------|
+| `vibetracking` | npm | CLI JavaScript wrapper (you publish locally) |
+| Native binaries | GitHub Releases | `.node` files for each platform |
+
+**Why?** This simplifies publishing to 1 npm package instead of 9, avoiding npm OIDC/auth issues.
+
+**How it works**: On first run, the CLI downloads the correct native binary from GitHub releases to `~/.vibetracking/bin/{version}/`.
 
 ## Procedure: Publish a New Version
 
 ### Step 1: Update Version Numbers
 
-Update versions in **both** package.json files:
-- `packages/cli/package.json`
-- `packages/core/package.json`
+Update version in `packages/cli/package.json`:
+```json
+{
+  "version": "X.Y.Z"
+}
+```
+
+Update `BINARY_VERSION` constant in:
+- `packages/cli/src/native.ts`
+- `packages/cli/src/native-runner.ts`
 
-Also update `optionalDependencies` versions in core's package.json.
+```typescript
+const BINARY_VERSION = "X.Y.Z";
+```
 
 ### Step 2: Commit and Push
 
 ```bash
-git add packages/cli/package.json packages/core/package.json
+git add packages/cli/
 git commit -m "chore: bump CLI version to X.Y.Z"
 git push origin main
 ```
@@ -51,57 +59,66 @@ git tag cli-vX.Y.Z
 git push origin cli-vX.Y.Z
 ```
 
-### Step 4: Verify Release
+### Step 4: Wait for CI
 
-GitHub Actions will automatically:
+GitHub Actions will:
 1. Build native binaries for all 6 platforms
 2. Create universal macOS binary
-3. Publish `@starknetid/vibetracking-core` and all platform packages
-4. Publish `vibetracking` CLI
+3. Upload all binaries to GitHub Release
 
 Monitor progress at: Actions > Release CLI
 
+### Step 5: Publish CLI to npm (Locally)
+
+Once CI completes, publish from your local machine:
+
+```bash
+cd packages/cli
+pnpm build
+npm publish --access public
+```
+
+### Step 6: Verify
+
+```bash
+# Check npm
+npm view vibetracking versions
+
+# Test fresh install (should download binary)
+rm -rf ~/.vibetracking/bin
+bunx vibetracking@X.Y.Z --version
+```
+
 ## Workflow Configuration
 
 - **File**: `.github/workflows/release.yml`
 - **Trigger**: Push tags matching `cli-v*`
-- **Authentication**: OIDC Trusted Publishing (no tokens required)
-
-### Setting Up Trusted Publishers
-
-Each package must be configured on npmjs.com to trust this workflow:
-
-1. Go to `https://www.npmjs.com/package/<package-name>/access`
-2. Scroll to **"Trusted Publisher"** section
-3. Click **"GitHub Actions"**
-4. Configure:
-   - **Organization/User**: `lfglabs-dev`
-   - **Repository**: `louisville`
-   - **Workflow filename**: `release.yml`
-   - **Environment**: *(leave blank)*
-
-Packages requiring trusted publisher setup:
-- `vibetracking`
-- `@starknetid/vibetracking-core`
-- `@starknetid/vibetracking-core-darwin-x64`
-- `@starknetid/vibetracking-core-darwin-arm64`
-- `@starknetid/vibetracking-core-darwin-universal`
-- `@starknetid/vibetracking-core-linux-x64-gnu`
-- `@starknetid/vibetracking-core-linux-arm64-gnu`
-- `@starknetid/vibetracking-core-win32-x64-msvc`
-- `@starknetid/vibetracking-core-win32-arm64-msvc`
-
-## Manual Trigger (Dry Run)
-
-Test the workflow without publishing:
+- **Output**: Native binaries uploaded to GitHub Release
+
+### Manual Trigger (Dry Run)
+
+Test the build without uploading:
 1. Go to Actions > Release CLI
 2. Click "Run workflow"
 3. Check "Dry run" option
 
+## Native Binary Locations
+
+Binaries are downloaded to `~/.vibetracking/bin/{version}/`:
+
+| Platform | Binary Name |
+|----------|-------------|
+| macOS Intel | `vibetracking-core.darwin-x64.node` |
+| macOS ARM | `vibetracking-core.darwin-arm64.node` |
+| Linux x64 | `vibetracking-core.linux-x64-gnu.node` |
+| Linux ARM64 | `vibetracking-core.linux-arm64-gnu.node` |
+| Windows x64 | `vibetracking-core.win32-x64-msvc.node` |
+| Windows ARM64 | `vibetracking-core.win32-arm64-msvc.node` |
+
 ## User Installation
 
 After publishing, users can install with:
 ```bash
-bunx vibetracking          # One-off execution
+bunx vibetracking          # One-off execution (downloads binary on first run)
 bun add -g vibetracking    # Global install
 ```

.github/workflows/release.yml

@@ -7,7 +7,7 @@ on:
   workflow_dispatch:
     inputs:
       dry_run:
-        description: 'Dry run (skip npm publish)'
+        description: 'Dry run (skip GitHub release upload)'
         required: false
         default: false
         type: boolean
@@ -27,7 +27,6 @@ env:
 
 permissions:
   contents: write
-  id-token: write
   actions: read
 
 jobs:
@@ -134,8 +133,8 @@ jobs:
           path: packages/core/*.node
           if-no-files-found: error
 
-  publish:
-    name: Publish to npm
+  upload-release:
+    name: Upload to GitHub Release
     runs-on: ubuntu-latest
     needs:
       - build
@@ -145,77 +144,60 @@ jobs:
     steps:
       - uses: actions/checkout@v4
 
-      - name: Setup Bun
-        uses: oven-sh/setup-bun@v2
-        with:
-          bun-version: latest
-
-      - name: Setup Node.js
-        uses: actions/setup-node@v4
-        with:
-          node-version: '22'
-          registry-url: 'https://registry.npmjs.org'
-
-      - name: Install dependencies
-        run: bun install
-
       - name: Download artifacts from current run
         if: ${{ github.event.inputs.skip_build != 'true' }}
         uses: actions/download-artifact@v4
         with:
-          path: packages/core/artifacts
+          path: artifacts
+          pattern: bindings-*
+          merge-multiple: true
 
       - name: Download artifacts from previous run
         if: ${{ github.event.inputs.skip_build == 'true' }}
         uses: actions/download-artifact@v4
         with:
-          path: packages/core/artifacts
+          path: artifacts
+          pattern: bindings-*
+          merge-multiple: true
           github-token: ${{ secrets.GITHUB_TOKEN }}
           run-id: ${{ github.event.inputs.run_id }}
 
-      - name: Move artifacts
-        run: bun x @napi-rs/cli artifacts
-        working-directory: packages/core
-
-      - name: List packages
-        run: ls -la npm/ || echo "No npm directory"
-        working-directory: packages/core
-
-      - name: Update npm (required for OIDC)
-        run: npm install -g npm@latest
+      - name: List artifacts
+        run: ls -la artifacts/
 
-      - name: Publish platform packages
-        if: ${{ github.event.inputs.dry_run != 'true' }}
+      - name: Get tag name
+        id: tag
         run: |
-          for dir in npm/*/; do
-            if [ -d "$dir" ]; then
-              echo "Publishing $dir"
-              (cd "$dir" && npm publish --access public)
-            fi
-          done
-        working-directory: packages/core
-
-      - name: Publish @starknetid/vibetracking-core
+          if [[ "${{ github.ref_type }}" == "tag" ]]; then
+            echo "name=${{ github.ref_name }}" >> $GITHUB_OUTPUT
+          else
+            # For manual runs, use the version from package.json
+            VERSION=$(jq -r .version packages/cli/package.json)
+            echo "name=cli-v${VERSION}" >> $GITHUB_OUTPUT
+          fi
+
+      - name: Create or update GitHub Release
         if: ${{ github.event.inputs.dry_run != 'true' }}
-        run: npm publish --access public
-        working-directory: packages/core
-
-      - name: Build CLI
-        run: bun run build
-        working-directory: packages/cli
-
-      - name: Publish vibetracking CLI
-        if: ${{ github.event.inputs.dry_run != 'true' }}
-        run: npm publish --access public
-        working-directory: packages/cli
+        uses: softprops/action-gh-release@v2
+        with:
+          tag_name: ${{ steps.tag.outputs.name }}
+          name: CLI ${{ steps.tag.outputs.name }}
+          files: artifacts/*.node
+          fail_on_unmatched_files: true
+          generate_release_notes: true
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 
       - name: Summary
         run: |
-          echo "## Published Packages" >> $GITHUB_STEP_SUMMARY
-          echo "- @starknetid/vibetracking-core" >> $GITHUB_STEP_SUMMARY
-          echo "- vibetracking" >> $GITHUB_STEP_SUMMARY
+          echo "## Release ${{ steps.tag.outputs.name }}" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "### Binaries uploaded to GitHub Release" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          ls -1 artifacts/*.node | while read f; do
+            echo "- $(basename $f)" >> $GITHUB_STEP_SUMMARY
+          done
           echo "" >> $GITHUB_STEP_SUMMARY
-          echo "### Install" >> $GITHUB_STEP_SUMMARY
-          echo "\`\`\`bash" >> $GITHUB_STEP_SUMMARY
-          echo "bunx vibetracking" >> $GITHUB_STEP_SUMMARY
-          echo "\`\`\`" >> $GITHUB_STEP_SUMMARY
+          echo "### Next Steps" >> $GITHUB_STEP_SUMMARY
+          echo "1. Publish CLI to npm locally: \`cd packages/cli && npm publish --access public\`" >> $GITHUB_STEP_SUMMARY
+          echo "2. Verify: \`bunx vibetracking@latest --version\`" >> $GITHUB_STEP_SUMMARY

CLAUDE.md

@@ -575,6 +575,33 @@ Cache TTL: 24 hours
 
 ---
 
-## CLI Publishing (npm)
+## CLI Publishing
 
-See the `publish-cli` skill for the full release workflow. Trigger terms: publish, release, npm, cli, version, tag.
+### Hybrid Publishing Model
+
+The CLI uses a hybrid publishing approach:
+
+- **npm**: Only the `vibetracking` CLI package is published (JavaScript wrapper)
+- **GitHub Releases**: Native binaries (`.node` files) are hosted as release assets
+- **First-run download**: CLI automatically downloads the correct binary on first run
+
+This simplifies publishing to just 1 npm package instead of 9 (CLI + core + 7 platform packages).
+
+### How It Works
+
+1. User runs `bunx vibetracking`
+2. CLI checks for binary in `~/.vibetracking/bin/{version}/`
+3. If not found, downloads from GitHub release
+4. Binary is cached for future runs
+
+### Publishing Workflow
+
+1. **Bump version** in `packages/cli/package.json`
+2. **Update BINARY_VERSION** in `packages/cli/src/native.ts` and `native-runner.ts`
+3. **Commit and push** the version change
+4. **Create and push tag**: `git tag cli-vX.Y.Z && git push origin cli-vX.Y.Z`
+5. **Wait for CI** to build and upload binaries to GitHub release
+6. **Publish CLI locally**: `cd packages/cli && pnpm build && npm publish --access public`
+7. **Verify**: `bunx vibetracking@latest --version`
+
+See the `publish-cli` skill for detailed steps. Trigger terms: publish, release, npm, cli, version, tag.

packages/cli/package.json

@@ -32,7 +32,6 @@
     "prepublishOnly": "bun run build"
   },
   "dependencies": {
-    "@starknetid/vibetracking-core": "workspace:*",
     "clipboardy": "^5.0.2",
     "commander": "^14.0.2",
     "csv-parse": "^5.6.0",

packages/cli/src/cli.ts

@@ -25,6 +25,7 @@ import {
   isCursorInstalled,
 } from "./cursor.js";
 import {
+  initNativeModule,
   parseLocalSourcesAsync,
   finalizeGraphAsync,
   type ParsedMessages,
@@ -207,6 +208,14 @@ async function openBrowserWithData(inviterUsername?: string) {
     await promptForCursorLogin();
   }
 
+  // Initialize native module (downloads binary on first run)
+  try {
+    await initNativeModule();
+  } catch (e) {
+    console.error(pc.red(`\n  Failed to initialize: ${(e as Error).message}\n`));
+    process.exit(1);
+  }
+
   const spinner = createSpinner({ color: "cyan" });
   spinner.start(pc.gray("Scanning AI coding tool data..."));