base-bash-libs-demo

Reference consumer and learning application for base-bash-libs.

This repository contains Beacon, a small offline support-bundle collector. It shows how a real Bash application can consume the released Base Bash v2 API while keeping its own commands, fixture schema, collection policy, redaction rules, and user-facing messages.

Beacon does not require Base, Docker, cloud credentials, or network access at runtime. The verified base-bash-libs v2.0.0 release bundle is committed under vendor/base-bash-libs, so a fresh clone has everything it needs.

Start here

• Base Bash overview
• Versioned documentation map
• Five-minute v2 quickstart
• Generated public API reference
• Beacon documentation and recommended reading path

To move directly from evaluation to a small application, follow use Base Bash in your project. It contains a copy-pasteable one-command consumer and both vendored and Homebrew launch paths.

Why base-bash-libs?

Non-trivial Bash tools repeatedly rebuild the same infrastructure: consistent commands and help, configuration precedence, temporary-directory cleanup, signal-safe lifecycle handling, checked filesystem operations, and portable package identity. Base Bash supplies those reusable contracts so an application can concentrate on its own policy.

Beacon makes that division concrete. Base Bash declares and runs the CLI, loads typed configuration, owns cleanup registration, and exposes immutable framework identity. Beacon decides which support files matter, how their data must be redacted, and what collection and verification mean. See why Base Bash for the code-level before/after and the boundaries that remain application-owned. If you are evaluating it for your own project, read should I use Base Bash? for prerequisites, adoption costs, alternatives, and maturity signals.

Quick start

Use Bash 4.2 or newer. On macOS, install a supported Bash with Homebrew; the vendored launcher discovers it automatically.

./bin/beacon --help
./bin/beacon status
./bin/beacon plan
./bin/beacon collect --dry-run
./bin/beacon collect
./bin/beacon verify

The default input is the deterministic fixture in fixtures/workspace. Real collection writes only to .beacon-output/beacon-support. Remove that directory before repeating the real collection, or select an unused destination:

./bin/beacon collect --output /tmp/my-beacon-bundle
./bin/beacon verify --output /tmp/my-beacon-bundle

collect --dry-run creates neither the output directory nor temporary application state beneath it.

For a scenario-driven walkthrough whose commands are exercised by CI, follow Beacon in five minutes.

For deterministic success, failure, interruption, cleanup, redaction, and non-interactive examples, see lifecycle and automation scenarios.

What Beacon demonstrates

• beacon status reports fixture readiness, the consumer Git branch, and the immutable framework version, commit, dirty state, and provenance.
• beacon plan lists the relative inputs, output location, and redaction policy without changing the filesystem.
• beacon collect copies selected fixture files into a support directory, replaces values whose keys contain TOKEN, SECRET, or PASSWORD, and writes a checksum manifest without absolute developer-machine paths.
• beacon verify checks every manifest entry and confirms that configured fixture secrets are absent from the collected payload.
• --workspace, --output, --config, --user-config, --quiet, --verbose, --dry-run, and --non-interactive compose application policy with the Base Bash lifecycle.
• collect --scenario failure|interrupt and --lifecycle-log provide safe, machine-readable evidence for failure and cleanup demonstrations.

Framework boundary

Base Bash owns argument parsing, standard application options, typed configuration, lifecycle hooks, logging, cleanup, safe filesystem helpers, Git inspection, and immutable package identity. Beacon owns which files form a support bundle, which fixture keys are sensitive, the manifest format, and the meaning of status, plan, collect, and verify.

The application imports only modules listed in the released public v2 API. It does not source a sibling checkout or inspect unpublished framework functions.

Immutable dependency

base-bash-libs.lock records the human-readable version, full release commit, canonical asset digest, and bundle-manifest digest. vendor/evidence preserves the release checksum manifest, provenance, and SPDX SBOM. Verify the committed package independently:

./scripts/verify-vendor

The default application path is completely offline. Downloading or changing a framework release belongs to a reviewed dependency-update change, not runtime.

Development

Install BATS and ShellCheck, then run the full gate:

./tests/validate.sh

CI runs the full suite on Ubuntu and macOS with Homebrew Bash, plus a network-disabled smoke test on the exact minimum Bash 4.2.53 runtime.

Standalone release artifacts

Beacon has its own version and release lifecycle, independent of the embedded Base Bash version. From a clean checkout whose VERSION matches the requested version, build and verify the deterministic four-file artifact set locally:

./scripts/release-artifact build --version 0.1.0 --output /tmp/beacon-release
./scripts/release-artifact verify /tmp/beacon-release
./scripts/release-artifact verify /tmp/beacon-release --trusted-smoke

The output contains the standalone archive, SHA-256 manifest, SPDX SBOM, and SLSA-style provenance. Default verification does not execute payload code; the --trusted-smoke option explicitly runs checks from a trusted artifact. Internal consistency is not proof of publisher authenticity. The archive carries both Beacon source identity and the distinct vendored framework identity. These commands do not tag, publish, or use the network; release publication always requires a separate authorized maintainer action. See the release process.

Framework compatibility

The scheduled and manually dispatched Framework Compatibility workflow tests an explicit Base Bash release tag or full commit without changing Beacon's committed default package. The same black-box contract is available locally:

./tests/candidate-smoke.sh /path/to/base-bash-libs-candidate

See framework compatibility and pin updates for the immutable-input rules, reviewed pin-update procedure, and rollback path.

Repository shape

• bin/beacon selects the committed Base Bash launcher.
• lib/beacon.sh contains the consumer-owned CLI and application policy.
• fixtures/workspace provides deterministic, intentionally fake inputs.
• examples/minimal-cli is the tested smallest runnable CLI consumer.
• vendor/base-bash-libs is the verified v2.0.0 release bundle.
• tests/beacon.bats exercises the installed application boundary.
• tests/lifecycle.bats exercises failure, signals, cleanup, automation, and hostile synthetic fixture data.
• tests/docs-examples.sh executes the exact five-minute tutorial commands.
• tests/docs-contracts.sh checks adoption-document links and API evidence.
• tests/minimal-consumer.sh runs the starter through the vendored launcher.
• scripts/release-artifact builds and verifies standalone release evidence.
• tests/validate.sh verifies the vendor, shell quality, tests, and smoke path.

Base

This repository is managed by Base.

Common commands:

basectl setup base-bash-libs-demo
basectl check base-bash-libs-demo
basectl doctor base-bash-libs-demo
basectl test base-bash-libs-demo

Base manages this repository's development workflow. It is not a Beacon or Base Bash runtime dependency.