mirror of
https://github.com/gastownhall/beads.git
synced 2026-09-14 20:17:24 +08:00
Chris Sells
d2f87d50de
* docs(pipeline): pin the generated CLI docs to the released bd; repair main's CLI reference The #4874 squash-merge raced the docs-autofix bot: the bot had pushed a regeneration from main's source onto the PR branch, so the squash landed a contradictory mix — the release-aligned hand-written docs plus a CLI reference re-documenting unreleased commands and flags, with docs.json referencing four pages (heartbeat, migrate-personal, reclaim, unclaim) whose files do not exist. That broken nav fails the docsync guard on main and on every branch cut from it. This restores the intended end state of #4874 and lands the pin that prevents the race from recurring. - Regenerate the CLI reference from a bd built from the v1.1.0 tag (CI's canonical pure-Go build), removing the unreleased commands/flags and fixing the dangling nav entries. - docs/cli-docs.pin names the release tag; scripts/resolve-docs-bd.sh builds and caches a canonical pure-Go bd from that tag, fetching the tag first in shallow CI checkouts. - generate-cli-docs.sh, check-doc-flags.sh, and check-cli-docs-drift.sh resolve bd through the pin and ignore a supplied binary while pinned (BD_DOCS_IGNORE_PIN=1 bypasses), so the drift gates and the autofix bot now enforce docs-match-release instead of docs-match-main. - tools/docsmint detects the pre-overhaul Docusaurus staging layout that bd <= v1.1.0 emits and converts it to the generic form before its normal Mintlify transform (tested); removable once the pin reaches a release whose emitter writes build/cli-docs. - check-doc-flags.sh: run without timeout(1) on macOS instead of failing Check 4. - Decision record: engdocs/decisions/2026-07-17-docs-release-pin.md; the beads-docs skill §8 updated to match. * lint: annotate gosec G705 false positive in the docsmint legacy bridge Same class as the existing nav-splice annotation: a developer tool writing repo Markdown, not a web-output sink.
60 lines
2.0 KiB
Bash
Executable File
60 lines
2.0 KiB
Bash
Executable File
#!/bin/bash
|
|
# resolve-docs-bd.sh — Resolve the bd binary the docs pipeline must use.
|
|
#
|
|
# Reads the release pin from docs/cli-docs.pin. When the pin names a tag,
|
|
# builds (and caches) a canonical pure-Go bd from that tag's source and
|
|
# prints the binary's absolute path on stdout. When the pin is HEAD or the
|
|
# pin file is absent, prints nothing and exits 0: callers fall back to their
|
|
# current-checkout behavior.
|
|
#
|
|
# The build matches CI's canonical docs build (CGO_ENABLED=0, -tags
|
|
# gms_pure_go), so regenerated docs are reproducible in any environment.
|
|
# The binary is cached at build/docs-bd/<pin>/bd (gitignored via /build/).
|
|
#
|
|
# Usage: scripts/resolve-docs-bd.sh
|
|
# stdout: absolute path to the pinned bd binary, or empty when unpinned
|
|
# diagnostics go to stderr
|
|
|
|
set -euo pipefail
|
|
|
|
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
|
|
PROJECT_ROOT="$(dirname "$SCRIPT_DIR")"
|
|
PIN_FILE="$PROJECT_ROOT/docs/cli-docs.pin"
|
|
|
|
if [ ! -f "$PIN_FILE" ]; then
|
|
exit 0
|
|
fi
|
|
|
|
PIN="$(grep -v '^[[:space:]]*#' "$PIN_FILE" | grep -m1 '[^[:space:]]' | tr -d '[:space:]' || true)"
|
|
if [ -z "$PIN" ] || [ "$PIN" = "HEAD" ]; then
|
|
exit 0
|
|
fi
|
|
|
|
CACHE_DIR="$PROJECT_ROOT/build/docs-bd/$PIN"
|
|
CACHED_BD="$CACHE_DIR/bd"
|
|
if [ -x "$CACHED_BD" ]; then
|
|
echo "$CACHED_BD"
|
|
exit 0
|
|
fi
|
|
|
|
# Make sure the pinned tag exists locally; shallow CI checkouts may not have
|
|
# fetched tags.
|
|
if ! git -C "$PROJECT_ROOT" rev-parse --verify --quiet "refs/tags/$PIN^{commit}" >/dev/null; then
|
|
echo "docs pin: fetching tag $PIN from origin..." >&2
|
|
git -C "$PROJECT_ROOT" fetch --depth=1 origin "refs/tags/$PIN:refs/tags/$PIN" >&2
|
|
fi
|
|
|
|
echo "docs pin: building bd from tag $PIN (CGO_ENABLED=0 -tags gms_pure_go)..." >&2
|
|
WT="$(mktemp -d)"
|
|
cleanup() {
|
|
git -C "$PROJECT_ROOT" worktree remove --force "$WT" >/dev/null 2>&1 || true
|
|
rm -rf "$WT"
|
|
}
|
|
trap cleanup EXIT
|
|
|
|
git -C "$PROJECT_ROOT" worktree add --detach --quiet "$WT" "refs/tags/$PIN"
|
|
mkdir -p "$CACHE_DIR"
|
|
(cd "$WT" && CGO_ENABLED=0 go build -tags gms_pure_go -o "$CACHED_BD" ./cmd/bd/) >&2
|
|
|
|
echo "$CACHED_BD"
|