Summary
Distribute archgate through winget (Windows Package Manager), following the same thin-shim pattern as the other ecosystems (ARCH-017): the winget package installs a small shim executable that downloads the real binary from GitHub Releases on first run, verifies its SHA256 checksum, caches it to ~/.archgate/bin/archgate.exe, and forwards to it.
winget install Archgate.Archgate
Approach
winget's portable installer type takes a standalone .exe from an InstallerUrl, places it in winget's packages directory, and creates an archgate command alias on PATH — no MSI authoring, no install scripts.
The key enabler: the Go shim (shims/go) already implements the full ARCH-017 behavioral contract — platform detection, versioned download, SHA256 verification, shared ~/.archgate/bin/ cache, arg forwarding, exit-code propagation — including a Windows exec path (internal/shim/exec_windows.go) and a Version constant that .simple-release.js already bumps on every release. Cross-compiling it to a Windows exe (~2–3 MB with -ldflags "-s -w") yields a winget-ready portable shim with zero new shim code.
Tasks
1. shims/winget/ — generation script and manifest templates
2. CI smoke test of the generation (smoke-test-windows.yml)
3. Publish the shim exe (release-binaries.yml)
4. Initial manifest submission to microsoft/winget-pkgs (one-time, manual)
5. Automate per-release manifest updates (publish-shims.yml)
6. Docs and governance
Design notes
Why a shim instead of pointing winget at the real binary?
- The package stays tiny (~2–3 MB vs ~60 MB compiled binary) and installs fast
- All install methods converge on the same
~/.archgate/bin/ cache — installing via winget after npm (or vice versa) downloads nothing
winget upgrade still works: each release submits a new manifest version whose shim pins the new CLI version, so the standard winget update flow and the shim's own download flow stay consistent
Trade-offs / open questions:
- First-run download latency — same as every other shim, acceptable per ARCH-017
- Windows ARM64 remains unsupported (out of scope; tracked by the platform matrix in ARCH-017)
- The release pipeline gains an external dependency on winget-pkgs PR moderation — publish failures there must not block the other shim publishes (separate job,
continue-on-error or equivalent)
- Whether to embed Windows version-info metadata in the shim exe (e.g. via
goversioninfo) — nice-to-have, not required by winget for portable packages
Summary
Distribute archgate through winget (Windows Package Manager), following the same thin-shim pattern as the other ecosystems (ARCH-017): the winget package installs a small shim executable that downloads the real binary from GitHub Releases on first run, verifies its SHA256 checksum, caches it to
~/.archgate/bin/archgate.exe, and forwards to it.Approach
winget's
portableinstaller type takes a standalone.exefrom anInstallerUrl, places it in winget's packages directory, and creates anarchgatecommand alias on PATH — no MSI authoring, no install scripts.The key enabler: the Go shim (
shims/go) already implements the full ARCH-017 behavioral contract — platform detection, versioned download, SHA256 verification, shared~/.archgate/bin/cache, arg forwarding, exit-code propagation — including a Windows exec path (internal/shim/exec_windows.go) and aVersionconstant that.simple-release.jsalready bumps on every release. Cross-compiling it to a Windows exe (~2–3 MB with-ldflags "-s -w") yields a winget-ready portable shim with zero new shim code.Tasks
1.
shims/winget/— generation script and manifest templatesshims/winget/holding the build script that cross-compilesshims/go/cmd/archgatewithGOOS=windows GOARCH=amd64 go build -ldflags "-s -w" -o archgate-shim-win32-x64.exe— no new shim code; the winget artifact is the compiled Go shimmanifests/) with{VERSION}/{SHA256}placeholders as the in-repo source of truth, rendered by the scriptREADME.mddocumenting the package and how the folder differs from the other shims (build recipe + manifests, not a standalone codebase)Versionconstant is already covered by the ARCH-013 bump hook, and templates use placeholdersPackageVersionplus the two URLs that embed the version, bumped by the.simple-release.jshook and enforced byARCH-013/shim-version-sync.{{SHA256}}is the only remaining placeholder, since the checksum cannot exist until the release workflow builds the binary.2. CI smoke test of the generation (
smoke-test-windows.yml)shims/winget/build script on the Windows smoke-test job (Go toolchain via setup-go)archgate-shim-win32-x64.exe --versionon the clean runner — this exercises the full production path (download of the latest released binary from GitHub Releases, SHA256 verification, cache to~/.archgate/bin/, exec) on every PR, not just at release timewinget validateis not preinstalled onwindows-latestrunners — full validation may be release-time/manual only)tests/shims/winget/build.test.tsasserts the rendered manifests carry no unresolved placeholder, and that runs on every PR viabun run validate. No YAML/schema well-formedness check runs in CI.winget validatepassed manually against the submitted 0.52.0 manifests.3. Publish the shim exe (
release-binaries.yml)shims/winget/build script from the release workflow (single generation path — no drift between what CI tests and what releases ship).sha256file and sigstore attestation, consistent with the existing release assets4. Initial manifest submission to
microsoft/winget-pkgs(one-time, manual)shims/winget/manifests/templates for package idArchgate.Archgate(version, installer, defaultLocale) with:InstallerType: portableInstallerUrl→archgate-shim-win32-x64.exerelease assetInstallerSha256from the companion checksum fileCommands: [archgate](command alias on PATH)x64only (win32-x64 is the only supported Windows target per ARCH-017)winget validate/winget install --manifestNew-Package, CLA cleared, validation pipeline running). Awaiting moderator review — recent new-package PRs merge in roughly 10 hours to 2 days.5. Automate per-release manifest updates (
publish-shims.yml)wingetjob (windows-latest) gated on the existing "wait for binaries" job, extended to also wait for the shim exe assetwingetcreate update Archgate.Archgate --version $VERSION --urls <shim-exe-url> --submitWINGET_TOKENrepo secret (PAT withpublic_repo) for the fork-and-PR flow against winget-pkgsArchgate.Archgateis accepted.wingetcreate updatefails against a package that does not exist, and the publish job fails loudly rather than skipping, so setting the secret early would turn every release red. The job currently warns and exits 0 when the secret is absent.6. Docs and governance
.rules.tsenumerates shim packages and needs a new entry (and whethershims/winget/— a build recipe, not a shim implementation — needs an explicit carve-out)Design notes
Why a shim instead of pointing winget at the real binary?
~/.archgate/bin/cache — installing via winget after npm (or vice versa) downloads nothingwinget upgradestill works: each release submits a new manifest version whose shim pins the new CLI version, so the standard winget update flow and the shim's own download flow stay consistentTrade-offs / open questions:
continue-on-erroror equivalent)goversioninfo) — nice-to-have, not required by winget for portable packages