fix: prepare release artifacts before publishing (#111)

## Summary
- Generate shell completions and man pages in an isolated, read-only
preparation job before protected release publishing.
- Bind prepared artifacts to the verified release commit and skip legacy
GoReleaser preparation hooks when republishing historical tags.
- Preserve existing archive contents, Linux packages, Homebrew output,
signing/notarization configuration, attestations, and current pinned
GitHub Actions versions.
- Add workflow, credential-boundary, release-configuration,
historical-tag, and artifact-compatibility regression coverage.

## Validation
- `env GOCACHE=/Users/jbeckwith/.cache/go-build ./scripts/test -skip
'^TestFilesCreateCLICancelClosesStalledFIFO$'`
- `env GOCACHE=/Users/jbeckwith/.cache/go-build go test -race
-parallel=1 ./... -skip '^TestFilesCreateCLICancelClosesStalledFIFO$'`
- `env GOCACHE=/Users/jbeckwith/.cache/go-build go test -race ./scripts
-count=1`
- `./scripts/lint`, `go vet ./...`, `actionlint`, `goreleaser check`,
and `./scripts/test-goreleaser-installer`
- Full GoReleaser snapshot across all nine Linux/macOS/Windows archive
targets, plus Linux packages and the Homebrew cask.

The excluded FIFO test fails independently on the unchanged macOS
baseline; Windows test cross-compilation passes.

Author: jbeckwith-oai

.github/workflows/ci.yml

@@ -52,6 +52,11 @@ jobs:
         id: goreleaser
         uses: ./.github/actions/setup-goreleaser
 
+      - name: Verify local and historical release preflight
+        run: go test ./scripts -run '^Test(Local|Historical)ReleasePreflight$' -count=1
+        env:
+          GORELEASER_EXECUTABLE: ${{ steps.goreleaser.outputs.executable }}
+
       - name: Generate release inputs
         run: |
           mkdir -p completions

.gitignore

@@ -1,5 +1,9 @@
 .prism.log
 .stdy.log
 dist/
+/completions/openai.bash
+/completions/openai.zsh
+/completions/openai.fish
+/man/man1/openai.1.gz
 /openai
 *.exe

docs/releasing.md

@@ -11,10 +11,22 @@ The reviewed checksums cover Linux and macOS hosts on x86_64 and arm64. The
 host architecture does not limit the Linux, macOS, and Windows release targets
 configured in `.goreleaser.yml`.
 
+Shell completions and man pages are generated in a separate, read-only job before
+the protected publishing job receives repository-write tokens or signing and
+notarization credentials. GoReleaser packages those prebuilt files without
+running the application. For local release or snapshot builds, first run
+`./scripts/generate-release-artifacts` without publishing or signing credentials.
+Publishing always skips GoReleaser's `before` hooks, including when an older
+release tag still contains the previous application-executing hooks.
+Rooted, exact-file ignore rules keep only the expected local completions and man
+page out of Git status; the publishing checkout applies the same exact-file
+excludes in its local Git metadata so non-snapshot releases also pass
+GoReleaser's clean-tree validation when historical tags predate those rules.
+
 The publish workflow installs GoReleaser from its trusted workflow checkout
 before switching to the requested release tag. This allows existing release tags
 that predate the installer to be republished; the workflow checkout, not the
-historical tag, determines the reviewed GoReleaser version.
+historical tag, determines the reviewed GoReleaser version and artifact generator.
 
 ## Update GoReleaser
 

scripts/generate-release-artifacts

@@ -0,0 +1,31 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+cd "${GITHUB_WORKSPACE:-$(dirname "$0")/..}"
+
+credentials=(
+  GITHUB_TOKEN
+  GH_TOKEN
+  HOMEBREW_TAP_GITHUB_TOKEN
+  MACOS_SIGN_P12
+  MACOS_SIGN_PASSWORD
+  MACOS_NOTARY_KEY
+  MACOS_NOTARY_KEY_ID
+  MACOS_NOTARY_ISSUER_ID
+  RELEASE_APP_PRIVATE_KEY
+  ACTIONS_ID_TOKEN_REQUEST_TOKEN
+)
+
+for credential in "${credentials[@]}"; do
+  if [[ -n "${!credential:-}" ]]; then
+    echo "Release artifacts must be generated without $credential" >&2
+    exit 1
+  fi
+done
+
+mkdir -p completions
+for shell in bash zsh fish; do
+  go run ./cmd/openai/main.go @completion "$shell" > "completions/openai.$shell"
+done
+go run ./cmd/openai/main.go @manpages -o man