# scripts ## Overview `scripts/` holds the build and release helpers. `build-libghostty-vt.sh` clones Ghostty at a pinned commit and builds the static `libghostty-vt` library and header with Zig. [`binding.gyp`](../binding.gyp) calls `resolve-libghostty-vt.mjs` to find that header and library when it builds [`native/`](../native/README.md). The other four Node ES module scripts do release work: they assemble per-platform prebuilds into `prebuilds/`, load the current platform's prebuild through `dist/index.js` as a check, create and push the `v` Git tag, and pick the npm dist-tag. None of them export functions. ## Interface | Script | Invoked by | Inputs | Output | | --- | --- | --- | --- | | `build-libghostty-vt.sh` | `npm run build:libghostty` (mise tasks `ci` and `release-prebuilds`) | env `GHOSTTY_REPO`, `GHOSTTY_COMMIT`, `GHOSTTY_SOURCE_DIR` (default `vendor/ghostty`), `LIBGHOSTTY_VT_PREFIX` (default `vendor/libghostty-vt`), `LIBGHOSTTY_VT_SIMD` (default `false`), `LIBGHOSTTY_VT_OPTIMIZE` (default `ReleaseFast`), `LIBGHOSTTY_VT_CPU` (default `baseline`) | progress on stdout, errors on stderr. Exit 0 on success. Its own checks exit 1. Under `set -euo pipefail`, a failed `mkdir` or `git` command exits with that command's status [scripts/build-libghostty-vt.sh:need] | | `check-baseline-cpu.sh` | mise task `check-baseline-cpu`, run by the `linux-x64` jobs of `.github/workflows/ci.yml`, `.github/workflows/publish.yml` and `.github/workflows/release-prebuilds.yml` (the last two with `PREBUILDS_ONLY=1`), all with `BASELINE_CPU_IMAGE` set to `ubuntu:24.04` pinned by digest, because Node alone dies on `qemu64` on those runners, which install Ubuntu's amd64v3 packages | env `QEMU_CPU` (default `qemu64`), `PREBUILDS_ONLY`, `BASELINE_CPU_IMAGE`. Needs Linux on x86_64, and `qemu-x86_64-static` or `qemu-x86_64` on `PATH` or, with `BASELINE_CPU_IMAGE`, `docker` | the smoke output on stdout. Exit 0 when `examples/smoke.ts` passes on the emulated CPU, 1 when it fails, 2 on the wrong platform, without qemu, when the image cannot install `libatomic1` and `qemu-user`, or when `node -e 0` alone fails on that CPU. `docker run` exits 125 when it cannot start the image [scripts/check-baseline-cpu.sh:qemu] | | `resolve-libghostty-vt.mjs` | `binding.gyp` `include_dirs` and `libraries` | argv `include` or `library`. Env `LIBGHOSTTY_VT_PREFIX` (default `vendor/libghostty-vt`), `LIBGHOSTTY_VT_INCLUDE_DIR` (default `/include`), `LIBGHOSTTY_VT_STATIC_LIB`, then `LIBGHOSTTY_VT_LIB` (default `/lib/libghostty-vt.a`, `ghostty-vt-static.lib` on win32) | the absolute path on stdout, with no trailing newline [scripts/resolve-libghostty-vt.mjs:libraryPath] | | `assemble-prebuilds.mjs` | `npm run assemble:prebuilds` (mise task `assemble-prebuilds`, run by `publish-dry-run` and `publish`) | argv[2] source (default `.release-artifacts`), argv[3] target (default `prebuilds`), env `EXPECTED_PREBUILD_PLATFORMS` (default `darwin-arm64,linux-arm64,linux-x64`) | JSON `{ sourceRoot, targetRoot, platforms }` on stdout [scripts/assemble-prebuilds.mjs:expectedPlatforms] | | `verify-prebuilds.mjs` | `npm run verify:prebuilds` (mise tasks `release-prebuilds`, `publish-dry-run`, and `publish`) | `prebuilds/` and `dist/index.js` (run `npm run build` first) | JSON `{ platforms, addon, nativeInfo }` on stdout, where `addon` is the file it loaded [scripts/verify-prebuilds.mjs:addon] | | `create-release-tag.mjs` | `npm run release:create-tag` (mise task `create-release-tag`, run by `.github/workflows/publish.yml`) | `package.json` `version`, env `RELEASE_BRANCH_NAME` (optional), `RELEASE_TARGET_SHA` (default `git rev-parse HEAD`) | JSON `{ tagName, targetSha, created }` on stdout [scripts/create-release-tag.mjs:releaseTargetSha] | | `resolve-npm-publish-tag.mjs` | `npm run resolve:publish-tag` (mise tasks `publish-dry-run` and `publish`), and directly in `.github/workflows/publish.yml` and in the `publish` task's `npm publish --tag` | `package.json` `version`, env `NPM_PUBLISH_TAG`, `GITHUB_REF_TYPE`, `GITHUB_REF_NAME` | one dist-tag and a newline on stdout [scripts/resolve-npm-publish-tag.mjs:printTag] | In the `.mjs` scripts, a failed `assert` or a thrown `Error` ends the process with a non-zero exit code. ## Invariants - The default Ghostty commit is `83fb95624b0439ee660c2679b43b38c8b63769cd`. `GHOSTTY_COMMIT` overrides it [scripts/build-libghostty-vt.sh:GHOSTTY_COMMIT]. - `build-libghostty-vt.sh` passes `-Dcpu=$LIBGHOSTTY_VT_CPU` (default `baseline`), so the library runs on any CPU of its architecture. On Darwin, Ghostty's build replaces the target with a generic macOS target, so the value has no effect there. Without it, Zig targets the build machine, and the `v0.1.0-beta.4` `linux-x64` prebuild, built on a runner with AVX-512, died with SIGILL on CPUs without AVX-512 [scripts/build-libghostty-vt.sh:CPU]. - `build-libghostty-vt.sh` exits 1 with `"error: missing required command ''"` and `"Install it first, then rerun npm run build:libghostty."` when `git` or `zig` is not on `PATH`. For `zig` it also prints `"This Ghostty commit requires Zig 0.17.0. With mise: mise install"` [scripts/build-libghostty-vt.sh:need]. - `build-libghostty-vt.sh` exits 1 when `zig version` differs from `minimum_zig_version` in Ghostty's `build.zig.zon`. It skips this check when that file names no version [scripts/build-libghostty-vt.sh:required_zig]. - `build-libghostty-vt.sh` exits 1 with `"error: expected exactly one 'const lib_version = \"\";' line in /build.zig, with no build metadata"` when Ghostty's `build.zig` has no such line, has more than one, or the value is not `MAJOR.MINOR.PATCH[-PRE]`. It checks this before it runs `zig` [scripts/build-libghostty-vt.sh:lib_version]. - `build-libghostty-vt.sh` runs `zig build -Demit-lib-vt=true -Dsimd=$SIMD -Doptimize=$OPTIMIZE -Dcpu=$CPU -Dlib-version-string=+ --prefix $PREFIX install`, with `--sysroot ` on Darwin when `xcrun` returns a path. `` is the full commit that `git rev-parse --verify HEAD` reports after the checkout. libghostty-vt reports `+` as its version string and `` as its build metadata. A failed build exits 1 [scripts/build-libghostty-vt.sh:zig_args] [scripts/build-libghostty-vt.sh:ghostty_commit]. - After the build, `$PREFIX/include/ghostty/vt.h` and `$PREFIX/lib/libghostty-vt.a` must exist. Otherwise the script exits 1 [scripts/build-libghostty-vt.sh:header]. - `resolve-libghostty-vt.mjs` exits 2 with `"usage: resolve-libghostty-vt.mjs "` for any other argument [scripts/resolve-libghostty-vt.mjs:command]. It exits 1 when `/ghostty/vt.h` or the static library is missing, and prints the setup steps and the paths it checked [scripts/resolve-libghostty-vt.mjs:fail]. - With `BASELINE_CPU_IMAGE` set, `check-baseline-cpu.sh` reruns itself in `docker run --rm --ulimit core=0 ` (no core file in the repository on a crash), with the repository and the real `node` binary mounted read-only at their host paths (so the image cannot change the addon or `prebuilds/`) and `QEMU_CPU` and `PREBUILDS_ONLY` passed through. The container installs `libatomic1` (Node needs it) and `qemu-user` with `apt-get`, so it needs the network. A Debian or Ubuntu image built for the x86-64 baseline lets Node run on `qemu64` [scripts/check-baseline-cpu.sh:BASELINE_CPU_IMAGE]. - `resolve-libghostty-vt.mjs` uses `??` for its defaults, so an environment variable set to an empty string does not fall back. `resolve("")` gives the working directory. Relative values resolve against the working directory, not the repository root [scripts/resolve-libghostty-vt.mjs:prefix]. - `assemble-prebuilds.mjs` asserts that the source and target differ and that the expected platform list is not empty [scripts/assemble-prebuilds.mjs:expectedPlatforms]. The source must be a directory that holds at least one `prebuilds-*` directory, and each platform directory must contain a `.node` file. Duplicate platforms fail, and every expected platform must be present. Platforms outside the expected list are copied without an error [scripts/assemble-prebuilds.mjs:hasNodeAddon]. Relative argv paths resolve against the working directory [scripts/assemble-prebuilds.mjs:sourceRoot]. - `verify-prebuilds.mjs` throws `"No prebuilds directory found. Run npm run build:prebuild first."` when `prebuilds/` cannot be read, and `"No prebuild platform directories found."` when it has no platform subdirectories [scripts/verify-prebuilds.mjs:prebuildsDir]. - `verify-prebuilds.mjs` sets `PREBUILDS_ONLY=1` before it imports `dist/index.js`, so `node-gyp-build` skips `build/Release` and loads only from `prebuilds/`. A stale addon from an earlier `npm run build:native` can no longer pass the check. The script then resolves the addon path again and throws unless that path is under `prebuilds/`. It loads only the current platform's addon [scripts/verify-prebuilds.mjs:addon]. - `create-release-tag.mjs` asserts that `version` matches `semverPattern`, the SemVer 2.0.0 grammar: no leading zeros in numeric identifiers and no empty identifiers. The tag is `v` [scripts/create-release-tag.mjs:semverPattern]. A set, non-empty `RELEASE_BRANCH_NAME` must equal `release/v` [scripts/create-release-tag.mjs:releaseBranchName]. The trimmed target SHA must be 40 hex characters and must equal the checked-out `HEAD` [scripts/create-release-tag.mjs:releaseTargetSha]. - When the remote tag already exists, `create-release-tag.mjs` asserts that its ref is `refs/tags/v` and that it points at the target SHA, prints `created: false`, and exits 0 without tagging. Empty `git ls-remote` output means the tag is absent. A failed `git ls-remote` (network or auth error) ends the script before it tags [scripts/create-release-tag.mjs:remoteTagSha]. - `resolve-npm-publish-tag.mjs` asserts that `version` matches its own `semverPattern`, the same SemVer 2.0.0 grammar with named groups. When `GITHUB_REF_TYPE` is `tag`, `GITHUB_REF_NAME` must be a string equal to `v`. This check runs before the `NPM_PUBLISH_TAG` override [scripts/resolve-npm-publish-tag.mjs:semverPattern]. - Dist-tag rule: `NPM_PUBLISH_TAG` is trimmed. A non-empty result must match `/^[A-Za-z][A-Za-z0-9._-]*$/` and is printed. Otherwise a version with no prerelease prints `latest`. Otherwise the first dot-separated prerelease identifier must match the same pattern and is printed in lower case, for example `beta` for `0.1.0-beta.1`. A version such as `1.0.0-1` fails with `"invalid prerelease channel for npm dist-tag: 1"` [scripts/resolve-npm-publish-tag.mjs:prerelease]. ## Side Effects - `build-libghostty-vt.sh` creates the parent of `GHOSTTY_SOURCE_DIR` and the `PREFIX` directory with `mkdir -p` [scripts/build-libghostty-vt.sh:PREFIX]. - Network: when `$GHOSTTY_SOURCE_DIR/.git` is missing, `build-libghostty-vt.sh` runs `git clone $GHOSTTY_REPO` (default `https://github.com/ghostty-org/ghostty.git`). Every run then runs `git fetch --depth 1 origin ` and `git checkout --detach ` in that directory, so every run needs the network [scripts/build-libghostty-vt.sh:GHOSTTY_REPO]. - `build-libghostty-vt.sh` runs `zig build ... install` into `PREFIX` [scripts/build-libghostty-vt.sh:zig_args] and writes `$PREFIX/ghostty-source.json` with the repository, commit, Zig version, SIMD, optimize, and requested CPU values (on Darwin the build ignores the CPU value). `commit` is the same resolved full commit that the build passed to `zig`, not the raw `GHOSTTY_COMMIT` value [scripts/build-libghostty-vt.sh:ghostty-source.json]. - `assemble-prebuilds.mjs` copies each `/prebuilds-*/` directory into a staging directory next to the target (`.staging-`, default `prebuilds.staging-`) with `errorOnExist: true`, and runs every check there. Only then does it move the old target to `.previous-`, rename the staging directory to the target, and delete the old one. A failed run deletes the staging directory and leaves the target as it was [scripts/assemble-prebuilds.mjs:stagingRoot]. - `verify-prebuilds.mjs` imports `../dist/index.js` and calls `getNativeInfo()`, which loads the native addon [scripts/verify-prebuilds.mjs:info]. - Network and remote state: `create-release-tag.mjs` runs `git ls-remote --tags origin`. When the tag is absent, it runs `git tag v ` and `git push origin refs/tags/v` [scripts/create-release-tag.mjs:git]. - `resolve-libghostty-vt.mjs` and `resolve-npm-publish-tag.mjs` read files and environment variables and write only to stdout and stderr [scripts/resolve-libghostty-vt.mjs:fail] [scripts/resolve-npm-publish-tag.mjs:printTag]. - Private helpers: `assertDirectory` and `listDirectories` in `assemble-prebuilds.mjs`, and `git` (which asserts an array of string arguments) in `create-release-tag.mjs` [scripts/assemble-prebuilds.mjs:listDirectories] [scripts/create-release-tag.mjs:git]. ## Verification - `npx vitest run test/scripts.test.ts` runs `create-release-tag.mjs`, `resolve-npm-publish-tag.mjs`, `assemble-prebuilds.mjs`, and `verify-prebuilds.mjs` as black boxes in temporary package roots, with a local bare repository as `origin` and no network. `npm test` includes it. No test covers `build-libghostty-vt.sh` or `resolve-libghostty-vt.mjs`. `mise run release-prebuilds` and `mise run publish-dry-run` start with `npm ci`, which reinstalls `node_modules/`. - Build scripts: `npm run build:libghostty && npm run build:native` - Prebuild check: `mise run release-prebuilds` - Baseline CPU check: `mise run check-baseline-cpu` after `npm run build:native` (Linux x86_64 with the `qemu-user` package, or `BASELINE_CPU_IMAGE=ubuntu:24.04` with Docker). Against the `v0.1.0-beta.4` and `v0.1.0-beta.5` `linux-x64` prebuilds it exits 1 (SIGILL), against a build with no instructions newer than the x86-64 baseline it exits 0. `binding.gyp` compiles the addon with `-march=x86-64` on Linux x64, so a compiler that defaults to x86-64-v3 (g++ on Ubuntu's amd64v3 variant) still gives such a build. - Prebuild assembly: `mise run publish-dry-run`. It needs `.release-artifacts/prebuilds-*` directories, which CI downloads in `.github/workflows/publish.yml`. - Dist-tag rule: `npm run resolve:publish-tag` (prints `beta` for version `0.1.0-beta.1`) - CAUTION: Do not run `npm run release:create-tag` to test it. It creates the `v` tag and pushes it to `origin`.