* fix(winget): require PortableCommandAlias for GasTownHall.Beads
GasTownHall.Beads 1.1.0 on winget-pkgs only sets Commands: (search
metadata) and never creates WinGet\Links\bd.exe, so already-running
shells never see bd after install (GH#4908).
- Add canonical GasTownHall.Beads.installer.yaml with PortableCommandAlias
- update-winget.sh regenerates that package id for new releases
- Document both package ids and the Links requirement in winget/README
- Add check-winget-portable-alias.sh guard
Fixes#4908
* fix(winget): address maphew's PR #5134 review (grep bug, guard, CI wiring)
Maintainer commits requested by the PR author on the reviewer's behalf,
addressing maphew's 2026-07-29 review of PR #5134:
- scripts/update-winget.sh: `grep windows` matched both amd64 and arm64
checksum lines, corrupting InstallerSha256 into an unparseable
two-line value. Narrow to `grep windows_amd64` (mirrors the existing
arm64 grep on the next block).
- scripts/update-winget.sh: quote the arm64 InstallerSha256 placeholder
so 64 bare zero digits don't parse as a YAML integer, matching the
quoting already used in the checked-in SteveYegge.beads.installer.yaml.
- scripts/check-winget-portable-alias.sh: replace the bare
`grep -q PortableCommandAlias:` substring check with a yq-based parse,
so a corrupted manifest (like the one above) fails the guard instead
of reporting OK; also fail closed on an empty winget/ glob instead of
silently exiting 0.
- .github/workflows/pr.yml, main.yml: run the guard in the existing
check-build-tags job so it executes on every PR instead of only when
someone remembers to invoke it by hand.
Locally verified: guard passes against the current checked-in
manifests, fails against a reproduction of the exact grep-bug
corruption, fails on an empty winget/ dir, and the generator produces
a yq-parseable manifest against a synthetic checksums.txt. shellcheck
clean; both workflow files parse as valid YAML.
* fix(winget): harden the PortableCommandAlias guard and its release docs
Maintainer review fixups for the adopt-pr review of PR #5134 (iteration 1,
synthesis approve / 0 blockers and 0 majors; all seven items were non-gating).
Scorecard 961/1000, Required Changes: None. Every edit site below is a line
this PR itself added.
Finding 1 (minor, Error Handling) — `yq -e ... >/dev/null 2>&1` collapsed three
distinct failures (yq absent at exit 127, unparseable manifest, alias genuinely
missing) into "missing valid PortableCommandAlias", defeating the script's own
stated rationale and pointing a debugger at manifests that are already correct.
The guard now names a missing yq up front and no longer discards stderr, so
yq's own diagnostic reaches the log of a required-gate job. yq is CI's first and
only yq consumer, running in a bare actions/checkout job, and sits outside the
host-tools inventory declared in scripts/BUILD.bazel; that is now stated where
the dependency lives.
Finding 4 (minor, Change Impact) — the glob is winget/*.installer.yaml but the
assertion was unconditional on installer type, so a future msi/exe/msix
manifest (no NestedInstallerFiles at all) would hard-fail a gate-feeding job
with no opt-out. Non-portable manifests are now classified out with a SKIP line.
The parse check deliberately precedes the class check: without that ordering an
unparseable manifest fails the NestedInstallerType test and is silently skipped
as "not portable", which is strictly worse than the behaviour being fixed.
Finding 2 (minor, Error Handling) — amd64 and arm64 had opposite failure
policies in one script: a missing amd64 checksum hard-fails, while a missing
arm64 checksum substituted 64 zeros and continued to success, disclosed only in
a source comment. The echoed "Next steps" block now ends in a loud
"DO NOT PUBLISH" warning naming the placeholder, emitted only when the fallback
actually fires.
The finding's second arm — "teach the guard to reject an all-zero
InstallerSha256" — is implemented as a WARNING rather than a failure, and
that is a deliberate downgrade. winget/SteveYegge.beads.installer.yaml:15
already carries exactly that placeholder for its arm64 entry; that file is
base-owned and is not in this PR's six-file diff, so a fatal tripwire would
turn a required check red over pre-existing content the PR never touched.
The legacy heredoc in update-winget.sh emits no arm64 entry at all, so the
placeholder is stale hand-authored state that the next generator run removes.
Verified: the guard still exits 0 on the real tree and reports the warning.
Finding 3 (minor, Contract & Interface Fidelity) — a winget-pkgs version
directory needs a version + defaultLocale + installer set, but the repo carries
only GasTownHall.Beads.installer.yaml, so README step 2 as written produced a
set winget-pkgs validation rejects. Took the documentation arm: GasTownHall is
now steered to `wingetcreate update` (which supplies the other two manifests
from the published set) and the hand-copy path is marked as applying only to
the legacy id, which does have a complete three-file set. Generating two more
manifests would have changed the contribution's deliverable scope.
Finding 5 (nit, Architectural Consistency) — the first update-winget.sh run
overwrote the checked-in manifest with a three-line header, deleting this PR's
own GH#4908 rationale from the artifact whose purpose is to carry it. The
heredoc now emits the same header, plus a fresh ReleaseDate. Verified by
generating into a temp tree: the generated header is byte-identical to the
checked-in file's first ten lines.
Finding 6 (nit, Documentation Accuracy) — the README froze SteveYegge.beads at
the "0.30.x era" while the script rewrites all three of its manifests to the
new version. Note that the section already disclosed that both ids are
refreshed, so the residual gap was narrower than the finding stated: what was
missing is that the legacy id's version is bumped out of the era the table
advertises. That clause is now explicit.
Finding 7 (nit, Test Evidence Quality) — the guard's fail-closed behaviour was
pinned by nothing in-repo. Adds scripts/check_winget_portable_alias_test.go
with ten cases: alias present, alias missing, wrong alias, empty winget dir,
unparseable manifest (asserting it is neither skipped nor misreported and that
yq's stderr survives), missing yq, a skipped non-portable manifest, a violating
portable sibling of a skipped manifest, and the advisory placeholder warning.
Deviates from the prescribed `requireHostTool(t, "yq")` on purpose.
requireHostTool fails rather than skips under Bazel because
//scripts:scripts_test is tagged host-tools, and that tag's declared
inventory is "git, python3, awk, sed, find, grep and timeout" — yq is not in
it, so the prescription would red the shared target on hosts that keep the
promise the tag actually makes. A skip-only gate is used and the reason is
recorded at the helper. Fixtures are synthetic so the target needs no new
data dependency; the real manifests are covered by the check-build-tags job,
which runs this script against the actual checkout.
Also fixed, found while editing and not raised by either lane: winget/README.md
told readers to run `grep windows` over checksums.txt, which is the exact
two-line ambiguity this PR fixed in the script (`grep windows` ->
`grep windows_amd64`). Before this PR the script and doc agreed; after it they
diverged, so the PR created the inconsistency. The doc now uses `grep windows_`
and says which line feeds which architecture.
Validation. `git diff --check` clean. The guard runs green on the real tree
(both manifests OK, rc=0) and on a freshly generated tree. go test ./scripts/
ok 21.7s (the package whose tests pin workflow content). Each new pin was
proven non-vacuous by reverting the corresponding fix and confirming the test
reds: dropping the class check reds the non-portable case; dropping the
placeholder tripwire reds the warning case; dropping the parse-before-classify
check reds the unparseable case; dropping the yq preflight reds the missing-yq
case; restoring `2>&1` reds the stderr assertion. All five arms red, and the
guard was restored byte-identical (md5 verified) after each. The arm64 warning
was exercised both ways against a stubbed curl: present arm64 checksum emits no
warning, absent one emits DO NOT PUBLISH.
New yq expressions stay inside the vocabulary shared by mikefarah yq v4 (what
ubuntu-latest ships) and python-yq/jq — identity, `==`, `[]`, `select` and
`-e`'s exit status — because only the pre-existing expression had been proven
green on mikefarah in CI, and this host has python-yq. Builtins the two flavours
spell differently (jq's `any(cond)` vs mikefarah's `any_c`) are avoided, and the
placeholder tripwire uses grep precisely because it looks for a known-bad
literal and so can only miss a bad value, never report OK on a manifest it
failed to parse.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---------
Co-authored-by: Bee <bee@ghosttrack.com>
Co-authored-by: Gas City Adopt-PR <adopt-pr@gascity.local>
Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
Co-authored-by: Eddie the Engineer <adopt-pr@gascity.com>
Beads' storage backend is Dolt, not git. Git integration (hooks, repo
discovery, identity) is optional — `BEADS_DIR` + `--stealth` provides
fully functional git-free operation with zero git calls.
Changes across 15 files:
- Replace all "git-backed" references with "Dolt-powered" or "Dolt-backed"
- Add "Git-Free Usage" section to README.md documenting BEADS_DIR + --stealth
- Fix stale "JSONL" storage reference in llms-full.txt
- Update SKILL.md to mark git as optional prerequisite
Complements GH#2522 (stale command cleanup) — that PR fixed removed
commands, this one fixes misleading storage backend framing.
Adds winget manifest files for publishing beads to Windows Package Manager:
- winget/SteveYegge.beads.yaml (version manifest)
- winget/SteveYegge.beads.installer.yaml (installer config)
- winget/SteveYegge.beads.locale.en-US.yaml (package metadata)
- scripts/update-winget.sh (helper script for updating manifests)
Once submitted to microsoft/winget-pkgs, users can install with:
winget install SteveYegge.beads
The update-winget.sh script automates manifest updates for new releases.
Closes#524🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>