feat: CLI docs auto-generation with bd help --doc/--list/--all #7253

Workflow file for this run

	name: CI

	on:
	push:
	branches: [ main ]
	pull_request:
	branches: [ main ]

	jobs:
	# Fast check to ensure all version files are in sync
	check-version-consistency:
	name: Check version consistency
	runs-on: ubuntu-latest
	steps:
	- uses: actions/checkout@v6

	- name: Check all versions match
	run: ./scripts/check-versions.sh

	# Check CLI docs are in sync with live command tree
	check-cli-docs-freshness:
	name: Check CLI docs freshness
	runs-on: ubuntu-latest
	steps:
	- uses: actions/checkout@v6

	- name: Set up Go
	uses: actions/setup-go@v6
	with:
	go-version-file: 'go.mod'

	- name: Build bd
	run: CGO_ENABLED=0 go build -o bd ./cmd/bd/

	- name: Generate CLI reference
	run: ./bd help --all > /tmp/cli-ref.md

	- name: Check docs/CLI_REFERENCE.md freshness
	run: \|
	if ! diff -q docs/CLI_REFERENCE.md /tmp/cli-ref.md > /dev/null 2>&1; then
	echo "CLI docs are out of sync!"
	echo ""
	echo "Run ./scripts/generate-cli-docs.sh to update them"
	echo ""
	echo "Diff:"
	diff docs/CLI_REFERENCE.md /tmp/cli-ref.md \|\| true
	exit 1
	fi
	echo "CLI docs are up to date"

	- name: Generate individual command docs
	run: \|
	mkdir -p /tmp/cli-docs
	./bd help --list \| while read -r cmd; do
	./bd help --doc "$cmd" > "/tmp/cli-docs/$cmd.md"
	done

	- name: Check website docs freshness
	run: \|
	for f in website/docs/cli-reference/*.md; do
	cmd=$(basename "$f" .md)
	if [ -f "/tmp/cli-docs/$cmd.md" ]; then
	if ! diff -q "$f" "/tmp/cli-docs/$cmd.md" > /dev/null 2>&1; then
	echo "Website doc $f is out of sync"
	echo "Run ./scripts/generate-cli-docs.sh to update"
	exit 1
	fi
	fi
	done
	echo "Website CLI docs are up to date"

	# Fast check to catch accidental .beads/issues.jsonl changes from contributors
	check-no-beads-changes:
	name: Check for .beads changes
	runs-on: ubuntu-latest
	if: github.event_name == 'pull_request'
	steps:
	- uses: actions/checkout@v6
	with:
	fetch-depth: 0

	- name: Check for .beads/issues.jsonl changes
	run: \|
	if git diff --name-only origin/${{ github.base_ref }}...HEAD \| grep -q "^\.beads/issues\.jsonl$"; then
	echo "This PR includes changes to .beads/issues.jsonl"
	echo ""
	echo "This file is the project's issue database and should not be modified in PRs."
	echo ""
	echo "To fix, run:"
	echo " git checkout origin/main -- .beads/issues.jsonl"
	echo " git commit --amend"
	echo " git push --force"
	echo ""
	exit 1
	fi
	echo "No .beads/issues.jsonl changes detected"

	# Cross-platform test matrix (Linux/macOS only - Windows uses smoke tests)
	test:
	name: Test (${{ matrix.os }})
	runs-on: ${{ matrix.os }}
	strategy:
	fail-fast: false
	matrix:
	os: [ubuntu-latest, macos-latest]
	include:
	# Linux: full test suite with coverage
	- os: ubuntu-latest
	coverage: true
	test-flags: '-v -race -short -coverprofile=coverage.out'
	# macOS: full test suite, no coverage (faster)
	- os: macos-latest
	coverage: false
	test-flags: '-v -race -short'
	steps:
	- uses: actions/checkout@v6

	- name: Set up Go
	uses: actions/setup-go@v6
	with:
	go-version-file: 'go.mod'

	- name: Install ICU4C (Linux)
	if: matrix.os == 'ubuntu-latest'
	run: \|
	sudo apt-get update
	sudo apt-get install -y libicu-dev

	- name: Install ICU4C (macOS)
	if: matrix.os == 'macos-latest'
	run: \|
	brew install icu4c
	dir="$(brew --prefix icu4c)"
	echo "CGO_CPPFLAGS=-I$dir/include" >> "$GITHUB_ENV"
	echo "CGO_LDFLAGS=-L$dir/lib -Wl,-rpath,$dir/lib" >> "$GITHUB_ENV"
	echo "PKG_CONFIG_PATH=$dir/lib/pkgconfig" >> "$GITHUB_ENV"

	- name: Configure Git
	run: \|
	git config --global user.name "CI Bot"
	git config --global user.email "ci@beads.test"

	- name: Install gotestsum
	if: matrix.coverage
	run: go install gotest.tools/gotestsum@latest

	- name: Build
	run: go build -v ./cmd/bd

	- name: Test (with coverage + JUnit XML)
	if: matrix.coverage
	run: \|
	gotestsum \
	--junitfile junit.xml \
	--format testdox \
	-- -race -short -coverprofile=coverage.out ./...

	- name: Test
	if: ${{ !matrix.coverage }}
	run: go test ${{ matrix.test-flags }} ./...

	- name: Upload coverage to Codecov
	if: matrix.coverage && !cancelled()
	uses: codecov/codecov-action@v5
	with:
	files: coverage.out
	token: ${{ secrets.CODECOV_TOKEN }}
	fail_ci_if_error: false

	- name: Upload test results to Codecov
	if: matrix.coverage && !cancelled()
	uses: codecov/codecov-action@v5
	with:
	files: junit.xml
	token: ${{ secrets.CODECOV_TOKEN }}
	report_type: test_results
	fail_ci_if_error: false

	# Windows smoke tests only - full test suite times out (see bd-bmev)
	# Linux/macOS run comprehensive tests; Windows just verifies binary works
	#
	# ICU is NOT required on Windows:
	# - go-mysql-server's regex_pure.go (via -tags gms_pure_go) uses Go stdlib regexp
	# - go-icu-regex's regex_windows.go also uses Go stdlib regexp (build tag: windows)
	# - The only CGO deps on Windows are runtime/cgo and gozstd (bundled C source)
	test-windows:
	name: Test (Windows - smoke)
	runs-on: windows-latest
	steps:
	- uses: actions/checkout@v6

	- name: Set up Go
	uses: actions/setup-go@v6
	with:
	go-version-file: 'go.mod'

	- name: Configure Git
	run: \|
	git config --global user.name "CI Bot"
	git config --global user.email "ci@beads.test"

	- name: Build (no CGO, pure Go)
	run: \|
	$env:CGO_ENABLED="0"
	go build -v -tags gms_pure_go -o bd.exe ./cmd/bd

	- name: Smoke test - version
	run: ./bd.exe version

	- name: Smoke test - help
	run: ./bd.exe help

	fmt-check:
	name: Check formatting
	runs-on: ubuntu-latest
	steps:
	- uses: actions/checkout@v6

	- name: Set up Go
	uses: actions/setup-go@v6
	with:
	go-version-file: 'go.mod'

	- name: Check gofmt
	run: make fmt-check

	lint:
	name: Lint
	runs-on: ubuntu-latest
	steps:
	- uses: actions/checkout@v6

	- name: Set up Go
	uses: actions/setup-go@v6
	with:
	go-version-file: 'go.mod'

	- name: Install ICU4C (Linux)
	run: \|
	sudo apt-get update
	sudo apt-get install -y libicu-dev

	- name: golangci-lint
	uses: golangci/golangci-lint-action@v9
	with:
	version: latest
	args: --timeout=5m

	test-nix:
	name: Test Nix Flake
	runs-on: ubuntu-latest
	# Allow failure until nixpkgs updates Go to 1.25.6+
	# (dolthub/driver requires go 1.25.6, nixpkgs-unstable has go 1.25.1)
	continue-on-error: true
	steps:
	- uses: actions/checkout@v6
	- uses: cachix/install-nix-action@v31
	with:
	nix_path: nixpkgs=channel:nixos-unstable
	- name: Run bd help via Nix
	id: nix_help
	continue-on-error: true
	run: \|
	export BEADS_DB="$PWD/.ci-beads/beads.db"
	mkdir -p "$(dirname "$BEADS_DB")"
	rm -rf .beads
	nix run .#default -- --db "$BEADS_DB" init --quiet --prefix ci
	nix run .#default -- --db "$BEADS_DB" > help.txt
	- name: Verify help text
	if: steps.nix_help.outcome == 'success'
	run: \|
	FIRST_LINE=$(head -n 1 help.txt)
	EXPECTED="Issues chained together like beads. A lightweight issue tracker with first-class dependency support."
	if [ "$FIRST_LINE" != "$EXPECTED" ]; then
	echo "First line of help.txt doesn't match expected output"
	echo "Expected: $EXPECTED"
	echo "Got: $FIRST_LINE"
	exit 1
	fi
	echo "Help text first line is correct"
	- name: Note soft-failed Nix run
	if: steps.nix_help.outcome != 'success'
	run: echo "Nix run is non-blocking until nixpkgs toolchain catches up; skipping help-text assertion."

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: CLI docs auto-generation with bd help --doc/--list/--all #7253

Workflow file

feat: CLI docs auto-generation with bd help --doc/--list/--all #7253

Uh oh!

Workflow file for this run