Skip to content

winget: a standalone cloudpin.exe (#96) - #101

Merged
paureis merged 23 commits into
mainfrom
feat/96-winget
Nov 4, 2026
Merged

paureis merged 23 commits into
mainfrom
feat/96-winget

Conversation

@paureis

@paureis paureis commented Oct 18, 2026 •

Copy link
Copy Markdown
Owner

Closes #96.

A standalone cloudpin.exe for winget: a Node 26 single executable application with cloudpin, yaml and cross-spawn bundled inside. The design is docs/superpowers/specs/2026-10-18-winget-design.md (owner-approved).

In this PR

  • scripts/build-exe.mjs:
    • Bundles dist/cli.js into one ESM file with rolldown. rolldown is a new devDependency pinned to 1.2.15, the version vitest already brings.
    • Inlines the version. src/version.ts reads package.json everywhere except inside the exe.
    • Runs node --build-sea with the Node pinned in scripts/exe-node-version.txt (26.13.0 since the merge with main), with code cache and snapshot off.
    • Downloads both Node files from nodejs.org/dist and checks each against the sha256 recorded in scripts/exe-node-sha256.txt and against SHASUMS256.txt.
    • Zips cloudpin.exe with LICENSE.
  • release.yml builds cloudpin-X.Y.Z-win-x64.zip in the existing ubuntu job (a cross-build, no Windows minutes). It's added to SHA256SUMS, the attestation, the release assets and the dry-run artifact.
  • Upgrade advice:
    • The exe knows it's a SEA. It loads node:sea through process.getBuiltinModule, so Bun still runs the npm build.
    • Under winget's package folder or its Links folder, it says winget upgrade paureis.cloudpin.
    • Anywhere else, it says to download the latest zip.
  • Nightly:
    • The existing Windows job builds the exe and runs scripts/check-exe.ps1: version, refusals, an az-absent pin, arguments cmd.exe would re-parse, and controls that must fail.
    • A new small node-security job (issues: write only there) files one issue per newer Node 26 security release. It checks --state all before filing, and its fetch has a 20 s timeout.
  • winget manifests: templates in packaging/winget/ (paureis.cloudpin, publisher paureis, schema 1.28.0). bump-installers.mjs --winget <dir> renders them from the release's SHA256SUMS after checking the zip.
  • docs/winget.md: the owner's by-hand submission, with wingetcreate submit and the token in an environment variable, never on the command line. README, CHANGELOG (Unreleased) and AGENTS.md are updated too.

Evidence

  • npm run typecheck exit 0; npm test 1039 passed, 8 skipped (Windows).
  • The CLI runs under Bun (the review's must-fix): bun dist/cli.js --version prints 1.1.0. The control: under Bun, import("node:sea") throws.
  • A release dry run built the exe on ubuntu (run 39103739006). Downloaded here, that Linux-built exe passed all 12 check-exe.ps1 checks on Windows, controls included (a wrong pin, a blocked exec, a damaged copy). Microsoft Defender found no threats in the exe or the zip.
  • Built locally:
    • 105.9 MB exe, 40.6 MB zip.
    • --version median startup 46 ms, against 103 ms for node dist/cli.js on Node 22.
  • winget validate (v1.29) passes on a rendered set. Dropping InstallerSha256 or License makes it fail.
  • After the review fixes, Nightly and the release dry run were dispatched on this branch; results are in the comment below.

Review

One review round. The must-fix: a static node:sea import broke cloudpin under Bun. Fixed if cheap:

  • Nightly's tests could be skipped when nodejs.org stalled;
  • a closed security issue was re-filed daily;
  • the Node files are now pinned by recorded sha256;
  • the design's Submitting row now matches the docs.

Left:

  • the winget upgrade notice can come before winget-pkgs accepts the new version;
  • the machine-scope Links folder isn't named in the PATH fix;
  • a --location install reads as the plain exe.

🤖 Generated with Claude Code

paureis and others added 19 commits October 18, 2026 01:15
Owner-approved decisions for 1.3.0: Node 26 SEA cross-built in the ubuntu
release job, cloudpin bundled into one ESM file, unsigned at first, x64 only,
Nightly flags Node security releases, paureis.cloudpin as the winget ID,
manifests generated by bump-installers and submitted by the owner by hand.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
rolldown 1.2.13 was already in the tree through vitest's vite; declaring
it at that exact version adds no package. Reinstalled from scratch per
CLAUDE.md: 15 @rolldown/binding entries, npm ci succeeds. The fresh
resolution also moved two dev-only transitives a patch: postcss 8.5.30
and tinybench 6.2.2.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
cli.ts and config.ts each read ../package.json through createRequire,
which can't work inside a Node single executable application, where
import.meta.url is the exe's path. src/version.ts reads it once, unless
the bundler has replaced CLOUDPIN_BUNDLED_VERSION with the literal
version.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Inside a single executable application (node:sea isSea()) the install is
read from the exe's own path: under winget's portable package folder
(<root>\Packages\paureis.cloudpin_<source>, user or machine scope) it is
winget, anywhere else the exe. Doctor's on-PATH check also knows winget's
Links folder, and treats a cloudpin.exe outside every layout as the exe.

Advice: winget upgrade paureis.cloudpin, or download the latest
cloudpin-X.Y.Z-win-x64.zip from the GitHub releases page.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Bundles dist/cli.js with yaml and cross-spawn into one ES module
(rolldown, the version inlined), refuses a bundle that still reads
package.json or loads a package, and runs node --build-sea of the Node
pinned in scripts/exe-node-version.txt (26.12.0) with the official
win-x64 node.exe of that version as the executable. Every Node file is
downloaded from nodejs.org/dist and checked against SHASUMS256.txt. On
Linux the linux-x64 node runs --build-sea; on Windows node.exe builds
itself. Writes cloudpin-X.Y.Z-win-x64.zip (cloudpin.exe and LICENSE)
with windows-zip.mjs's zip writer.

--node-version prints the pin; --security-release prints a newer
security release of its major line from nodejs.org/dist/index.json.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
After the Windows zip, the publish job runs scripts/build-exe.mjs, which
fetches the pinned Node's linux-x64 build and win-x64 node.exe from
nodejs.org/dist (each checked against SHASUMS256.txt) and runs
--build-sea on ubuntu. The zip joins SHA256SUMS, the provenance
attestation, the release assets and the dry run's artifact. Nothing
else in the job changes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… releases (#96)

The existing Windows job builds the exe from the checkout and runs
scripts/check-exe.ps1 from Windows PowerShell 5.1: --version against
package.json, an unknown section refused with the exe's download advice,
an azure pin passing with az absent (PATH is System32), the arguments
a&b, %PATH%, ^ and a|b reaching explain --json unchanged, and controls
that must fail (a wrong pin against a fake az, a damaged exe copy). The
job's timeout goes from 8 to 10 minutes.

The changed job (ubuntu, daily) asks build-exe.mjs for a newer security
release of the pinned Node line and opens one issue per release, with
issues: write on that job only; a failure there never skips the tests.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
README's Windows install part says each release from 1.3.0 has the
exe zip and that winget comes with 1.3.0; CHANGELOG under Unreleased;
AGENTS.md's layout table names src/version.ts and the exe scripts.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
)

The multi-file manifest winget-pkgs requires (version, installer,
defaultLocale en-US), schema 1.28.0 with the yaml-language-server
headers real manifests carry. The installer is the release's
cloudpin-X.Y.Z-win-x64.zip, a zip with one portable nested installer,
cloudpin.exe, aliased as cloudpin. ArchiveBinariesDependOnPath is left
unset: the exe carries everything it needs, so winget's default link in
its Links folder is enough, and install-method.ts already recognises it.
__VERSION__, __SHA256__ and __RELEASE_DATE__ are filled in by
scripts/bump-installers.mjs --winget.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
)

--winget <out-dir> fills packaging/winget/'s templates and writes them to
<out-dir>/manifests/p/paureis/cloudpin/<version>/, winget-pkgs' layout, so
wingetcreate submit takes that folder. InstallerSha256 is the
SHA256SUMS line for cloudpin-X.Y.Z-win-x64.zip, uppercase as winget-pkgs
writes it, after the downloaded zip is checked against it. ReleaseDate is
the GitHub Release's published date from the public API, or --date
YYYY-MM-DD. Each rendered file must parse as YAML for paureis.cloudpin
at that version with no placeholder left.

As with --tap and --bucket, every check runs before any write, and the
options combine: a version folder that already has files is refused
before anything is downloaded (--force rewrites it), and a wrong exe zip
leaves the bucket untouched too.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Numbered by-hand steps, the same for the first version and every later
one: render with bump-installers --winget and winget validate, a classic
public_repo token with a 7-day expiry, read into
WINGET_CREATE_GITHUB_TOKEN with Read-Host so it never appears on a
command line (wingetcreate reads that variable when no --token is given),
wingetcreate submit with the PR titles winget-pkgs' template asks for,
then the CLA bot, the validation labels, and what to do on
Binary-Validation-Error, Defender and executable failures, with the
signing options from the design. Later versions use submit, not update,
so the submitted manifest is the one checked against SHA256SUMS. Points
not confirmed by the docs are marked unverified. AGENTS.md's layout
table names packaging/winget/ and this page.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…#96)

Bun has no node:sea and refuses to load a module that imports it, so under
Bun every cloudpin command exited 1, the shell wrapper's cloudpin exec
crashed and agent hooks failed open. isSea() now asks
process.getBuiltinModule, and is false when the module or the function is
missing (Node before 22.3) or the lookup throws.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The index.json fetch had no timeout, so a stalled nodejs.org ran into
the Nightly job's own limit and cancelled it. securityRelease() now
aborts the request after 20 s with an error that names the URL.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
It shared the changed job, so a stalled nodejs.org could cancel that job
and skip the tests that need it, and the job held issues: write. Now
node-security runs daily on its own with issues: write, nothing needs
it, and changed is back to contents: read.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The duplicate check listed only open issues, so closing "Node X security
release: rebuild cloudpin.exe?" as not needed filed it again the next
day, and every day until the pin moved. It now lists all states.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The win-x64 node.exe and the linux-x64 tarball were checked only against
SHASUMS256.txt from the same host, so a file swapped on nodejs.org along
with its SHASUMS256.txt would pass. scripts/exe-node-sha256.txt now
records both for the pinned 26.12.0 (cross-checked against the signed
SHASUMS256.txt.asc), and a download is used only when it matches the
record and SHASUMS256.txt; any mismatch or missing record fails the
build. Bumping the pin is one step: the version, then --print-hashes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The Submitting row still said wingetcreate update per minor release;
docs/winget.md submits the rendered, SHA256SUMS-checked manifest with
wingetcreate submit every time, because update hashes the zip itself.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@paureis paureis added this to the 1.3.0 milestone Oct 18, 2026
The damaged-copy control looked for the static node:sea import, which the
Bun fix removed, so Nightly's Windows job failed "the bundled code is in the
exe" (run 39105515088; the other 11 checks passed). It now looks for
process.getBuiltinModule?.(id), a code token found once in the bundle, so
damaging it is still a syntax error. All 12 checks pass on the exe the
post-fix release dry run built (run 39105516712).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@paureis

paureis commented Oct 18, 2026

Copy link
Copy Markdown
Owner Author

Branch runs after the review fixes: release dry run 39105516712 green (pinned-hash build). Nightly 39105515088: node-security and ubuntu green; on Windows the exe built and passed 11/12 checks. The 12th, the damaged-copy control, was looking for the node:sea import that the Bun fix removed. Fixed in 9ca4628, and all 12 checks now pass locally on the post-fix CI-built exe. The Windows job will be confirmed by a re-dispatch next session.

paureis and others added 2 commits November 4, 2026 18:19
CHANGELOG: main's, with the winget lines under [Unreleased]. Lockfile: main's
entries; rolldown is now a direct devDependency at 1.2.15, the version vitest
already brings, so only one copy is installed.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
26.12.1 was a security release after the 26.12.0 this branch pinned. The recorded
hashes match the release's SHASUMS256.txt.asc, whose signature checks out against
the signer's key from nodejs/release-keys.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@paureis paureis changed the title winget: a standalone cloudpin.exe (#96) [merge after v1.2.0] winget: a standalone cloudpin.exe (#96) Nov 4, 2026
@paureis
paureis marked this pull request as ready for review November 4, 2026 23:21
Bundled comments mention package.json (a Vercel source path, npm's engines), so
Nightly's exe build stopped once main was merged. The check now looks for the
name as a string, in any quotes and through a path.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@paureis
paureis merged commit c2c604d into main Nov 4, 2026
9 checks passed
@paureis
paureis deleted the feat/96-winget branch November 4, 2026 23:26
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

winget package (standalone exe)

1 participant