fix(winget): require PortableCommandAlias for GasTownHall.Beads (#5134)

* 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>
This commit is contained in:
Vishnu J 2026-09-30 20:24:59 -07:00 • committed by GitHub
commit 8f195454ef
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
8 changed files with 475 additions and 26 deletions

View file

@ -140,6 +140,7 @@ jobs:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v6
- run: ./scripts/check-build-tags.sh
- run: ./scripts/check-go-install-guidance.sh
- run: ./scripts/check-winget-portable-alias.sh
# Lock in the cgo-test-contamination fix (mybd-ycx / GH#3683 follow-up).
# cmd/bd carries a mix of cgo-only test helpers (embedded Dolt, sql.DB) and

View file

@ -164,6 +164,7 @@ jobs:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v6
- run: ./scripts/check-build-tags.sh
- run: ./scripts/check-go-install-guidance.sh
- run: ./scripts/check-winget-portable-alias.sh
# Lock in two CGO-disabled portability boundaries. cmd/bd carries a mix of
# cgo-only test helpers (embedded Dolt, sql.DB) and pure-Go tests; compiling

View file

@ -23,6 +23,7 @@ go_test(
"check_build_tags_test.go",
"check_doc_freshness_test.go",
"check_testing_short_test.go",
"check_winget_portable_alias_test.go",
"ci_capability_selector_test.go",
"ci_workflow_apt_get_timeout_test.go",
"ci_workflow_test.go",

View file

@ -0,0 +1,71 @@
#!/bin/bash
# Guard: winget installer manifests must set PortableCommandAlias (GH#4908).
# Parses with yq rather than grep so a corrupt/unparseable manifest (e.g. a
# multi-line InstallerSha256 from a checksum-matching bug) fails loudly
# instead of a bare substring match reporting OK.
#
# yq flavour portability: these 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. Avoid builtins the two spell
# differently, e.g. jq's `any(cond)` against mikefarah's `any_c`.
set -euo pipefail
# yq is outside the host-tools inventory declared in scripts/BUILD.bazel and no
# workflow job installs it, so name the missing tool instead of reporting every
# manifest as missing its alias.
if ! command -v yq >/dev/null 2>&1; then
echo "FAIL: yq is required by this guard but is not installed"
exit 1
fi
ROOT="$(cd "$(dirname "$0")/.." && pwd)"
shopt -s nullglob
files=("$ROOT"/winget/*.installer.yaml)
if [ "${#files[@]}" -eq 0 ]; then
echo "FAIL: no winget/*.installer.yaml files found"
exit 1
fi
# The placeholder scripts/update-winget.sh substitutes when a release publishes
# no windows_arm64 checksum.
ZERO_SHA256="0000000000000000000000000000000000000000000000000000000000000000"
fail=0
for f in "${files[@]}"; do
# Parse before classifying. An unparseable manifest has to fail here rather
# than fall through the NestedInstallerType test below and get skipped as
# "not portable". yq's own diagnostic is left on stderr deliberately: the
# point of this guard is that a missing tool or a parse error is
# distinguishable from a missing alias.
if ! yq -e '.' "$f" >/dev/null; then
echo "FAIL: $f is not parseable YAML"
fail=1
continue
fi
# PortableCommandAlias exists only for nested portable installers, so an
# msi/exe/msix manifest added later is outside this guard's class rather than
# in violation of it.
if ! yq -e '.NestedInstallerType == "portable"' "$f" >/dev/null; then
echo "SKIP: $f is not a nested portable installer"
continue
fi
if yq -e '.NestedInstallerFiles[] | select(.PortableCommandAlias == "bd")' "$f" >/dev/null; then
echo "OK: $f has PortableCommandAlias"
else
echo "FAIL: $f missing valid PortableCommandAlias: bd (GH#4908)"
fail=1
fi
# Placeholder-hash tripwire. Advisory, not fatal: the only occurrence in the
# tree today is the arm64 entry of the legacy SteveYegge manifest, which this
# guard does not otherwise gate, so failing would turn a required check red
# over pre-existing content. grep is deliberate here — this looks for a
# known-bad literal, so unlike the alias assertion above it can only miss a
# bad value, never report OK on a manifest it failed to understand.
if grep -Eq "InstallerSha256:[[:space:]]*\"?${ZERO_SHA256}\"?[[:space:]]*\$" "$f"; then
echo "WARNING: $f carries a placeholder all-zero InstallerSha256 — do not publish that entry"
fi
done
exit "$fail"

View file

@ -0,0 +1,255 @@
package scripts_test
import (
"os"
"os/exec"
"path/filepath"
"runtime"
"strings"
"testing"
)
// The guard's own vocabulary is shared between mikefarah yq v4 and python-yq,
// so either flavour exercises these cases. Deliberately a plain skip rather
// than requireHostTool: //scripts:scripts_test is tagged host-tools, and that
// tag's declared inventory (git, python3, awk, sed, find, grep, timeout) does
// not include yq, so failing under Bazel would red the shared target on hosts
// that keep the promise the tag actually makes.
func skipWithoutYQ(t *testing.T) {
t.Helper()
if _, err := exec.LookPath("yq"); err != nil {
t.Skipf("yq not available: %v", err)
}
}
const (
wingetAliasManifest = `PackageIdentifier: Example.Beads
PackageVersion: 1.2.3
InstallerType: zip
NestedInstallerType: portable
NestedInstallerFiles:
- RelativeFilePath: bd.exe
PortableCommandAlias: bd
Installers:
- Architecture: x64
InstallerUrl: https://example.invalid/beads_1.2.3_windows_amd64.zip
InstallerSha256: 12B1D37344D3B1543301E21A2B9ED3AB6AE009F0418441F3DE5F762B40769A6B
ManifestType: installer
ManifestVersion: 1.12.0
`
// No NestedInstallerFiles at all, which is the shape of every non-nested
// installer type. PortableCommandAlias is meaningless here.
wingetMsiManifest = `PackageIdentifier: Example.Beads
PackageVersion: 1.2.3
InstallerType: msi
Installers:
- Architecture: x64
InstallerUrl: https://example.invalid/beads_1.2.3_windows_amd64.msi
InstallerSha256: 12B1D37344D3B1543301E21A2B9ED3AB6AE009F0418441F3DE5F762B40769A6B
ManifestType: installer
ManifestVersion: 1.12.0
`
)
// runWingetAliasGuard runs check-winget-portable-alias.sh against a throwaway
// tree holding the given files. The script resolves the repository from its own
// location, so it is copied in beside a synthetic winget/ directory. The real
// in-tree manifests are covered by the check-build-tags job, which runs this
// same script against the actual checkout.
func runWingetAliasGuard(t *testing.T, files map[string]string) (string, error) {
t.Helper()
if runtime.GOOS == "windows" {
t.Skip("guard is a Bash boundary")
}
skipWithoutYQ(t)
script, err := os.ReadFile(filepath.Join(sourceRepoRoot(t), "scripts", "check-winget-portable-alias.sh"))
if err != nil {
t.Fatalf("read check-winget-portable-alias.sh: %v", err)
}
dir := t.TempDir()
all := map[string]string{"scripts/check-winget-portable-alias.sh": string(script)}
for rel, content := range files {
all[rel] = content
}
for rel, content := range all {
full := filepath.Join(dir, rel)
if err := os.MkdirAll(filepath.Dir(full), 0o700); err != nil {
t.Fatalf("mkdir %s: %v", filepath.Dir(full), err)
}
if err := os.WriteFile(full, []byte(content), 0o600); err != nil {
t.Fatalf("write %s: %v", rel, err)
}
}
cmd := exec.Command("bash", filepath.Join(dir, "scripts", "check-winget-portable-alias.sh"))
cmd.Dir = dir
out, err := cmd.CombinedOutput()
return string(out), err
}
func TestWingetAliasGuardAcceptsPortableManifestWithAlias(t *testing.T) {
out, err := runWingetAliasGuard(t, map[string]string{
"winget/Example.Beads.installer.yaml": wingetAliasManifest,
})
if err != nil {
t.Fatalf("a portable manifest with PortableCommandAlias should pass: %v\n%s", err, out)
}
if !strings.Contains(out, "OK:") {
t.Errorf("expected an OK line, got:\n%s", out)
}
}
func TestWingetAliasGuardRejectsMissingAlias(t *testing.T) {
out, err := runWingetAliasGuard(t, map[string]string{
"winget/Example.Beads.installer.yaml": strings.ReplaceAll(
wingetAliasManifest, " PortableCommandAlias: bd\n", ""),
})
if err == nil {
t.Fatalf("a portable manifest without PortableCommandAlias was accepted:\n%s", out)
}
if !strings.Contains(out, "missing valid PortableCommandAlias") {
t.Errorf("expected the alias diagnostic, got:\n%s", out)
}
}
// The alias must be exactly `bd`; that is the name winget links onto PATH.
func TestWingetAliasGuardRejectsWrongAlias(t *testing.T) {
out, err := runWingetAliasGuard(t, map[string]string{
"winget/Example.Beads.installer.yaml": strings.ReplaceAll(
wingetAliasManifest, "PortableCommandAlias: bd", "PortableCommandAlias: beads"),
})
if err == nil {
t.Fatalf("a manifest aliasing something other than bd was accepted:\n%s", out)
}
if !strings.Contains(out, "missing valid PortableCommandAlias") {
t.Errorf("expected the alias diagnostic, got:\n%s", out)
}
}
func TestWingetAliasGuardRejectsEmptyWingetDir(t *testing.T) {
out, err := runWingetAliasGuard(t, nil)
if err == nil {
t.Fatalf("an empty winget/ directory was accepted:\n%s", out)
}
if !strings.Contains(out, "no winget/*.installer.yaml files found") {
t.Errorf("expected the empty-set diagnostic, got:\n%s", out)
}
}
// An unparseable manifest must be reported as a parse failure rather than
// reported as a missing alias or skipped as a non-portable installer.
func TestWingetAliasGuardRejectsUnparseableManifest(t *testing.T) {
out, err := runWingetAliasGuard(t, map[string]string{
"winget/Example.Beads.installer.yaml": "PackageIdentifier: Example.Beads\n\tInstallerSha256: [unclosed\n",
})
if err == nil {
t.Fatalf("an unparseable manifest was accepted:\n%s", out)
}
if !strings.Contains(out, "is not parseable YAML") {
t.Errorf("expected the parse diagnostic, got:\n%s", out)
}
if strings.Contains(out, "SKIP:") {
t.Errorf("an unparseable manifest must not be skipped as non-portable:\n%s", out)
}
// yq's own stderr has to survive to the log, otherwise a parse error is
// indistinguishable from a missing alias. Matched loosely because the
// wording differs between yq flavours.
if !strings.Contains(strings.ToLower(out), "error") {
t.Errorf("expected yq's own diagnostic to reach the log, got:\n%s", out)
}
}
// A missing yq must be named, not reported as every manifest missing its alias.
func TestWingetAliasGuardNamesMissingYQ(t *testing.T) {
if runtime.GOOS == "windows" {
t.Skip("guard is a Bash boundary")
}
script, err := os.ReadFile(filepath.Join(sourceRepoRoot(t), "scripts", "check-winget-portable-alias.sh"))
if err != nil {
t.Fatalf("read check-winget-portable-alias.sh: %v", err)
}
dir := t.TempDir()
for rel, content := range map[string]string{
"scripts/check-winget-portable-alias.sh": string(script),
"winget/Example.Beads.installer.yaml": wingetAliasManifest,
} {
full := filepath.Join(dir, rel)
if err := os.MkdirAll(filepath.Dir(full), 0o700); err != nil {
t.Fatalf("mkdir %s: %v", filepath.Dir(full), err)
}
if err := os.WriteFile(full, []byte(content), 0o600); err != nil {
t.Fatalf("write %s: %v", rel, err)
}
}
emptyBin := filepath.Join(dir, "emptybin")
if err := os.MkdirAll(emptyBin, 0o700); err != nil {
t.Fatalf("mkdir %s: %v", emptyBin, err)
}
cmd := exec.Command("bash", filepath.Join(dir, "scripts", "check-winget-portable-alias.sh"))
cmd.Dir = dir
// The tool check is bash builtins only, so it still reports with no PATH.
cmd.Env = append(os.Environ(), "PATH="+emptyBin)
out, err := cmd.CombinedOutput()
if err == nil {
t.Fatalf("guard passed with no yq on PATH:\n%s", out)
}
if !strings.Contains(string(out), "yq is required") {
t.Errorf("expected the missing-yq diagnostic, got:\n%s", out)
}
if strings.Contains(string(out), "PortableCommandAlias") {
t.Errorf("a missing tool must not be reported as a missing alias:\n%s", out)
}
}
// PortableCommandAlias is not a field non-nested installers have, so the guard
// must classify them out instead of hard-failing a required job.
func TestWingetAliasGuardSkipsNonPortableInstaller(t *testing.T) {
out, err := runWingetAliasGuard(t, map[string]string{
"winget/Example.Beads.installer.yaml": wingetMsiManifest,
})
if err != nil {
t.Fatalf("a non-portable manifest should not fail the guard: %v\n%s", err, out)
}
if !strings.Contains(out, "SKIP:") {
t.Errorf("expected a SKIP line, got:\n%s", out)
}
}
// Classifying non-portable manifests out must not weaken the guard for the
// portable ones sharing the directory.
func TestWingetAliasGuardStillFailsPortableSiblingOfSkippedManifest(t *testing.T) {
out, err := runWingetAliasGuard(t, map[string]string{
"winget/Example.Msi.installer.yaml": wingetMsiManifest,
"winget/Example.Beads.installer.yaml": strings.ReplaceAll(
wingetAliasManifest, " PortableCommandAlias: bd\n", ""),
})
if err == nil {
t.Fatalf("a violating portable manifest was masked by a skipped sibling:\n%s", out)
}
if !strings.Contains(out, "SKIP:") || !strings.Contains(out, "missing valid PortableCommandAlias") {
t.Errorf("expected both a SKIP and the alias diagnostic, got:\n%s", out)
}
}
// The all-zero hash scripts/update-winget.sh substitutes for a missing
// windows_arm64 checksum is surfaced, but advisory: the legacy SteveYegge
// manifest already carries one, and this guard is not the gate for that.
func TestWingetAliasGuardWarnsButDoesNotFailOnPlaceholderSha256(t *testing.T) {
arm64Entry := ` - Architecture: arm64
InstallerUrl: https://example.invalid/beads_1.2.3_windows_arm64.zip
InstallerSha256: "` + strings.Repeat("0", 64) + `"
ManifestType: installer`
manifest := strings.ReplaceAll(wingetAliasManifest, "ManifestType: installer", arm64Entry)
if !strings.Contains(manifest, "arm64") {
t.Fatalf("fixture did not gain an arm64 installer entry:\n%s", manifest)
}
out, err := runWingetAliasGuard(t, map[string]string{
"winget/Example.Beads.installer.yaml": manifest,
})
if err != nil {
t.Fatalf("the placeholder tripwire must stay advisory: %v\n%s", err, out)
}
if !strings.Contains(out, "placeholder all-zero InstallerSha256") {
t.Errorf("expected the placeholder warning, got:\n%s", out)
}
}

View file

@ -23,7 +23,7 @@ WINGET_DIR="$SCRIPT_DIR/../winget"
# Get SHA256 from release checksums
echo "Fetching SHA256 for v$VERSION..."
SHA256=$(curl -sL "https://github.com/gastownhall/beads/releases/download/v$VERSION/checksums.txt" | grep windows | awk '{print $1}')
SHA256=$(curl -sL "https://github.com/gastownhall/beads/releases/download/v$VERSION/checksums.txt" | grep windows_amd64 | awk '{print $1}')
if [ -z "$SHA256" ]; then
echo "Error: Could not find Windows checksum for v$VERSION"
@ -48,7 +48,7 @@ ManifestType: version
ManifestVersion: 1.6.0
EOF
# Update installer manifest
# Update installer manifest (PortableCommandAlias required — GH#4908)
cat > "$WINGET_DIR/SteveYegge.beads.installer.yaml" << EOF
# yaml-language-server: \$schema=https://aka.ms/winget-manifest.installer.1.6.0.schema.json
PackageIdentifier: SteveYegge.beads
@ -99,11 +99,72 @@ ManifestType: defaultLocale
ManifestVersion: 1.6.0
EOF
# GasTownHall.Beads is the package id users install today (v1.x on winget-pkgs).
# Always set PortableCommandAlias so WinGet\\Links\\bd.exe is created (GH#4908).
# SHA256 for arm64 is left for the releaser to fill from checksums.txt when present.
ARM_SHA=$(curl -sL "https://github.com/gastownhall/beads/releases/download/v$VERSION/checksums.txt" | grep 'windows_arm64' | awk '{print $1}' | tr '[:lower:]' '[:upper:]')
ARM_SHA_IS_PLACEHOLDER=0
if [ -z "$ARM_SHA" ]; then
ARM_SHA="0000000000000000000000000000000000000000000000000000000000000000"
ARM_SHA_IS_PLACEHOLDER=1
fi
# Keep this header in step with the checked-in winget/GasTownHall.Beads.installer.yaml:
# the first run of this script overwrites that file, so anything documented only
# there (the GH#4908 rationale) would be silently dropped.
cat > "$WINGET_DIR/GasTownHall.Beads.installer.yaml" << EOF
# yaml-language-server: \$schema=https://aka.ms/winget-manifest.installer.1.12.0.schema.json
# Canonical installer for PackageIdentifier GasTownHall.Beads (published under
# manifests/g/GasTownHall/Beads/<version>/ in microsoft/winget-pkgs).
#
# PortableCommandAlias is REQUIRED so winget creates
# %LOCALAPPDATA%\\Microsoft\\WinGet\\Links\\bd.exe. Without it, only the package
# folder is on PATH (visible only to processes started after install) and
# already-running shells never see \`bd\` (GH#4908).
#
# Commands: is search metadata only — it does NOT create the Links symlink.
PackageIdentifier: GasTownHall.Beads
PackageVersion: $VERSION
InstallerType: zip
NestedInstallerType: portable
NestedInstallerFiles:
- RelativeFilePath: bd.exe
PortableCommandAlias: bd
Commands:
- bd
ReleaseDate: $(date -u +%F)
Installers:
- Architecture: x64
InstallerUrl: https://github.com/gastownhall/beads/releases/download/v$VERSION/beads_${VERSION}_windows_amd64.zip
InstallerSha256: $SHA256
- Architecture: arm64
InstallerUrl: https://github.com/gastownhall/beads/releases/download/v$VERSION/beads_${VERSION}_windows_arm64.zip
InstallerSha256: "$ARM_SHA"
ManifestType: installer
ManifestVersion: 1.12.0
EOF
echo ""
echo "✓ Updated winget manifests for v$VERSION"
echo ""
echo "Next steps:"
echo "1. Commit these changes"
echo "2. Fork https://github.com/microsoft/winget-pkgs"
echo "3. Copy winget/*.yaml to manifests/s/SteveYegge/beads/$VERSION/"
echo "3. Prefer GasTownHall.Beads:"
echo " copy winget/GasTownHall.Beads.installer.yaml"
echo " → manifests/g/GasTownHall/Beads/$VERSION/"
echo " (legacy SteveYegge.beads → manifests/s/SteveYegge/beads/$VERSION/)"
echo "4. Submit PR to microsoft/winget-pkgs"
echo ""
echo "Reminder: PortableCommandAlias: bd is required (GH#4908)."
# The arm64 fallback above is otherwise disclosed only in a source comment, and
# the manifest it writes is schema-valid, so a releaser following the steps
# above would publish an installer entry that fails hash validation at install
# time.
if [ "$ARM_SHA_IS_PLACEHOLDER" -eq 1 ]; then
echo ""
echo "WARNING: no windows_arm64 checksum found for v$VERSION;"
echo " the arm64 InstallerSha256 is a zero placeholder — DO NOT PUBLISH"
echo " until it is replaced with the real hash from checksums.txt."
fi

View file

@ -0,0 +1,29 @@
# yaml-language-server: $schema=https://aka.ms/winget-manifest.installer.1.12.0.schema.json
# Canonical installer for PackageIdentifier GasTownHall.Beads (published under
# manifests/g/GasTownHall/Beads/<version>/ in microsoft/winget-pkgs).
#
# PortableCommandAlias is REQUIRED so winget creates
# %LOCALAPPDATA%\Microsoft\WinGet\Links\bd.exe. Without it, only the package
# folder is on PATH (visible only to processes started after install) and
# already-running shells never see `bd` (GH#4908).
#
# Commands: is search metadata only — it does NOT create the Links symlink.
PackageIdentifier: GasTownHall.Beads
PackageVersion: 1.1.0
InstallerType: zip
NestedInstallerType: portable
NestedInstallerFiles:
- RelativeFilePath: bd.exe
PortableCommandAlias: bd
Commands:
- bd
ReleaseDate: 2026-07-04
Installers:
- Architecture: x64
InstallerUrl: https://github.com/gastownhall/beads/releases/download/v1.1.0/beads_1.1.0_windows_amd64.zip
InstallerSha256: 12B1D37344D3B1543301E21A2B9ED3AB6AE009F0418441F3DE5F762B40769A6B
- Architecture: arm64
InstallerUrl: https://github.com/gastownhall/beads/releases/download/v1.1.0/beads_1.1.0_windows_arm64.zip
InstallerSha256: C2F3FC50407896336BAFAAB74E955F632FDFB487579FD24E44D766AB05792F7F
ManifestType: installer
ManifestVersion: 1.12.0

View file

@ -1,43 +1,73 @@
# Windows Package Manager (winget) Manifest
# Windows Package Manager (winget) Manifests
This directory contains the winget manifest files for publishing beads to the Windows Package Manager.
This directory holds winget manifests for publishing beads to the Windows Package Manager.
## Installation (once published)
## Package identifiers
```powershell
winget install SteveYegge.beads
```
| Identifier | Install command | Notes |
|---|---|---|
| **GasTownHall.Beads** | `winget install GasTownHall.Beads` | Current community package (v1.x). Prefer this for new installs. |
| **SteveYegge.beads** | `winget install SteveYegge.beads` | Legacy identifier (0.30.x era). Kept for continuity. |
## Manifest Files
Both installer manifests **must** set `PortableCommandAlias: bd` under `NestedInstallerFiles`.
That is what creates `%LOCALAPPDATA%\Microsoft\WinGet\Links\bd.exe`.
- `SteveYegge.beads.yaml` - Version manifest (main file)
- `SteveYegge.beads.installer.yaml` - Installer configuration
- `SteveYegge.beads.locale.en-US.yaml` - Package description and metadata
`Commands: [bd]` alone is **search metadata only** — it does not create a symlink.
Without `PortableCommandAlias`, winget only adds the package folder to PATH (inherited by
*new* processes). Already-running shells, editors, and agents never see `bd` until restart
(GH#4908).
## Manifest files
### GasTownHall.Beads (current)
- `GasTownHall.Beads.installer.yaml` — installer + **PortableCommandAlias**
This repo carries only the installer manifest for this id, but a winget-pkgs version
directory needs a `version` + `defaultLocale` + `installer` set. **Publish this id with
`wingetcreate update`** (below), which supplies the other two from the already-published
manifests. Hand-copying just this file produces a set winget-pkgs validation rejects.
### SteveYegge.beads (legacy)
- `SteveYegge.beads.yaml` — version manifest
- `SteveYegge.beads.installer.yaml` — installer + PortableCommandAlias
- `SteveYegge.beads.locale.en-US.yaml` — locale
- Copy to winget-pkgs: `manifests/s/SteveYegge/beads/<version>/`
The hand-copy path applies to this id only — it is the one with a complete three-file set.
## Submitting to winget-pkgs
1. Fork https://github.com/microsoft/winget-pkgs
2. Create directory: `manifests/s/SteveYegge/beads/<version>/`
3. Copy the three manifest files to that directory
4. Submit a PR to microsoft/winget-pkgs
2. For `SteveYegge.beads`, place the three manifests under the path above
3. For `GasTownHall.Beads`, use `wingetcreate` rather than a hand-copied directory
4. Open a PR
Or use the wingetcreate tool:
```powershell
wingetcreate update SteveYegge.beads --version <new-version> --urls <new-url> --submit
wingetcreate update GasTownHall.Beads --version <new-version> --urls <new-url> --submit
```
## Updating for New Releases
## Updating for new releases
When releasing a new version:
```bash
./scripts/update-winget.sh <version>
```
1. Update the version in all three manifest files
2. Update the InstallerUrl in the installer manifest
3. Update the InstallerSha256 (get from checksums.txt in the release)
4. Update the ReleaseNotesUrl
5. Submit PR to microsoft/winget-pkgs
This refreshes the SteveYegge.beads manifests (and regenerates GasTownHall.Beads.installer.yaml
with PortableCommandAlias). Note that it rewrites **both** ids to `<version>`, including the
legacy one — so the first run moves `SteveYegge.beads` off the 0.30.x version named above.
Then:
1. Update InstallerSha256 from the release `checksums.txt`
2. Commit, then PR to microsoft/winget-pkgs
### Getting the SHA256
```bash
curl -sL https://github.com/gastownhall/beads/releases/download/v<VERSION>/checksums.txt | grep windows
curl -sL https://github.com/gastownhall/beads/releases/download/v<VERSION>/checksums.txt | grep windows_
```
The `windows_amd64` line is the `x64` `InstallerSha256`; the `windows_arm64` line is the
`arm64` one. A bare `grep windows` matches both and is what produced the two-hash
`InstallerSha256` that `scripts/check-winget-portable-alias.sh` now catches.