From df3fd90c15c185f64de1b6d013695a70c3c71292 Mon Sep 17 00:00:00 2001 From: Ramesh Padmanabhaiah <22363102+codeforester@users.noreply.github.com> Date: Thu, 8 Oct 2026 10:59:44 +0530 Subject: [PATCH] docs: add expected output and troubleshooting guidance --- CHANGELOG.md | 5 +- README.md | 112 ++++++++++++++++++++++++++++++++++++++-- tests/docs-contracts.sh | 9 ++++ tests/docs-examples.sh | 30 +++++++++++ 4 files changed, 152 insertions(+), 4 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index b171f5e..e842d3a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,7 +7,10 @@ and versions are tracked in the repo-root `VERSION` file. ## [Unreleased] -No unreleased changes yet. +### Documentation + +- Documented stable quick-start output, the informational collection log, and + troubleshooting for Bash setup, output collisions, and modified bundles. ## [0.1.1] - 2026-10-08 diff --git a/README.md b/README.md index d4ffbc4..3de43f2 100644 --- a/README.md +++ b/README.md @@ -70,6 +70,110 @@ directory before repeating the real collection, or select an unused destination: `collect --dry-run` creates neither the output directory nor temporary application state beneath it. +### Expected output + +The paths, branch name, framework commit, and timestamps vary by checkout. The +stable lines below are the useful contract to compare with a terminal session: + +`./bin/beacon --help` includes: + +```text +Offline support-bundle collector +Commands: + status Show fixture and framework readiness + plan Describe bundle inputs and redactions + collect Create a redacted support bundle + verify Verify a collected support bundle +``` + +`./bin/beacon status` reports the consumer and the immutable framework identity: + +```text +application=beacon +workspace_ready=yes +selected_files=3 +framework_version= +framework_provenance=release-artifact +``` + +`./bin/beacon plan` reports the selected inputs and redaction policy without +creating a bundle: + +```text +operation=collect +selected_files=3 +inputs=config/app.env,logs/app.log,system/info.txt +redact_keys=TOKEN,SECRET,PASSWORD +include=config/app.env +include=logs/app.log +include=system/info.txt +``` + +`./bin/beacon collect --dry-run` reports the planned operation and does not +write the destination: + +```text +dry_run=true +operation=collect +selected_files=3 +``` + +Successful `./bin/beacon collect` reports the bundle and checksum manifest: + +```text +bundle= +manifest=/MANIFEST.sha256 +``` + +Successful `./bin/beacon verify --output ` reports: + +```text +verified=true +files=4 +bundle= +``` + +On a normal, non-quiet collection, the vendored `file` module may also emit an +`INFO` line while it updates the bundle README section. That line includes a +temporary path and a framework source location, so both are intentionally +environment-specific; it is informational, not a failure. Use `--quiet` when +only the stable machine-readable result is wanted. + +## Troubleshooting + +### The launcher cannot find a supported Bash + +Beacon requires Bash 4.2.53 or newer. On macOS, install the Homebrew Bash +formula and ask Base to diagnose the project setup: + +```bash +brew install bash +base-bash check --project . +``` + +Run the check from this repository. It confirms the launcher and framework +setup without changing Beacon's committed vendor. + +### Collection refuses to overwrite an output directory + +Collection never overwrites an existing destination. Choose a new path, or +remove only a bundle that you own before retrying: + +```bash +./bin/beacon collect --output /tmp/my-beacon-bundle-2 +``` + +### Verification reports a checksum mismatch + +The bundle is immutable after collection. If a file under `files/` was edited, +`verify` exits non-zero with `ERROR: Manifest checksum mismatch.` Collect again +to a new destination rather than editing the existing bundle: + +```bash +./bin/beacon collect --output /tmp/my-beacon-bundle-fixed +./bin/beacon verify --output /tmp/my-beacon-bundle-fixed +``` + For a scenario-driven walkthrough whose commands are exercised by CI, follow [Beacon in five minutes](docs/five-minute-tutorial.md). @@ -147,9 +251,11 @@ Base Bash version. From a clean checkout whose `VERSION` matches the requested version, build and verify the deterministic four-file artifact set locally: ```bash -./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 +release_version=X.Y.Z +release_output=/tmp/beacon-release-$release_version +./scripts/release-artifact build --version "$release_version" --output "$release_output" +./scripts/release-artifact verify "$release_output" +./scripts/release-artifact verify "$release_output" --trusted-smoke ``` The output contains the standalone archive, SHA-256 manifest, SPDX SBOM, and diff --git a/tests/docs-contracts.sh b/tests/docs-contracts.sh index 8ac6333..4b816de 100755 --- a/tests/docs-contracts.sh +++ b/tests/docs-contracts.sh @@ -19,6 +19,15 @@ grep -Fq '[adoption decision guide](should-i-use-base-bash-libs.md)' "$docs_cont grep -Fq '[five-minute Beacon tutorial](five-minute-tutorial.md)' "$docs_contract_decision" grep -Fq '[Beacon documentation and recommended reading path](docs/README.md)' "$docs_contract_readme" grep -Fq '[use Base Bash in your project](docs/use-in-your-project.md)' "$docs_contract_readme" +grep -Fq '### Expected output' "$docs_contract_readme" +grep -Fq '## Troubleshooting' "$docs_contract_readme" +grep -Fq 'framework_provenance=release-artifact' "$docs_contract_readme" +grep -Fq 'dry_run=true' "$docs_contract_readme" +grep -Fq 'verified=true' "$docs_contract_readme" +grep -Fq 'brew install bash' "$docs_contract_readme" +grep -Fq 'base-bash check --project .' "$docs_contract_readme" +grep -Fq 'ERROR: Manifest checksum mismatch.' "$docs_contract_readme" +grep -Fq "Use \`--quiet\` when" "$docs_contract_readme" grep -Fq '## Code-level before and after' "$docs_contract_why" grep -Fq 'BEGIN BEFORE AFTER CLI' "$docs_contract_why" grep -Fq 'BEGIN BEFORE AFTER CLEANUP' "$docs_contract_why" diff --git a/tests/docs-examples.sh b/tests/docs-examples.sh index e10e5d0..3b1f00b 100755 --- a/tests/docs-examples.sh +++ b/tests/docs-examples.sh @@ -5,9 +5,11 @@ set -euo pipefail docs_root="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")/.." && pwd -P)" tutorial="$docs_root/docs/five-minute-tutorial.md" example_script="$(mktemp "${TMPDIR:-/tmp}/beacon-docs-example.XXXXXX")" +output_root="$(mktemp -d "${TMPDIR:-/tmp}/beacon-docs-output.XXXXXX")" cleanup() { rm -f "$example_script" + rm -rf "$output_root" } trap cleanup EXIT @@ -29,6 +31,34 @@ shellcheck --shell=bash "$example_script" ( cd -- "$docs_root" /usr/bin/env bash "$example_script" + + ./bin/beacon --help > "$output_root/help.txt" + grep -Fq 'Offline support-bundle collector' "$output_root/help.txt" + grep -Fq 'Commands:' "$output_root/help.txt" + grep -Fq ' collect Create a redacted support bundle' "$output_root/help.txt" + + ./bin/beacon status > "$output_root/status.txt" + grep -Fxq 'application=beacon' "$output_root/status.txt" + grep -Fxq 'workspace_ready=yes' "$output_root/status.txt" + grep -Fxq 'framework_provenance=release-artifact' "$output_root/status.txt" + + ./bin/beacon plan --output "$output_root/plan" > "$output_root/plan.txt" + grep -Fxq 'operation=collect' "$output_root/plan.txt" + grep -Fxq 'redact_keys=TOKEN,SECRET,PASSWORD' "$output_root/plan.txt" + grep -Fxq 'include=config/app.env' "$output_root/plan.txt" + + ./bin/beacon collect --dry-run --output "$output_root/dry-run" > "$output_root/dry-run.txt" + grep -Fxq 'dry_run=true' "$output_root/dry-run.txt" + grep -Fxq 'operation=collect' "$output_root/dry-run.txt" + [[ ! -e "$output_root/dry-run" ]] + + ./bin/beacon collect --output "$output_root/collect" > "$output_root/collect.txt" 2> "$output_root/collect.err" + grep -Fxq "bundle=$output_root/collect" "$output_root/collect.txt" + grep -Fxq "manifest=$output_root/collect/MANIFEST.sha256" "$output_root/collect.txt" + + ./bin/beacon verify --output "$output_root/collect" > "$output_root/verify.txt" + grep -Fxq 'verified=true' "$output_root/verify.txt" + grep -Fxq 'files=4' "$output_root/verify.txt" ) /usr/bin/env bash "$docs_root/tests/docs-before-after.sh"