Publishing & Release Guide

This document covers how to release the spt CLI and @smartpointstech/* npm packages.

Overview

When you push a version tag (v*), the release workflow automatically:

1. Builds the spt binary for 5 targets (macOS x64/ARM, Linux x64/ARM, Windows x64)
2. Creates a GitHub Release with all binaries + a macOS universal binary
3. Updates the Homebrew tap (SmartPointsTech/homebrew-tap)
4. Publishes to Chocolatey (choco install spt)
5. Submits to Winget (winget install SmartPointsTech.Spt)
6. Publishes npm packages (@smartpointstech/cli, @smartpointstech/core, @smartpointstech/sona)

Prerequisites

1. GitHub Secrets

Add these secrets to the spt repository (Settings > Secrets and variables > Actions):

Secret	Purpose	How to get it
HOMEBREW_TAP_TOKEN	Push to SmartPointsTech/homebrew-tap	GitHub PAT with repo scope
CHOCOLATEY_API_KEY	Push .nupkg to chocolatey.org	Chocolatey account > API Keys
WINGET_GITHUB_TOKEN	Submit PRs to microsoft/winget-pkgs	GitHub PAT with public_repo scope
NPM_TOKEN	Publish @smartpointstech/* packages	npm token create (Automation type)

All secrets are optional — the workflow gracefully skips any step whose secret is missing.

2. Homebrew Tap Repository

Already exists: SmartPointsTech/homebrew-tap

The HOMEBREW_TAP_TOKEN PAT needs:

• Scope: repo (full control of private repositories)
• Owner: must have push access to SmartPointsTech/homebrew-tap

To create:

1. Go to https://github.com/settings/tokens
2. Generate new token (classic) with repo scope
3. Add as HOMEBREW_TAP_TOKEN in spt repo secrets

3. Chocolatey Account

1. Register at https://community.chocolatey.org/account/Register
2. Verify your email
3. Go to Account > API Keys to get your key
4. Add as CHOCOLATEY_API_KEY in spt repo secrets

First-time setup: The first Chocolatey package submission goes through manual moderation (typically 1–3 days). Subsequent versions are auto-approved if no changes to the install scripts are detected.

4. Winget Initial Submission

The Winget workflow uses wingetcreate to auto-submit PRs. However, the first version must be submitted manually:

# Install wingetcreate
winget install wingetcreate

# Submit initial manifest
wingetcreate new https://github.com/SmartPointsTech/spt/releases/download/v0.1.0/spt_0.1.0_x86_64-pc-windows-msvc.zip

This opens an interactive wizard. Use these values:

• PackageIdentifier: SmartPointsTech.Spt
• Publisher: SmartPoints Technology
• PackageName: spt
• License: MIT
• ShortDescription: Unified CLI for SPT Format vector stores

After the initial PR is merged into microsoft/winget-pkgs, subsequent releases auto-submit via the workflow.

The WINGET_GITHUB_TOKEN PAT needs:

• Scope: public_repo
• Used by wingetcreate to fork microsoft/winget-pkgs and create PRs

5. npm Authentication

# Create an automation token (doesn't require 2FA on publish)
npm token create --type=automation

# Add as NPM_TOKEN in spt repo secrets

Or authenticate locally for manual publishes:

npm adduser

Cutting a Release

Standard Release

# 1. Ensure you're on main and everything is clean
git checkout main
git pull origin main

# 2. Update version in Cargo.toml workspace
#    Edit [workspace.package] version = "X.Y.Z"
#    Also update crates/spt-cli/Cargo.toml if it has its own version

# 3. Update npm package versions
npm version X.Y.Z --workspaces --no-git-tag-version

# 4. Commit version bump
git add -A
git commit -m "chore: bump version to X.Y.Z"
git push origin main

# 5. Tag and push — this triggers the release workflow
git tag -a vX.Y.Z -m "vX.Y.Z"
git push origin vX.Y.Z

Pre-release

# Pre-release tags (contain a hyphen) skip Homebrew/Chocolatey/Winget/npm
git tag -a vX.Y.Z-rc.1 -m "vX.Y.Z-rc.1"
git push origin vX.Y.Z-rc.1

This creates a GitHub Release marked as "pre-release" with binaries, but doesn't update any package managers.

Verifying the Release

GitHub Release

Check https://github.com/SmartPointsTech/spt/releases for:

• All 6 archives (5 platform-specific + 1 macOS universal)
• SHA256 checksum files
• Changelog

Homebrew

# Update tap
brew update

# Install or upgrade
brew install SmartPointsTech/tap/spt
# or
brew upgrade SmartPointsTech/tap/spt

# Verify
spt --version

Chocolatey

# Install (may take 1-3 days for first version moderation)
choco install spt

# Upgrade
choco upgrade spt

# Verify
spt --version

Winget

# Install (may take a few days for first PR to merge)
winget install SmartPointsTech.Spt

# Upgrade
winget upgrade SmartPointsTech.Spt

# Verify
spt --version

npm

npx @smartpointstech/cli --version

From Source

cargo install --git https://github.com/SmartPointsTech/spt.git spt-cli
spt --version

Manual / Emergency Publishes

If the CI workflow fails for a specific package manager, you can publish manually:

Manual Homebrew Update

git clone https://github.com/SmartPointsTech/homebrew-tap.git
cd homebrew-tap
# Edit Formula/spt.rb with new version, URLs, and SHA256 values
git commit -am "Update spt to vX.Y.Z"
git push

Manual Chocolatey Publish

# From the spt repo root
cd packaging/chocolatey

# Edit spt.nuspec — set correct version
# Edit tools/chocolateyInstall.ps1 — set correct URL and SHA256

choco pack spt.nuspec
choco push spt.X.Y.Z.nupkg --source https://push.chocolatey.org/ --api-key YOUR_API_KEY

Manual Winget Submission

wingetcreate update SmartPointsTech.Spt `
  --version X.Y.Z `
  --urls https://github.com/SmartPointsTech/spt/releases/download/vX.Y.Z/spt_X.Y.Z_x86_64-pc-windows-msvc.zip `
  --submit `
  --token YOUR_GITHUB_PAT

Manual npm Publish

npm adduser  # if not already logged in
npm publish --workspaces --access public

Troubleshooting

Build fails for a specific target

• Check the GitHub Actions logs for the failing matrix entry
• Common issue: missing system dependencies for cross-compilation
• Linux ARM builds require gcc-aarch64-linux-gnu

Homebrew tap not updating

• Verify HOMEBREW_TAP_TOKEN is valid and has repo scope
• Check if the token owner has push access to SmartPointsTech/homebrew-tap
• The step is skipped for pre-release tags (containing -)

Chocolatey package rejected

• First submission requires manual moderation (1–3 days)
• Check https://community.chocolatey.org/packages/spt for status
• Ensure VERIFICATION.txt is present and accurate
• Review Chocolatey moderation guidelines

Winget submission failing

• First version must be submitted manually (see Prerequisites above)
• Ensure WINGET_GITHUB_TOKEN has public_repo scope
• Check https://github.com/microsoft/winget-pkgs/pulls for your PR status
• wingetcreate may fail if the package identifier doesn't exist yet

npm publish fails

• Ensure NPM_TOKEN is an automation token (not granular/publish)
• Check that @spt org exists on npm and you have publish access
• The @smartpointstech/core package runs a napi build during prepublishOnly

SHA256 mismatch

• Each archive has a .sha256 companion file in the GitHub Release
• Checksums are computed during the build job and passed through job outputs
• If a mismatch occurs, re-run the release workflow

Architecture

Tag push (v*)
  │
  ├─► build (matrix: 5 targets)
  │     ├─ x86_64-apple-darwin
  │     ├─ aarch64-apple-darwin
  │     ├─ x86_64-unknown-linux-gnu
  │     ├─ aarch64-unknown-linux-gnu
  │     └─ x86_64-pc-windows-msvc
  │
  ├─► release (creates GitHub Release + universal macOS binary)
  │     │
  │     ├─► homebrew (updates SmartPointsTech/homebrew-tap)
  │     ├─► chocolatey (pushes .nupkg to chocolatey.org)
  │     ├─► winget (submits PR to microsoft/winget-pkgs)
  │     └─► npm (publishes @smartpointstech/* workspaces)

File Reference

File	Purpose
.github/workflows/ci.yaml	CI: fmt, clippy, test on push/PR
.github/workflows/release.yaml	Full release pipeline
packaging/chocolatey/spt.nuspec	Chocolatey package spec
packaging/chocolatey/tools/chocolateyInstall.ps1	Chocolatey install script
packaging/chocolatey/tools/chocolateyUninstall.ps1	Chocolatey uninstall script
packaging/chocolatey/tools/VERIFICATION.txt	Chocolatey moderation verification
packaging/winget/*.yaml	Winget manifest templates (reference only)