Merge pull request #8 from effect-native/feat/publish-v1

feat: npm publishing pipeline with OIDC provenance

Author: subtleGradient

.github/workflows/release.yml

@@ -8,56 +8,67 @@ on:
 permissions:
   contents: write
   packages: write
+  id-token: write  # Required for npm OIDC provenance
 
 env:
   REGISTRY: ghcr.io
   IMAGE_NAME: ${{ github.repository }}
 
 jobs:
   build:
-    name: Build binaries
+    name: Build all binaries (Zig cross-compile)
     runs-on: ubuntu-latest
-    strategy:
-      matrix:
-        include:
-          # Linux builds
-          - target: x86_64-linux-gnu
-            platform: linux-x64-gnu
-          - target: x86_64-linux-musl
-            platform: linux-x64-musl
-          - target: aarch64-linux-gnu
-            platform: linux-arm64-gnu
-          - target: aarch64-linux-musl
-            platform: linux-arm64-musl
-          - target: armv7-linux-gnueabihf
-            platform: linux-armv7-gnu
-          - target: armv7-linux-musleabihf
-            platform: linux-armv7-musl
-          - target: i386-linux-musl
-            platform: linux-i386-musl
-          # macOS builds
-          - target: x86_64-macos
-            platform: darwin-x64
-          - target: aarch64-macos
-            platform: darwin-arm64
-          # Windows build
-          - target: x86_64-windows
-            platform: win32-x64
     steps:
       - uses: actions/checkout@v4
 
       - name: Install Zig
         uses: mlugg/setup-zig@v1
 
-      - name: Build ${{ matrix.platform }}
+      - name: Build all platforms
         run: |
-          zig build -Dtarget=${{ matrix.target }} -Doptimize=ReleaseSafe
+          # Zig cross-compiles for any platform from any platform
+          # No need for matrix - build everything on one runner
+          
+          TARGETS=(
+            "x86_64-linux-gnu:linux-x64-gnu"
+            "x86_64-linux-musl:linux-x64-musl"
+            "aarch64-linux-gnu:linux-arm64-gnu"
+            "aarch64-linux-musl:linux-arm64-musl"
+            "arm-linux-gnueabihf:linux-arm-gnu"
+            "arm-linux-musleabihf:linux-arm-musl"
+            "x86_64-macos:darwin-x64"
+            "aarch64-macos:darwin-arm64"
+            # Windows - DISABLED: POSIX API usage needs fixing
+            # "x86_64-windows:win32-x64"
+            # i386 - DISABLED: Low priority, test after v1.0.0
+            # "i386-linux-musl:linux-i386-musl"
+          )
+          
+          for entry in "${TARGETS[@]}"; do
+            IFS=':' read -r target platform <<< "$entry"
+            echo "=== Building $platform (zig target: $target) ==="
+            
+            zig build -Dtarget="$target" -Doptimize=ReleaseSafe
+            
+            mkdir -p "release/$platform"
+            if [[ "$platform" == win32* ]]; then
+              cp zig-out/bin/ansilust.exe "release/$platform/"
+            else
+              cp zig-out/bin/ansilust "release/$platform/"
+            fi
+            
+            # Clean for next build
+            rm -rf zig-out zig-cache
+          done
+          
+          echo "=== All builds complete ==="
+          find release -type f
       
       - name: Upload artifacts
         uses: actions/upload-artifact@v4
         with:
-          name: binaries-${{ matrix.platform }}
-          path: zig-out/*/ansilust*
+          name: binaries-all
+          path: release/
           retention-days: 1
 
   assemble-npm:
@@ -72,25 +83,28 @@ jobs:
         with:
           node-version: '20'
 
-      - name: Download all artifacts
+      - name: Download binaries artifact
         uses: actions/download-artifact@v4
         with:
+          name: binaries-all
           path: artifacts/
 
-      - name: Assemble binaries
+      - name: Show artifact structure
         run: |
-          mkdir -p zig-out
-          # Extract binaries from artifact structure
-          find artifacts -name "ansilust*" -type f | while read file; do
-            basename=$(basename "$file")
-            cp "$file" "zig-out/$basename"
-          done
+          echo "=== Artifact structure ==="
+          find artifacts -type f
       
       - name: Install dependencies
         run: npm install
 
+      - name: Extract version from tag
+        id: version
+        run: |
+          VERSION=${GITHUB_REF#refs/tags/v}
+          echo "version=$VERSION" >> $GITHUB_OUTPUT
+      
       - name: Run assembly script
-        run: node scripts/assemble-npm-packages.js
+        run: PACKAGE_VERSION=${{ steps.version.outputs.version }} node scripts/assemble-npm-packages.js
 
       - name: Upload npm packages
         uses: actions/upload-artifact@v4
@@ -100,9 +114,12 @@ jobs:
           retention-days: 1
 
   publish-npm:
-    name: Publish to npm
+    name: Publish to npm (OIDC)
     needs: assemble-npm
     runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write  # Required for npm OIDC publishing (no NPM_TOKEN needed)
     steps:
       - uses: actions/checkout@v4
 
@@ -112,28 +129,44 @@ jobs:
           node-version: '20'
           registry-url: 'https://registry.npmjs.org'
 
+      - name: Upgrade npm for OIDC support
+        run: npm install -g npm@latest
+      
       - name: Download npm packages
         uses: actions/download-artifact@v4
         with:
           name: npm-packages
           path: packages/
 
-      - name: Publish platform packages
+      - name: OIDC preflight - ensure no auth tokens
+        run: |
+          echo "=== OIDC Preflight ==="
+          # Remove any existing auth tokens to ensure OIDC is used
+          for npmrc in "$NPM_CONFIG_USERCONFIG" ~/.npmrc .npmrc; do
+            if [ -n "$npmrc" ] && [ -f "$npmrc" ]; then
+              echo "Cleaning $npmrc of any existing auth tokens..."
+              sed -i -E '/\/\/registry\.npmjs\.org\/:(_authToken|_auth)\s*=/d' "$npmrc" 2>/dev/null || true
+              sed -i -E '/^\s*(_authToken|_auth)\s*=/d' "$npmrc" 2>/dev/null || true
+            fi
+          done
+          
+          echo "Verifying npm registry connectivity..."
+          npm ping || exit 1
+          echo "Registry: $(npm config get registry)"
+      
+      - name: Publish platform packages with OIDC
         run: |
           for pkg in packages/ansilust-*/; do
             if [ -f "$pkg/package.json" ]; then
+              echo "Publishing $pkg..."
               cd "$pkg"
-              npm publish
+              npm publish --provenance --access public
               cd - > /dev/null
             fi
           done
-        env:
-          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
       
-      - name: Publish meta package
-        run: npm publish packages/ansilust/
-        env:
-          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+      - name: Publish meta package with OIDC
+        run: npm publish packages/ansilust/ --provenance --access public
 
   create-release:
     name: Create GitHub release
@@ -142,38 +175,44 @@ jobs:
     steps:
       - uses: actions/checkout@v4
 
-      - name: Download all artifacts
+      - name: Download binaries artifact
         uses: actions/download-artifact@v4
         with:
+          name: binaries-all
           path: artifacts/
 
       - name: Prepare release artifacts
         run: |
           mkdir -p release-artifacts
           
-          # Copy and organize binaries
-          find artifacts -name "ansilust*" -type f | while read file; do
-            platform=$(basename "$file" | sed 's/ansilust-//' | sed 's/.exe$//')
+          # Iterate through platform directories
+          for platform_dir in artifacts/*/; do
+            platform=$(basename "$platform_dir")
+            binary="$platform_dir/ansilust"
+            binary_exe="$platform_dir/ansilust.exe"
             
-            if [[ "$platform" == "win32"* ]]; then
+            if [[ -f "$binary_exe" ]]; then
               # Windows: create zip
-              mkdir -p "temp/$platform/bin"
-              cp "$file" "temp/$platform/bin/"
+              mkdir -p "temp/ansilust-$platform"
+              cp "$binary_exe" "temp/ansilust-$platform/"
               cd temp
-              zip -r "../release-artifacts/ansilust-$platform.zip" "$platform/"
+              zip -r "../release-artifacts/ansilust-$platform.zip" "ansilust-$platform/"
               cd ..
               rm -rf temp
-            else
+            elif [[ -f "$binary" ]]; then
               # Unix: create tar.gz
-              mkdir -p "temp/$platform/bin"
-              cp "$file" "temp/$platform/bin/ansilust"
-              chmod +x "temp/$platform/bin/ansilust"
+              mkdir -p "temp/ansilust-$platform"
+              cp "$binary" "temp/ansilust-$platform/"
+              chmod +x "temp/ansilust-$platform/ansilust"
               cd temp
-              tar -czf "../release-artifacts/ansilust-$platform.tar.gz" "$platform/"
+              tar -czf "../release-artifacts/ansilust-$platform.tar.gz" "ansilust-$platform/"
               cd ..
               rm -rf temp
             fi
           done
+          
+          echo "=== Release artifacts ==="
+          ls -la release-artifacts/
       
       - name: Generate checksums
         run: bash scripts/generate-checksums.sh release-artifacts/
@@ -242,9 +281,10 @@ jobs:
     steps:
       - uses: actions/checkout@v4
 
-      - name: Download all artifacts
+      - name: Download binaries artifact
         uses: actions/download-artifact@v4
         with:
+          name: binaries-all
           path: artifacts/
 
       - name: Set up Docker Buildx

.gitignore

@@ -8,9 +8,11 @@ package-lock.json
 npm-debug.log*
 yarn-error.log*
 
-# Platform package binaries
-packages/*/bin/
+# Platform package binaries (but not the launcher.js in ansilust/bin/)
 packages/ansilust-*/
+!packages/ansilust/
+!packages/ansilust/bin/
+!packages/ansilust/bin/launcher.js
 
 # Build artifacts
 *.o

.specs/publish/first/PREP/01-HYPOTHESIS.md

@@ -0,0 +1,30 @@
+# Hypothesis: First Publish Strategy
+
+## The Prior
+
+Based on the context:
+- We have a working Zig build system
+- We have placeholder npm packages published (`ansilust`, `16colors`, `16c`)
+- We have a comprehensive spec for esbuild-style npm distribution
+- We have install.sh and release.yml workflows sketched out
+- We have changesets configured
+
+**I expect the fastest path to "published somewhere usable" is:**
+
+1. **GitHub Releases first** - Binary tarballs with checksums
+2. **npm second** - Platform packages + meta launcher
+3. **Everything else later** - AUR, Nix, install scripts from ansilust.com
+
+**Assumptions:**
+- The Zig build already produces working binaries for at least the native platform
+- GitHub Actions can cross-compile to other targets
+- The npm packages just need the launcher.js and binaries stuffed in
+- We can ship v1.0.0 with just npm + GitHub releases working
+
+**Rationale:**
+- GitHub Releases is the simplest - just `gh release create` with binaries
+- npm is the most user-visible - `npx ansilust` is the dream command
+- install.sh from ansilust.com requires hosting setup (more friction)
+- AUR/Nix can wait - smaller audience, more maintenance
+
+**Key Question:** Can we get to `npx ansilust file.ans` working in one session?

.specs/publish/first/PREP/02-EVIDENCE-LOG.md

@@ -0,0 +1,73 @@
+# Evidence Log: First Publish Reality Check
+
+## Raw Facts
+
+### [SUPPORTS] Build System Works
+- `zig build -Doptimize=ReleaseSafe` completes successfully
+- Produces two binaries:
+  - `zig-out/bin/ansilust` (8.3MB) - ANSI art renderer
+  - `zig-out/bin/16c` (11.0MB) - 16colors archive downloader
+- Both binaries execute correctly on native platform (Linux x64)
+
+### [SUPPORTS] npm Infrastructure Exists
+- Root `package.json` with workspaces configured
+- Changesets installed (`@changesets/cli`, `@changesets/changelog-github`)
+- Three placeholder packages published at v0.0.1:
+  - `ansilust` - meta package with launcher stub
+  - `16colors` - placeholder
+  - `16c` - placeholder
+
+### [SUPPORTS] Release Workflow Exists
+- `.github/workflows/release.yml` - full matrix build (10 targets)
+- `.github/workflows/changeset-version.yml` - version PR automation
+- `scripts/install.sh` - complete bash installer (327 lines)
+- `scripts/assemble-npm-packages.js` - platform package assembly script
+
+### [SUPPORTS] Package Structure Defined
+- `packages/ansilust/package.json` has:
+  - `bin: {"ansilust": "bin/launcher.js"}` 
+  - `dependencies: {"detect-libc": "^2.1.2"}`
+  - `optionalDependencies` for all 10 platform packages
+- BUT: One local file reference `"ansilust-linux-x64-gnu": "file:../ansilust-linux-x64-gnu"` - need to fix
+
+### [FALSIFIES] Launcher Not Implemented
+- `packages/ansilust/index.js` is just a placeholder console.log
+- `packages/ansilust/bin/launcher.js` does NOT exist
+- This blocks `npx ansilust` from working
+
+### [FALSIFIES] Platform Packages Not Created
+- No `packages/ansilust-*` directories exist (only `ansilust`, `16colors`, `16c`)
+- Assembly script exists but hasn't been run
+- Would need to create all 10 platform package directories
+
+### [SUPPORTS] Cross-Compilation Targets Defined
+Build matrix in release.yml covers:
+- linux-x64-gnu, linux-x64-musl
+- linux-arm64-gnu, linux-arm64-musl
+- linux-armv7-gnu, linux-armv7-musl
+- linux-i386-musl
+- darwin-x64, darwin-arm64
+- win32-x64
+
+### [SUPPORTS] AUR Package Template Exists
+- `aur/PKGBUILD` and `aur/.SRCINFO` exist
+- Need to verify they reference correct URLs
+
+### [SUPPORTS] Nix Flake Exists
+- `flake.nix` at repository root
+- Need to verify it's functional
+
+## Critical Gaps
+
+1. **No launcher.js** - npx won't work
+2. **No platform packages** - npm install won't get binaries
+3. **Local file reference** in optionalDependencies - will break publish
+4. **No --version/--help** in ansilust binary - just usage message
+5. **Assembly script** expects specific binary locations that don't match CI output
+
+## Quick Wins
+
+1. Create `bin/launcher.js` - ~50 lines of code
+2. Create one platform package manually for testing
+3. Fix the local file reference in package.json
+4. Test `npm link` workflow locally before publishing