Relocate contributor- and maintainer-facing material out of docs/ so the directory can become the user-facing Mintlify site. Moves preserve subpaths (adr/, design/, staged-for-removal/ intact). messaging.md, UI_PHILOSOPHY.md, and AGENT_SIGNING.md move per their DOC_INVENTORY dispositions (design doc, design philosophy, maintainer convention). Inbound links updated repo-wide: root guides, CONTRIBUTING, AGENTS, workflows, lint config, scripts (check-doc-freshness now resolves the inventory at engdocs/DOC_INVENTORY.md), Go comments, and the synced website metadata page (regenerated via sync-website-docs.sh + generate-llms-full.sh). The emitted help text in cmd/bd/init_safety_help.go still references docs/adr/0002-init-safety-invariants.md; changing it would change bd's runtime output, which is out of scope for this branch (flagged in the PR).
166 lines
8.3 KiB
Markdown
166 lines
8.3 KiB
Markdown
# Noridoc: scripts
|
|
|
|
Path: @/scripts
|
|
|
|
### Overview
|
|
|
|
The `scripts` directory contains build and release automation utilities for the beads project. These scripts handle version management, installation with embedded build info, and release orchestration across multiple distribution channels.
|
|
|
|
Key scripts include version bumping, installation helpers that inject git information at build time, and release coordination across GitHub, Homebrew, PyPI, and npm.
|
|
|
|
## generate-cli-docs.sh
|
|
|
|
Generates maintained CLI reference docs from the live Cobra command tree exposed by `bd help`.
|
|
|
|
### Usage
|
|
|
|
```bash
|
|
# Regenerate checked-in CLI docs using a temporary no-cgo build
|
|
./scripts/generate-cli-docs.sh
|
|
|
|
# Regenerate the live docs and one release snapshot
|
|
./scripts/generate-cli-docs.sh --versioned 1.0.5
|
|
|
|
# Regenerate/check against an existing binary
|
|
./scripts/generate-cli-docs.sh ./bd
|
|
./scripts/generate-cli-docs.sh --check ./bd
|
|
```
|
|
|
|
### Outputs
|
|
|
|
- `docs/CLI_REFERENCE.md` from the live Cobra command tree
|
|
- `website/docs/cli-reference/*.md` from the live Cobra command tree
|
|
- `website/versioned_docs/version-X.Y.Z/cli-reference/*.md` only when `--versioned X.Y.Z` is supplied by the release snapshot workflow
|
|
- `website/static/llms-full.txt` freshness is checked from the same generated website docs tree
|
|
|
|
`scripts/check-doc-flags.sh` runs the `--check` mode in CI and fails when live top-level commands are missing from live generated docs or `llms-full.txt` is stale. Historical Docusaurus CLI snapshots are release artifacts; ordinary PR checks do not rewrite them to match unreleased commands.
|
|
|
|
## check-docs-version.sh
|
|
|
|
Validates the released Docusaurus docs metadata:
|
|
|
|
- `website/versions.json` latest entry and `website/docusaurus.config.ts` `lastVersion` agree
|
|
- the matching `website/versioned_docs/version-X.Y.Z` and sidebar snapshot exist
|
|
- the versioned CLI reference label matches the latest released docs snapshot
|
|
- `website/static/llms-full.txt` is sourced from the latest released snapshot
|
|
|
|
Default CI mode does not require the latest released docs snapshot to equal
|
|
`cmd/bd/version.go`, because a version bump may land before the release is cut.
|
|
Use `BEADS_REQUIRE_RELEASE_DOCS=1 ./scripts/check-docs-version.sh`, or run from a
|
|
`v*` tag, for release preflight mode where the docs snapshot must match the
|
|
current binary version.
|
|
|
|
## check-doc-freshness.sh
|
|
|
|
Validates marker-based freshness for reference-shaped docs that are not generated from a single clean source.
|
|
|
|
### Usage
|
|
|
|
```bash
|
|
./scripts/check-doc-freshness.sh
|
|
make check-docs
|
|
```
|
|
|
|
The script currently checks the reference docs named in `engdocs/DOC_INVENTORY.md`: `CONFIG.md`, `SETUP.md`, `ADO_CONFIG.md`, `JSON_SCHEMA.md`, `RECOVERY.md`, `ERROR_HANDLING.md`, `LINTING.md`, and `design/otel/otel-data-model.md`. Each doc must be listed in the inventory, include a recent `Last reviewed:` marker, include a `Freshness source:` marker, and name source paths or globs that exist in the repository.
|
|
|
|
Set `DOC_FRESHNESS_MAX_AGE_DAYS` to override the default 90-day review window. Set `DOC_FRESHNESS_TODAY=YYYY-MM-DD` when testing date behaviour.
|
|
|
|
### How it fits into the larger codebase
|
|
|
|
- **Build Integration**: The `install.sh` script is referenced in documentation and release processes as the primary user-facing installation mechanism. It integrates directly with the Go build system to ensure full version information is embedded.
|
|
|
|
- **Version Pipeline**: Works alongside the version infrastructure in `@/cmd/bd/version.go` by extracting and passing git information at build time via ldflags.
|
|
|
|
- **Release Automation**: The `release.sh` and `bump-version.sh` scripts orchestrate the release process documented in `@/RELEASING.md`, ensuring version consistency across all components (CLI, plugin, MCP server, npm package).
|
|
|
|
- **CI/CD Integration**: Goreleaser (configured in `@/.goreleaser.yml`) uses the same ldflag patterns established by these scripts, ensuring consistency across all installation methods.
|
|
|
|
- **Multi-Channel Distribution**: These scripts ensure that whether a user installs via Homebrew, npm, GitHub releases, or direct `go install`, they get consistent version reporting with full git information.
|
|
|
|
### Core Implementation
|
|
|
|
**install.sh** (GitHub issue #503 fix):
|
|
|
|
The script simplifies local installation from source while ensuring full version information is available in the resulting binary:
|
|
|
|
1. **Usage** (lines 1-6):
|
|
- Can be invoked from source checkout with optional custom install directory
|
|
- `./scripts/install.sh` installs to `$(go env GOPATH)/bin`
|
|
- `./scripts/install.sh /usr/local/bin` installs to custom location
|
|
|
|
2. **Git Information Extraction** (lines 12-14):
|
|
- Extracts full commit hash via `git rev-parse HEAD`
|
|
- Extracts branch name via `git rev-parse --abbrev-ref HEAD`
|
|
- Gracefully handles missing git info (returns empty strings in non-git environments)
|
|
|
|
3. **Build Information Display** (lines 16-18):
|
|
- Shows user where installation will occur
|
|
- Displays the 12-character short commit hash
|
|
- Displays the branch name for context
|
|
|
|
4. **Installation with Ldflags** (line 20):
|
|
- Calls `go install` with explicit `-ldflags` to set `main.Commit` and `main.Branch`
|
|
- These ldflags inject values that are then picked up by `resolveCommitHash()` and `resolveBranch()` in `@/cmd/bd/version.go`
|
|
|
|
5. **Post-Install Verification** (lines 22-24):
|
|
- Immediately runs `bd version` to show the user that installation succeeded
|
|
- User sees commit and branch info in the output, confirming full version info is present
|
|
|
|
**Makefile Integration** (`@/Makefile`, lines 37-41):
|
|
|
|
The Makefile's `install` target uses identical logic:
|
|
- Extracts git info at build time
|
|
- Passes to `go install` via ldflags
|
|
- Ensures that standard `make install` produces binaries with full version info, not just `make build`
|
|
|
|
**Goreleaser Configuration** (`@/.goreleaser.yml`):
|
|
|
|
All 5 platform builds (linux-amd64, linux-arm64, darwin-amd64, darwin-arm64, windows-amd64) use goreleaser's built-in git variables:
|
|
- `-X main.Commit={{.Commit}}` uses goreleaser's detected commit
|
|
- `-X main.Branch={{.Branch}}` uses goreleaser's detected branch
|
|
- Ensures released binaries have full version info without requiring manual extraction
|
|
|
|
**Version Bumping** (`bump-version.sh` and `release.sh`):
|
|
|
|
- Coordinates version updates across multiple files (CLI version, plugin metadata, MCP server, npm package)
|
|
- Ensures all distribution channels report consistent version numbers
|
|
- Integrates with release process documented in `@/RELEASING.md`
|
|
|
|
### Things to Know
|
|
|
|
**Why Explicit Ldflags Are Necessary**:
|
|
- `go install` does not automatically embed VCS information like `go build` does (even though Go supports it)
|
|
- Without explicit ldflags, binaries lack commit and branch information regardless of installation method
|
|
- The Makefile and goreleaser configurations compensate for this limitation
|
|
|
|
**Installation Path Resolution**:
|
|
- The script uses `$(go env GOPATH)/bin` as the default installation target
|
|
- This respects the user's Go configuration and matches standard Go tooling behavior
|
|
- Allows overriding for system-wide installations (e.g., `/usr/local/bin`)
|
|
|
|
**Git Information Fallbacks**:
|
|
- The script silently handles missing git info (returns empty strings)
|
|
- This allows installation in non-git environments or git-less distributions
|
|
- The version command in `@/cmd/bd/version.go` has its own fallback chain
|
|
|
|
**Testing the Version Pipeline**:
|
|
- After running `./scripts/install.sh`, users should immediately see full version info via `bd version`
|
|
- The text output shows format like: `bd version 0.29.0 (dev: main@7e70940)`
|
|
- JSON output includes both `commit` and `branch` fields
|
|
|
|
**Release Coordination**:
|
|
- The `install.sh` script is independent of release automation
|
|
- Users can run it locally to build from any source branch
|
|
- Release scripts (`release.sh`, `update-homebrew.sh`) handle orchestration across channels and are documented separately in `@/RELEASING.md`
|
|
|
|
**Platform Compatibility**:
|
|
- All scripts use POSIX shell constructs (bash on all platforms)
|
|
- Git operations work identically on macOS, Linux, and Windows (with Git for Windows)
|
|
- The go install command behaves consistently across all platforms
|
|
|
|
**Security Considerations**:
|
|
- Scripts use `set -e` to fail fast on any errors
|
|
- Git commands are defensive (using `2>/dev/null` to suppress errors)
|
|
- No shell injection risks as git values are passed as structured arguments
|
|
|
|
Created and maintained by Nori.
|