netwatch/script/bootstrap

#!/bin/sh
# script/bootstrap: install all dependencies needed to build and develop
# this repo. Idempotent: every install is guarded by a check so already
# installed tools are skipped. Base tooling comes from nix, apt, brew,
# or apk (detected in that order); assumes nothing is present. Node is
# used directly if installed; otherwise it is installed at a pinned
# version via nvm (installing nvm itself first, from a hash-verified
# release archive, never curl | sh). Go is used directly only if its
# version falls inside the pinned window described at GO_MAX_MINOR below
# -- a newer Go is ignored, not preferred -- and golangci-lint is
# installed at the exact pinned version; both come from hash-verified
# official release archives, never an install script.
#
# The backend's toolchain is bootstrapped here because script/check runs
# backend/script/test and backend/script/lint, so a machine that cannot
# run go and golangci-lint cannot pass the repo-wide gate or the
# pre-commit hook that script/setup installs.
#
# Anything installed outside the system package manager is symlinked
# into ~/.local/bin, so a later `make check` in a plain shell finds it.
# nvm only puts node on PATH for shells that source nvm.sh, which
# neither make nor the git hook does.
#
# Three rules govern what this script is allowed to touch:
#
#   1. Everything it installs itself lands under $HOME, using $TMPDIR
#      only for scratch downloads it then deletes. The one exception is
#      the system package manager, which it shells out to for base
#      tooling (see pkg_install) and which owns those paths already. A
#      per-repo bootstrap has no business writing to /usr/local/bin, a
#      Homebrew prefix, or any other system-wide location behind that
#      package manager's back.
#   2. It never replaces something it did not create. Only a symlink
#      that already points into one of its own managed directories is
#      overwritten; anything else is left alone and bootstrap exits
#      non-zero telling you what to remove.
#   3. It never reports success while the tools a later `make check`
#      would pick up are not the ones it provisioned. If it cannot
#      guarantee the pinned toolchain wins on your PATH, it exits
#      non-zero rather than leaving you a green bootstrap and a broken
#      gate.
set -eu

ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"

# The PATH as the caller had it, captured before ensure_bin_dir amends
# it. verify_toolchain checks against this rather than against the PATH
# this script builds for itself, so what it reports is what a later
# `make check` in the user's own shell will actually resolve.
ORIG_PATH="$PATH"

# Pinned versions, 2026-07-07
NODE_VERSION="22.17.0"
NVM_VERSION="0.40.3"
# sha256 of https://github.com/nvm-sh/nvm/archive/refs/tags/v0.40.3.tar.gz
NVM_SHA256="5f4d6aaa04a177dc93c985e31dbc411ab6b8c6e1e21d8015dbc1372625fcd1d0"
YARN_VERSION="1.22.22"

# Go 1.25.7 (2026-08-09). This is the toolchain inside the pinned
# golang:1.25-alpine builder of Dockerfile.backend, so a local build
# uses the same compiler CI does.
#
# The Go pin is a compatibility constraint to match, not a floor to
# clear. golangci-lint links go/types from the Go release it was built
# with, and go/types refuses to load packages compiled by a newer Go:
# with the pinned linter (built with go1.25.4) and a host Go 1.26,
# `make check` dies with
#
#     panic: file requires newer Go version go1.26
#            (application built with go1.25)
#
# So an already-installed go is reused only inside a window:
# GO_MIN_VERSION is the floor from backend/go.mod, and GO_MAX_MINOR is
# the major.minor of the Go the pinned golangci-lint was built with.
# Anything outside that window is ignored and GO_VERSION is installed
# instead. GO_MAX_MINOR is therefore coupled to GOLANGCI_LINT_VERSION
# below and must be revisited whenever that pin moves; `golangci-lint
# version` prints the "built with goX.Y.Z" it needs.
GO_VERSION="1.25.7"
GO_MIN_VERSION="1.25.5"
GO_MAX_MINOR="1.25"

# golangci-lint 2.7.2 (2026-08-09). MUST stay equal to the golangci-lint
# pinned in Dockerfile.backend (currently commit
# 9f61b0f53f80672872fced07b6874397c3ed197b, which is tag v2.7.2), so a
# local `make lint` and CI's in-image `make check` report the same
# findings.
#
# Reconciliation note: PR #31 moves Dockerfile.backend to golangci-lint
# v2.12.2, commit c0d3ddc9cf3faa61a4e378e879ece580256d76e5. When that
# lands, GOLANGCI_LINT_VERSION and every hash in golangci_lint_sha256()
# below must be updated to the v2.12.2 release archives in the same
# commit, or local and CI will disagree. GO_MAX_MINOR must move with
# it, to the major.minor that release reports as "built with".
GOLANGCI_LINT_VERSION="2.7.2"

# Where hash-verified archives are unpacked. Version-scoped, so bumping
# a pin installs alongside the old copy instead of half-overwriting it.
# Filled in by main() from script/projectname. TOOLCHAIN is also the
# ownership boundary used by link_bin: a symlink pointing inside it is
# one this script created and may replace.
TOOLCHAIN=""
GO_DIR=""
GOLANGCI_LINT_DIR=""

PKGMGR=""
SUDO=""
APT_UPDATED=""
BIN_DIR=""
NODE_BIN=""

detect_pkgmgr() {
    [ -n "$PKGMGR" ] && return 0
    if command -v nix-env >/dev/null 2>&1; then
        PKGMGR="nix"
    elif command -v apt-get >/dev/null 2>&1; then
        PKGMGR="apt"
    elif command -v brew >/dev/null 2>&1; then
        PKGMGR="brew"
    elif command -v apk >/dev/null 2>&1; then
        PKGMGR="apk"
    else
        echo "bootstrap: no supported package manager (nix, apt, brew, apk)" >&2
        exit 1
    fi
    if [ "$PKGMGR" = "apt" ]; then
        export DEBIAN_FRONTEND=noninteractive
        if [ "$(id -u)" != "0" ]; then
            SUDO="sudo"
        fi
    fi
}

# pkg_install <nix-attr> <apt-pkg> <brew-formula> <apk-pkg>
pkg_install() {
    detect_pkgmgr
    case "$PKGMGR" in
        nix) nix-env -iA "nixpkgs.$1" ;;
        apt)
            if [ -z "$APT_UPDATED" ]; then
                $SUDO env DEBIAN_FRONTEND=noninteractive apt-get update
                APT_UPDATED=1
            fi
            $SUDO env DEBIAN_FRONTEND=noninteractive apt-get install -y "$2"
            ;;
        brew) brew install "$3" ;;
        apk) apk add --no-cache "$4" ;;
    esac
}

missing() {
    ! command -v "$1" >/dev/null 2>&1
}

# verify_sha256 <file> <expected-hash>
verify_sha256() {
    if command -v sha256sum >/dev/null 2>&1; then
        actual="$(sha256sum "$1" | cut -d' ' -f1)"
    else
        actual="$(shasum -a 256 "$1" | cut -d' ' -f1)"
    fi
    if [ "$actual" != "$2" ]; then
        echo "bootstrap: sha256 mismatch for $1" >&2
        echo "  expected: $2" >&2
        echo "  actual:   $actual" >&2
        exit 1
    fi
}

# fetch_verified <url> <expected-hash> <dest>: download a release
# archive and check it against a hash hardcoded in this script before
# anything is unpacked or run. Never pipe a remote script to a shell.
fetch_verified() {
    if missing curl; then pkg_install curl curl curl curl; fi
    curl -fsSL -o "$3" "$1"
    verify_sha256 "$3" "$2"
}

# platform: <os>-<arch> as used in the Go and golangci-lint release
# archive filenames.
platform() {
    plat_os="$(uname -s)"
    plat_arch="$(uname -m)"
    case "$plat_os" in
        Linux) plat_os="linux" ;;
        Darwin) plat_os="darwin" ;;
        *)
            echo "bootstrap: unsupported OS $plat_os" >&2
            exit 1
            ;;
    esac
    case "$plat_arch" in
        x86_64 | amd64) plat_arch="amd64" ;;
        aarch64 | arm64) plat_arch="arm64" ;;
        *)
            echo "bootstrap: unsupported architecture $plat_arch" >&2
            exit 1
            ;;
    esac
    echo "$plat_os-$plat_arch"
}

# ver_ge <have> <want>: succeed if dotted version <have> is at least
# <want>, comparing up to three numeric components.
ver_ge() {
    awk -v have="$1" -v want="$2" '
        BEGIN {
            n = split(have, h, ".")
            m = split(want, w, ".")
            for (i = 1; i <= 3; i++) {
                hv = (i <= n) ? h[i] + 0 : 0
                wv = (i <= m) ? w[i] + 0 : 0
                if (hv > wv) exit 0
                if (hv < wv) exit 1
            }
            exit 0
        }'
}

# ensure_bin_dir: the directory provisioned tools are linked into. It is
# always ~/.local/bin: per-user, never a system-wide or package-manager
# prefix. It is put at the front of PATH for the rest of this run, and
# reported if the caller's own PATH did not already contain it.
ensure_bin_dir() {
    [ -n "$BIN_DIR" ] && return 0
    BIN_DIR="$HOME/.local/bin"
    mkdir -p "$BIN_DIR"
    case "$PATH" in
        "$BIN_DIR":*) ;;
        *)
            PATH="$BIN_DIR:$PATH"
            export PATH
            ;;
    esac
    case ":$ORIG_PATH:" in
        *":$BIN_DIR:"*) ;;
        *)
            echo "bootstrap: add $BIN_DIR to the front of your PATH, e.g." >&2
            echo "  export PATH=\"\$HOME/.local/bin:\$PATH\"" >&2
            ;;
    esac
}

# owned_path <path>: true when <path> lies inside a directory this
# script provisions, i.e. a link to it is one this script created and
# may replace. Everything else belongs to the user or to a package
# manager and is never touched.
owned_path() {
    case "$1" in
        "$TOOLCHAIN"/*) return 0 ;;
        "$HOME"/.nvm/*) return 0 ;;
        *) return 1 ;;
    esac
}

# refuse_clobber <path> <what>: report that <path> is not ours and stop.
refuse_clobber() {
    echo "bootstrap: $1 already exists and $2." >&2
    echo "  Refusing to replace something this script did not create." >&2
    echo "  Remove or rename it and re-run bootstrap." >&2
    exit 1
}

# link_bin <target> <name>: idempotently expose one provisioned binary
# on PATH. Only an existing symlink into one of our own directories is
# replaced; a regular file, a directory, or a symlink pointing anywhere
# else is left intact and bootstrap fails.
link_bin() {
    ensure_bin_dir
    link="$BIN_DIR/$2"
    if [ -L "$link" ]; then
        existing="$(readlink "$link")"
        if ! owned_path "$existing"; then
            refuse_clobber "$link" \
                "is a symlink to $existing, outside this repo's toolchain"
        fi
    elif [ -e "$link" ]; then
        refuse_clobber "$link" "is not a symlink"
    fi
    ln -sfn "$1" "$link"
}

# nvm is a bash script; run a command in a bash with nvm loaded
nvm_sh() {
    bash -c ". \"\$HOME/.nvm/nvm.sh\" && $*"
}

ensure_nvm() {
    [ -s "$HOME/.nvm/nvm.sh" ] && return 0
    # nvm prerequisites; nvm itself requires bash
    if missing bash; then pkg_install bash bash bash bash; fi
    if missing curl; then pkg_install curl curl curl curl; fi
    if missing git; then pkg_install git git git git; fi
    tmp="$(mktemp -d)"
    fetch_verified \
        "https://github.com/nvm-sh/nvm/archive/refs/tags/v${NVM_VERSION}.tar.gz" \
        "$NVM_SHA256" "$tmp/nvm.tar.gz"
    mkdir -p "$HOME/.nvm"
    tar -xzf "$tmp/nvm.tar.gz" -C "$HOME/.nvm" --strip-components=1
    rm -rf "$tmp"
}

ensure_node() {
    if ! missing node; then return 0; fi
    ensure_nvm
    nvm_sh "nvm install $NODE_VERSION"
    NODE_BIN="$HOME/.nvm/versions/node/v$NODE_VERSION/bin"
    for nb in node npm npx corepack; do
        if [ -e "$NODE_BIN/$nb" ]; then link_bin "$NODE_BIN/$nb" "$nb"; fi
    done
}

# ensure_yarn: yarn comes from corepack. Left to itself, `corepack
# enable` writes its shims next to the corepack binary it resolved, and
# it writes four of them (yarn, yarnpkg, pnpm, pnpx), not the one asked
# for. --install-directory keeps all four inside this repo's own
# toolchain directory, and only yarn is then linked onto PATH. The
# no-corepack fallback likewise installs into a per-user npm prefix
# under the toolchain directory instead of npm's global one. Nothing
# here writes outside $HOME.
ensure_yarn() {
    if ! missing yarn; then return 0; fi
    yarn_bin="$TOOLCHAIN/corepack-shims"
    mkdir -p "$yarn_bin"
    if ! missing corepack; then
        corepack enable --install-directory "$yarn_bin"
        corepack prepare "yarn@$YARN_VERSION" --activate
    elif [ -s "$HOME/.nvm/nvm.sh" ]; then
        nvm_sh "nvm use $NODE_VERSION >/dev/null && \
            corepack enable --install-directory \"$yarn_bin\" && \
            corepack prepare yarn@$YARN_VERSION --activate"
    else
        yarn_bin="$TOOLCHAIN/npm-global/bin"
        npm install -g --prefix "$TOOLCHAIN/npm-global" "yarn@$YARN_VERSION"
    fi
    if [ -e "$yarn_bin/yarn" ]; then
        link_bin "$yarn_bin/yarn" yarn
    fi
}

install_js_deps() {
    if missing yarn && [ -s "$HOME/.nvm/nvm.sh" ]; then
        nvm_sh "nvm use $NODE_VERSION >/dev/null && cd \"$ROOT\" && \
            yarn install --frozen-lockfile"
    else
        yarn install --frozen-lockfile
    fi
}

# go_sha256 <platform>: sha256 of
# https://go.dev/dl/go1.25.7.<platform>.tar.gz, from the signed release
# index at https://go.dev/dl/?mode=json (2026-08-09).
go_sha256() {
    case "$1" in
        linux-amd64)
            echo "12e6d6a191091ae27dc31f6efc630e3a3b8ba409baf3573d955b196fdf086005"
            ;;
        linux-arm64)
            echo "ba611a53534135a81067240eff9508cd7e256c560edd5d8c2fef54f083c07129"
            ;;
        darwin-amd64)
            echo "bf5050a2152f4053837b886e8d9640c829dbacbc3370f913351eb0904cb706f5"
            ;;
        darwin-arm64)
            echo "ff18369ffad05c57d5bed888b660b31385f3c913670a83ef557cdfd98ea9ae1b"
            ;;
        *)
            echo "bootstrap: no pinned Go archive hash for $1" >&2
            exit 1
            ;;
    esac
}

# go_ok: an already-installed go is acceptable only inside the window
# described at GO_MAX_MINOR: at least GO_MIN_VERSION, and no newer in
# major.minor than the Go the pinned golangci-lint was built with. A
# newer host Go is not "good enough", it makes `make check` panic, so it
# is treated exactly like a missing one.
go_ok() {
    if missing go; then return 1; fi
    have="$(go version 2>/dev/null | awk '{print $3}')"
    have="${have#go}"
    [ -n "$have" ] || return 1
    ver_ge "$have" "$GO_MIN_VERSION" || return 1
    ver_ge "$GO_MAX_MINOR" "$(echo "$have" | cut -d. -f1,2)"
}

# gofmt_ok: gofmt is a gate tool -- backend/script/fmt-check runs it --
# and its output is not guaranteed byte-identical across Go releases, so
# a gofmt from a different release than the go that compiles the code is
# treated exactly like a missing one, the same way a mismatched
# golangci-lint is. `go version <file>` prints the toolchain a Go binary
# was built with, so this compares the gofmt that resolves on PATH
# against the go that resolves on PATH, without depending on where
# either one lives. Anything it cannot read -- no go to ask, gofmt
# absent, not a Go binary -- fails closed.
gofmt_ok() {
    if missing go; then return 1; fi
    if missing gofmt; then return 1; fi
    go_have="$(go version 2>/dev/null | awk '{print $3}')"
    [ -n "$go_have" ] || return 1
    fmt_have="$(go version "$(command -v gofmt)" 2>/dev/null | awk '{print $NF}')"
    [ "$fmt_have" = "$go_have" ]
}

# ensure_go: reuse the host toolchain only when the go on PATH is inside
# the window AND a gofmt from that same release is on PATH with it. Both
# link_bin calls sit outside that early return, so whenever the pinned
# toolchain is the one in use they run on every bootstrap, not only on
# the run that unpacked the archive: a deleted or never-created gofmt
# link is restored rather than silently left to some other Go's gofmt.
ensure_go() {
    if go_ok && gofmt_ok; then return 0; fi
    if [ ! -x "$GO_DIR/bin/go" ]; then
        plat="$(platform)"
        tmp="$(mktemp -d)"
        fetch_verified \
            "https://go.dev/dl/go${GO_VERSION}.${plat}.tar.gz" \
            "$(go_sha256 "$plat")" "$tmp/go.tar.gz"
        rm -rf "$GO_DIR.partial"
        mkdir -p "$GO_DIR.partial"
        tar -xzf "$tmp/go.tar.gz" -C "$GO_DIR.partial" --strip-components=1
        rm -rf "$GO_DIR"
        mv "$GO_DIR.partial" "$GO_DIR"
        rm -rf "$tmp"
    fi
    link_bin "$GO_DIR/bin/go" go
    link_bin "$GO_DIR/bin/gofmt" gofmt
}

# golangci_lint_sha256 <platform>: sha256 of the golangci-lint 2.7.2
# release archive for that platform, from
# https://github.com/golangci/golangci-lint/releases/download/v2.7.2/golangci-lint-2.7.2-checksums.txt
# (2026-08-09).
golangci_lint_sha256() {
    case "$1" in
        linux-amd64)
            echo "ce46a1f1d890e7b667259f70bb236297f5cf8791a9b6b98b41b283d93b5b6e88"
            ;;
        linux-arm64)
            echo "7028e810837722683dab679fb121336cfa303fecff39dfe248e3e36bc18d941b"
            ;;
        darwin-amd64)
            echo "6966554840a02229a14c52641bc38c2c7a14d396f4c59ba0c7c8bb0675ca25c9"
            ;;
        darwin-arm64)
            echo "6ce86a00e22b3709f7b994838659c322fdc9eae09e263db50439ad4f6ec5785c"
            ;;
        *)
            echo "bootstrap: no pinned golangci-lint archive hash for $1" >&2
            exit 1
            ;;
    esac
}

# golangci_lint_ok: unlike go, this must be the exact pinned version.
# A different version reports a different set of findings, so local
# results would stop matching what Dockerfile.backend gates on.
golangci_lint_ok() {
    if missing golangci-lint; then return 1; fi
    have="$(golangci-lint version 2>&1 | awk '
        {
            for (i = 1; i < NF; i++) {
                if ($i == "version") {
                    v = $(i + 1)
                    sub(/^v/, "", v)
                    print v
                    exit
                }
            }
        }')"
    [ "$have" = "$GOLANGCI_LINT_VERSION" ]
}

ensure_golangci_lint() {
    if golangci_lint_ok; then return 0; fi
    if [ ! -x "$GOLANGCI_LINT_DIR/golangci-lint" ]; then
        plat="$(platform)"
        base="golangci-lint-${GOLANGCI_LINT_VERSION}-${plat}"
        tmp="$(mktemp -d)"
        fetch_verified \
            "https://github.com/golangci/golangci-lint/releases/download/v${GOLANGCI_LINT_VERSION}/${base}.tar.gz" \
            "$(golangci_lint_sha256 "$plat")" "$tmp/golangci-lint.tar.gz"
        mkdir -p "$tmp/x"
        tar -xzf "$tmp/golangci-lint.tar.gz" -C "$tmp/x" --strip-components=1
        rm -rf "$GOLANGCI_LINT_DIR.partial"
        mkdir -p "$GOLANGCI_LINT_DIR.partial"
        cp "$tmp/x/golangci-lint" "$GOLANGCI_LINT_DIR.partial/golangci-lint"
        chmod +x "$GOLANGCI_LINT_DIR.partial/golangci-lint"
        rm -rf "$GOLANGCI_LINT_DIR"
        mv "$GOLANGCI_LINT_DIR.partial" "$GOLANGCI_LINT_DIR"
        rm -rf "$tmp"
    fi
    link_bin "$GOLANGCI_LINT_DIR/golangci-lint" golangci-lint
}

# verify_toolchain: bootstrap must not exit 0 while the tools the gate
# will actually run are not the provisioned ones. Everything above only
# guarantees the right tools exist and are linked into $BIN_DIR; if
# something earlier on the caller's PATH shadows them, `make check` --
# and the pre-commit hook script/setup installs -- still break, and a
# warning buried in a long bootstrap log is not enough. So the checks
# re-run against the PATH the caller will have (theirs, plus $BIN_DIR at
# the front if bootstrap had to ask for it), and a failure is fatal.
#
# Every gate tool that has a version constraint is checked with the same
# predicate its install used -- go_ok, gofmt_ok, golangci_lint_ok -- not
# with a bare presence test, because a wrong-version gate tool produces
# different results from the one CI runs, which is the failure this
# function exists to prevent. node and yarn have no pinned version to
# disagree about, so presence is the whole constraint for them.
verify_toolchain() {
    # BIN_DIR is only set once something needed linking, but the remedy
    # text must name a real directory in every reachable state, so fall
    # back to the one ensure_bin_dir would have chosen.
    bin_dir="${BIN_DIR:-$HOME/.local/bin}"

    # Model the PATH the caller will actually have: their own, plus
    # $BIN_DIR at the front only if bootstrap linked something there and
    # therefore told them to add it.
    verify_path="$ORIG_PATH"
    if [ -n "$BIN_DIR" ]; then
        case ":$ORIG_PATH:" in
            *":$BIN_DIR:"*) ;;
            *) verify_path="$BIN_DIR:$ORIG_PATH" ;;
        esac
    fi

    saved_path="$PATH"
    PATH="$verify_path"
    export PATH
    bad=""
    go_ok || bad="$bad go"
    gofmt_ok || bad="$bad gofmt"
    golangci_lint_ok || bad="$bad golangci-lint"
    for t in node yarn; do
        if missing "$t"; then bad="$bad $t"; fi
    done
    PATH="$saved_path"
    export PATH

    [ -z "$bad" ] && return 0

    # Two different faults land here and they need different remedies: a
    # tool that resolves but is the wrong build is being shadowed, and
    # telling the user to fix PATH is right; a tool that does not resolve
    # at all is not being shadowed by anything, and saying so would send
    # them hunting for a conflict that does not exist.
    echo "bootstrap: the toolchain on your PATH cannot run the gate." >&2
    wrong=""
    absent=""
    for t in $bad; do
        where="$(
            export PATH="$verify_path"
            command -v "$t" 2>/dev/null || true
        )"
        if [ -n "$where" ]; then
            echo "  $t: $where (wrong version)" >&2
            wrong="$wrong $t"
        else
            echo "  $t: not found" >&2
            absent="$absent $t"
        fi
    done
    echo "  The pinned toolchain is linked into $bin_dir." >&2
    if [ -n "$wrong" ]; then
        echo "  The tools shown with a path resolve to a build this" >&2
        echo "  script did not provision: something earlier on your PATH" >&2
        echo "  shadows $bin_dir. Put $bin_dir first in" >&2
        echo "  PATH, or remove the conflicting tool, then re-run." >&2
    fi
    if [ -n "$absent" ]; then
        echo "  The tools shown as not found are on no directory of your" >&2
        echo "  PATH at all, so nothing is shadowing them. Add $bin_dir" >&2
        echo "  to PATH and re-run; if they are still not found after" >&2
        echo "  that, bootstrap failed to install them and that is a bug" >&2
        echo "  in this script, not in your environment." >&2
    fi
    echo "  Failing rather than leaving you a bootstrap that reports" >&2
    echo "  success and a \`make check\` that does not run." >&2
    exit 1
}

main() {
    cd "$ROOT"

    TOOLCHAIN="$HOME/.local/share/$("$ROOT/script/projectname")/toolchain"
    GO_DIR="$TOOLCHAIN/go-$GO_VERSION"
    GOLANGCI_LINT_DIR="$TOOLCHAIN/golangci-lint-$GOLANGCI_LINT_VERSION"

    if missing make; then pkg_install gnumake make make make; fi
    if missing git; then pkg_install git git git git; fi

    ensure_node
    ensure_yarn
    install_js_deps

    ensure_go
    ensure_golangci_lint

    verify_toolchain

    echo "bootstrap complete"
}

main "$@"