Merge pull request #67 from ran-codes/feat/release-binary-format

feat: standalone binary releases with install script

Author: ran-codes

.claude/reference/protocols/deployment.md

@@ -1,31 +1,56 @@
-# Deployment Checklist
+# Deployment
 
-## 1. Pre-Release — Feature Readiness
+## Matrix Build vs Goreleaser
+
+**Matrix build** (used by notion-sync): You write explicit `go build` commands in a GitHub Actions matrix — one job per OS/arch combo. Simple but verbose. Outputs standalone binaries.
+
+**Goreleaser** (used by zenodo-cli): A declarative tool that reads `.goreleaser.yaml` and handles building, packaging, checksums, and changelogs in one step. Less CI code, supports multi-binary projects natively. By default produces archives (tar.gz/zip), but can output raw binaries with `format: binary`.
+
+zenodo-cli uses goreleaser with `format: binary` so we get the simplicity of goreleaser config with the same standalone-binary UX as notion-sync.
+
+## Feature Comparison
+
+| Feature | notion-sync (matrix) | zenodo-cli (goreleaser) | ELI5 |
+|---|---|---|---|
+| Build system | Manual `go build` in CI matrix | Goreleaser (declarative yaml) | How the binaries get compiled in CI |
+| Release artifacts | Standalone binaries (`name-os-arch`) | Standalone binaries (via `format: binary`) | What users actually download |
+| macOS/Linux install | `curl \| bash` install script | `curl \| bash` install script | One-liner to install on Mac/Linux |
+| Windows install | Scoop (points at `.exe`) | Scoop (points at `.exe`) | One-liner to install on Windows |
+| Checksums | `sha256sum` in CI step | Goreleaser generates `checksums.txt` | Verifies download wasn't corrupted |
+| Version injection | `-X main.version=` in CI | `-X internal/cli.version=` via ldflags | Embeds version number into the binary at build time |
+| Scoop manifest update | CI step with `jq` | CI step with `jq` | Auto-updates the Scoop package after release |
+| Multi-binary support | Separate build line per binary | Multiple `builds:` entries in yaml | How we ship both `zenodo` and `zenodo-mcp` |
+| Changelog | GitHub auto-generated | Goreleaser with commit filters | Release notes on the GitHub release page |
+
+## Checklist
+
+### 1. Pre-Release — Feature Readiness
 
 - [ ] All features intended for this release are merged to `main`
-- [ ] Any commands not ready are commented out (e.g. deposit write, access links in v0.1)
 - [ ] `go build ./...` and `go test ./...` pass on `main`
-- [ ] Rebuild binary (`go build -o zenodo.exe ./cmd/zenodo`) and smoke-test key commands
+- [ ] Rebuild binaries and smoke-test key commands
 
-## 2. Pre-Release — CI/CD Readiness
+### 2. Pre-Release — CI/CD Readiness
 
 - [ ] `.github/workflows/release.yml` exists and triggers on `v*` tags
-- [ ] `.goreleaser.yaml` is configured (platforms, ldflags, archives, checksums)
-- [ ] `bucket/zenodo.json` Scoop manifest exists
+- [ ] `.goreleaser.yaml` is configured (platforms, ldflags, format: binary)
+- [ ] `bucket/zenodo-cli.json` Scoop manifest exists
 - [ ] Release workflow includes Scoop manifest auto-update step
+- [ ] `scripts/install.sh` exists for macOS/Linux
 - [ ] Version injection works (`internal/cli/version.go` has ldflags vars)
 
-## 3. Tag & Release
+### 3. Tag & Release
 
 - [ ] Ensure you're on `main` with a clean working tree
 - [ ] Tag: `git tag v<VERSION>` (e.g. `git tag v0.1.0`)
 - [ ] Push tag: `git push origin v<VERSION>`
 - [ ] Monitor the GitHub Actions release workflow for success
 
-## 4. Post-Release Verification
+### 4. Post-Release Verification
 
 - [ ] GitHub release page has binaries for all platforms (linux/darwin/windows × amd64/arm64)
 - [ ] `checksums.txt` is included in the release assets
-- [ ] `bucket/zenodo.json` was auto-updated with new version and hash (check the commit on `main`)
-- [ ] Scoop install works: `scoop bucket add zenodo https://github.com/ran-codes/zenodo-cli && scoop install zenodo`
+- [ ] `bucket/zenodo-cli.json` was auto-updated with new version and hash
+- [ ] Scoop install works: `scoop bucket add zenodo-cli https://github.com/ran-codes/zenodo-cli && scoop install zenodo-cli`
+- [ ] macOS install works: `curl -fsSL ... | bash`
 - [ ] `zenodo version` shows correct version, commit, and date

.claude/reference/v0.1/features/deployment.md

@@ -0,0 +1,86 @@
+# Deployment — CI/CD Design
+
+## Problem
+
+zenodo-cli ships two binaries (`zenodo` + `zenodo-mcp`) and needs to support three install methods:
+
+1. **macOS/Linux**: `curl | bash` one-liner
+2. **Windows**: Scoop package manager
+3. **Manual**: Download from GitHub Releases
+
+The original goreleaser config produced tar.gz/zip archives. This made `curl | bash` impractical (download archive → extract → find binary → move to PATH) and diverged from the pattern established in notion-sync.
+
+## Options Considered
+
+### Option A: Matrix build (notion-sync pattern)
+
+Manual `go build` commands in a GitHub Actions matrix — one job per OS/arch.
+
+```yaml
+strategy:
+  matrix:
+    include:
+      - goos: darwin
+        goarch: arm64
+      - goos: linux
+        goarch: amd64
+      # ...
+steps:
+  - run: go build -o zenodo-${{ matrix.goos }}-${{ matrix.goarch }} ./cmd/zenodo
+  - run: go build -o zenodo-mcp-${{ matrix.goos }}-${{ matrix.goarch }} ./cmd/zenodo-mcp
+```
+
+**Pros**: Simple, explicit, identical to notion-sync.
+**Cons**: Verbose CI config. Every new binary = more lines. No auto-changelog. Must manually handle checksums, ldflags, etc.
+
+### Option B: Goreleaser with archives (original)
+
+Goreleaser bundles both binaries into tar.gz (Unix) / zip (Windows) per platform.
+
+**Pros**: Minimal config. Multi-binary is one yaml entry.
+**Cons**: Archives break `curl | bash`. Users must extract before using. Diverges from notion-sync UX.
+
+### Option C: Goreleaser with `format: binary` (chosen)
+
+Goreleaser outputs standalone binaries (no archive wrapping). Names follow `{name}-{os}-{arch}` pattern.
+
+**Pros**: Declarative config. Multi-binary support. Auto-changelog. Checksums. Same standalone-binary UX as notion-sync.
+**Cons**: Slightly different from notion-sync's CI internals (goreleaser vs matrix), but identical end result.
+
+## Implementation
+
+### Goreleaser config (`.goreleaser.yaml`)
+
+Two `builds:` entries — one for `zenodo`, one for `zenodo-mcp`. Both use `binary: {name}-{{ .Os }}-{{ .Arch }}` naming. Archives section set to `format: binary` so no tar.gz/zip wrapping.
+
+### Release workflow (`.github/workflows/release.yml`)
+
+Triggered on `v*` tags. Runs goreleaser, then updates the Scoop manifest with checksums for both `.exe` files and commits to main.
+
+### Install script (`scripts/install.sh`)
+
+Detects OS/arch, downloads both `zenodo` and `zenodo-mcp` binaries from the latest GitHub release, installs to `/usr/local/bin`. Uses `sudo` only if needed.
+
+### Scoop manifest (`bucket/zenodo-cli.json`)
+
+Downloads both `.exe` files. Uses an `installer` script to rename from `zenodo-windows-amd64.exe` → `zenodo.exe` (and same for mcp). Both listed in `bin` array.
+
+## Release artifacts
+
+Each release produces:
+
+| File | Description |
+|------|-------------|
+| `zenodo-darwin-amd64` | CLI — macOS Intel |
+| `zenodo-darwin-arm64` | CLI — macOS Apple Silicon |
+| `zenodo-linux-amd64` | CLI — Linux x64 |
+| `zenodo-linux-arm64` | CLI — Linux ARM |
+| `zenodo-windows-amd64.exe` | CLI — Windows x64 |
+| `zenodo-windows-arm64.exe` | CLI — Windows ARM |
+| `zenodo-mcp-darwin-amd64` | MCP server — macOS Intel |
+| `zenodo-mcp-darwin-arm64` | MCP server — macOS Apple Silicon |
+| `zenodo-mcp-linux-amd64` | MCP server — Linux x64 |
+| `zenodo-mcp-linux-arm64` | MCP server — Linux ARM |
+| `zenodo-mcp-windows-amd64.exe` | MCP server — Windows x64 |
+| `zenodo-mcp-windows-arm64.exe` | MCP server — Windows ARM |
+| `checksums.txt` | SHA-256 checksums for all files |

.github/workflows/release.yml

@@ -30,23 +30,29 @@ jobs:
       - name: Update Scoop manifest
         run: |
           VERSION="${GITHUB_REF_NAME#v}"
-          SHA256=$(grep "zenodo_${VERSION}_windows_amd64.zip" dist/checksums.txt | awk '{print $1}')
+          SHA256_ZENODO=$(grep 'zenodo-windows-amd64.exe' dist/checksums.txt | awk '{print $1}')
+          SHA256_MCP=$(grep 'zenodo-mcp-windows-amd64.exe' dist/checksums.txt | awk '{print $1}')
 
           jq \
             --arg ver "$VERSION" \
-            --arg hash "$SHA256" \
-            '.version = $ver | .architecture."64bit".url = "https://github.com/ran-codes/zenodo-cli/releases/download/v\($ver)/zenodo_\($ver)_windows_amd64.zip" | .architecture."64bit".hash = $hash' \
-            bucket/zenodo.json > bucket/zenodo.json.tmp
+            --arg hash_zenodo "$SHA256_ZENODO" \
+            --arg hash_mcp "$SHA256_MCP" \
+            '.version = $ver
+            | .architecture."64bit".url[0] = "https://github.com/ran-codes/zenodo-cli/releases/download/v\($ver)/zenodo-windows-amd64.exe"
+            | .architecture."64bit".url[1] = "https://github.com/ran-codes/zenodo-cli/releases/download/v\($ver)/zenodo-mcp-windows-amd64.exe"
+            | .architecture."64bit".hash[0] = $hash_zenodo
+            | .architecture."64bit".hash[1] = $hash_mcp' \
+            bucket/zenodo-cli.json > bucket/zenodo-cli.json.tmp
 
-          mv bucket/zenodo.json.tmp bucket/zenodo.json
+          mv bucket/zenodo-cli.json.tmp bucket/zenodo-cli.json
 
       - name: Commit updated Scoop manifest
         run: |
           git config user.name "github-actions[bot]"
           git config user.email "github-actions[bot]@users.noreply.github.com"
           git fetch origin main
           git checkout main
-          git add bucket/zenodo.json
+          git add bucket/zenodo-cli.json
           git diff --cached --quiet && echo "No changes to commit" && exit 0
           git commit -m "scoop: update manifest to v${GITHUB_REF_NAME#v}"
           git push origin main

.goreleaser.yaml

@@ -8,7 +8,8 @@ before:
 builds:
   - id: zenodo
     main: ./cmd/zenodo
-    binary: zenodo
+    binary: zenodo-{{ .Os }}-{{ .Arch }}
+    no_unique_dist_dir: true
     env:
       - CGO_ENABLED=0
     goos:
@@ -26,7 +27,8 @@ builds:
 
   - id: zenodo-mcp
     main: ./cmd/zenodo-mcp
-    binary: zenodo-mcp
+    binary: zenodo-mcp-{{ .Os }}-{{ .Arch }}
+    no_unique_dist_dir: true
     env:
       - CGO_ENABLED=0
     goos:
@@ -40,11 +42,7 @@ builds:
       - -s -w
 
 archives:
-  - format: tar.gz
-    name_template: "{{ .ProjectName }}_{{ .Version }}_{{ .Os }}_{{ .Arch }}"
-    format_overrides:
-      - goos: windows
-        format: zip
+  - format: binary
 
 checksum:
   name_template: "checksums.txt"

README.md

@@ -6,18 +6,24 @@ Wraps the Zenodo REST API for record lookup, community browsing, license search,
 
 ## Install
 
+### Install script (macOS / Linux)
+
+```sh
+curl -fsSL https://raw.githubusercontent.com/ran-codes/zenodo-cli/main/scripts/install.sh | bash
+```
+
 ### Scoop (Windows)
 
 ```powershell
 ## Install Scoop if you don't have it: https://scoop.sh
 # irm get.scoop.sh | iex
-scoop bucket add zenodo https://github.com/ran-codes/zenodo-cli
-scoop install zenodo
+scoop bucket add zenodo-cli https://github.com/ran-codes/zenodo-cli
+scoop install zenodo-cli
 ```
 
 ### Manual download
 
-Download the binary for your platform from [GitHub Releases](https://github.com/ran-codes/zenodo-cli/releases), rename it to `zenodo` (or `zenodo.exe` on Windows), and add it to your PATH.
+Download the binaries for your platform from [GitHub Releases](https://github.com/ran-codes/zenodo-cli/releases) and add them to your PATH.
 
 ## Usage
 

bucket/zenodo-cli.json

@@ -0,0 +1,41 @@
+{
+  "version": "0.0.0",
+  "description": "CLI tool for managing metadata, searching records, and querying assets on Zenodo.",
+  "homepage": "https://github.com/ran-codes/zenodo-cli",
+  "license": "MIT",
+  "architecture": {
+    "64bit": {
+      "url": [
+        "https://github.com/ran-codes/zenodo-cli/releases/download/v0.0.0/zenodo-windows-amd64.exe",
+        "https://github.com/ran-codes/zenodo-cli/releases/download/v0.0.0/zenodo-mcp-windows-amd64.exe"
+      ],
+      "hash": [
+        "",
+        ""
+      ]
+    }
+  },
+  "installer": {
+    "script": [
+      "Copy-Item \"$dir\\zenodo-windows-amd64.exe\" \"$dir\\zenodo.exe\"",
+      "Copy-Item \"$dir\\zenodo-mcp-windows-amd64.exe\" \"$dir\\zenodo-mcp.exe\""
+    ]
+  },
+  "bin": ["zenodo.exe", "zenodo-mcp.exe"],
+  "checkver": {
+    "github": "https://github.com/ran-codes/zenodo-cli"
+  },
+  "autoupdate": {
+    "architecture": {
+      "64bit": {
+        "url": [
+          "https://github.com/ran-codes/zenodo-cli/releases/download/v$version/zenodo-windows-amd64.exe",
+          "https://github.com/ran-codes/zenodo-cli/releases/download/v$version/zenodo-mcp-windows-amd64.exe"
+        ]
+      }
+    },
+    "hash": {
+      "url": "https://github.com/ran-codes/zenodo-cli/releases/download/v$version/checksums.txt"
+    }
+  }
+}