freeze.mjs

Publishes the current worktree branch to dev, after backing it up and proving it green.

Contributor tooling › freeze.mjs

What it does

Backs the current worktree branch up as a timestamped git tag, merges origin/dev in, proves the merged tree with npm run check, then pushes the branch and fast-forwards dev to it. Retries the fetch-merge-check-push cycle up to 3 times when another worktree wins the race to advance dev first. Refuses to run at all from dev, staging, main, an unregistered worktree, or a dirty tree.

Usage

The minimal invocation that works:

npm run freeze

The equivalent direct form:

node tools/freeze.mjs [--dry-run]

Options

Flag	Value	What it does	Default
--dry-run	no value	Skips every write: no backup tag, no push, no fast-forward of dev. Still fetches, merges origin/dev locally, and runs npm run check on the merged tree, then reports what it would have pushed.	off — writes for real

Inputs and outputs

Reads:

• the current worktree's identity, via basename(REPO_ROOT) resolved against tools/worktree-registry.mjs (fails if unregistered)
• the current branch, and the working tree's git status
• existing backup-<key>-* tags

Writes, skipped entirely under --dry-run:

• a backup-<key>-<epoch-ms> tag on the current HEAD, pushed to origin
• on the first round only, a backup-<key>-<epoch-ms>-dev tag marking where dev stood at the start
• deletes (and unpushes) this worktree's backup tags older than 7 days
• merges origin/dev into the local branch, then pushes the local branch to origin
• fast-forwards dev to the merged HEAD by pushing HEAD:dev (GW_FREEZE=1 is set for that one push)

Every round also runs npm run check, --dry-run included — whatever that suite touches, freeze.mjs touches.

Exit codes: a completed publish or a completed dry run exits 0. Any of these exits 1:

• not in the registry, on the wrong branch, or a dirty tree
• a tag creation, fetch, or merge-conflict failure
• npm run check red, or the branch push failing
• the retry loop exhausting its 3 rounds because dev keeps moving

There is no exit code other than 0 or 1.

Examples

Publish a finished, committed worktree branch to dev:

npm run freeze

Check whether the branch would pass, without publishing anything:

npm run freeze -- --dry-run

Notes

Refuses on a dirty tree, on dev/staging/main directly, and on a worktree not listed in tools/worktree-registry.mjs, printing the reason before exiting 1.

Proves the tree with npm run check, which is the whole gate — freezing therefore proves the browser and dev-loop suites too, and takes as long as the gate does.

The retry loop is bounded at 3 rounds. If another worktree keeps winning the race to advance dev, freeze gives up with exit 1, but the worktree branch itself is already pushed and safe — only dev was not advanced.

Undo a publish with the backup tag it prints on its way in: git reset --hard backup-<key>-<epoch>.

Source

tools/freeze.mjs — part of Contributor tooling