Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -92,7 +92,7 @@ requests and on `main`, all inside the devcontainer image.

| Command | Run from | Purpose |
|---|---|---|
| `just test` | devcontainer | level-1 checks, as in CI: gofmt, vet, `go test -race`, golangci-lint, `openspec validate --all --strict` |
| `just test` | devcontainer | level-1 checks, as in CI: gofmt, vet, `go test -race`, golangci-lint, `openspec validate --all --strict`, and `hack/test-install.sh` (`install.sh` against a release served on loopback) |
| `just golden` | devcontainer | rewrite golden files after an intended change |
| `just build` | devcontainer | build a static `bin/siding` (linux) |
| `just dist <version>` | devcontainer | build the release binaries (macOS and Linux, arm64 and amd64) and `SHA256SUMS` into `dist/`; CI does it on `v*` tags and publishes a GitHub Release |
Expand Down
28 changes: 26 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -65,17 +65,41 @@ steps below follow the order you walk them in; each links to the details in the

### 1. Install siding

```sh
curl -fsSL https://raw.githubusercontent.com/tweinmann/siding/main/install.sh | sh
```

The script downloads the latest release for your machine (macOS or Linux, arm64 or amd64),
checks it against the release's `SHA256SUMS`, installs it as `~/.local/bin/siding` without
`sudo`, and tells you if that directory is not on your `PATH`. Run it again to update.
`SIDING_VERSION=v0.5.0` installs a given release, `SIDING_INSTALL_DIR=/usr/local/bin` another
directory (with `sudo sh` if it needs root).

To read the script before it runs:

```sh
curl -fsSLO https://raw.githubusercontent.com/tweinmann/siding/main/install.sh
less install.sh && sh install.sh
```

<details>
<summary>Without the script</summary>

Download the binary for your platform and `SHA256SUMS` from the
[latest release](https://github.com/tweinmann/siding/releases/latest), then:

```sh
shasum -a 256 -c SHA256SUMS --ignore-missing # sha256sum on Linux
chmod +x siding-darwin-arm64 # siding-<os>-<arch> of your platform
sudo mv siding-darwin-arm64 /usr/local/bin/siding
xattr -d com.apple.quarantine /usr/local/bin/siding # macOS: the binary is not signed yet
xattr -d com.apple.quarantine /usr/local/bin/siding # macOS, after a browser download: the binary is not signed yet
siding version
```

With Go: `go install github.com/tweinmann/siding/cmd/siding@latest`.

</details>

The binaries are static and need nothing but Docker and git. To build siding yourself, see
[Developing siding](#developing-siding).

Expand Down Expand Up @@ -427,7 +451,7 @@ on your machine and siding's tests never touch your Docker containers.

| Command | Purpose |
|---|---|
| `just test` | formatting, vet, unit tests with `-race`, golangci-lint, OpenSpec validation (as in CI) |
| `just test` | formatting, vet, unit tests with `-race`, golangci-lint, OpenSpec validation, the test of `install.sh` (as in CI) |
| `just golden` | rewrite golden files after an intended output change |
| `just build` | build `bin/siding` |
| `just dist <version>` | the release binaries and `SHA256SUMS` in `dist/`, as CI builds them for a `v*` tag |
Expand Down
69 changes: 69 additions & 0 deletions hack/test-install.sh
Original file line number Diff line number Diff line change
@@ -0,0 +1,69 @@
#!/usr/bin/env bash
# Tests install.sh against a release built with just dist and served on a loopback port: an
# install, an update, a broken checksum, an install directory missing from the PATH, and an
# unsupported platform. Needs no Docker and no network; leaves nothing behind.
set -euo pipefail
source "$(dirname "$0")/lib.sh"
[[ "${SIDING_DEVCONTAINER:-}" == 1 ]] || die "run this inside the siding devcontainer (SIDING_DEVCONTAINER is not set)"

cd "$(dirname "$0")/.."
work="$(mktemp -d)"
server=""
cleanup() {
[[ -n "$server" ]] && kill "$server" 2>/dev/null
rm -rf "$work"
}
trap cleanup EXIT

# A release of this platform's binary only: the script downloads nothing else.
case "$(uname -m)" in aarch64 | arm64) arch=arm64 ;; *) arch=amd64 ;; esac
asset="siding-linux-$arch"
mkdir -p "$work/release"
CGO_ENABLED=0 go build -trimpath -ldflags "-X main.version=v0.0.0-test" -o "$work/release/$asset" ./cmd/siding
(cd "$work/release" && sha256sum "$asset" >SHA256SUMS)

port="$(python3 -c 'import socket; s = socket.socket(); s.bind(("127.0.0.1", 0)); print(s.getsockname()[1])')"
python3 -m http.server "$port" --bind 127.0.0.1 --directory "$work/release" >/dev/null 2>&1 &
server=$!
retry 20 curl -fs -o /dev/null "http://127.0.0.1:$port/SHA256SUMS" || die "the test server did not start"

failed=0
check() { # check <name> <condition…>
local name="$1"
shift
if "$@"; then echo "ok $name"; else echo "FAIL $name"; failed=1; fi
}
install() { # install <dir> [VAR=value…]: runs install.sh, output in $work/out
local dir="$1"
shift
env SIDING_DOWNLOAD_URL="http://127.0.0.1:$port" SIDING_INSTALL_DIR="$dir" "$@" sh install.sh >"$work/out" 2>&1
}
has() { grep -qF -- "$1" "$work/out"; }

bin="$work/bin"
check "install" install "$bin" PATH="$bin:$PATH"
check " the binary runs" bash -c "'$bin/siding' version | grep -q v0.0.0-test"
check " says what comes next" has "Next: siding setup"
check " no PATH hint when on the PATH" bash -c "! grep -q 'is not on your PATH' '$work/out'"

check "update" install "$bin" PATH="$bin:$PATH"
check " still runs" bash -c "'$bin/siding' version >/dev/null"

check "not on the PATH" install "$work/other" PATH="/usr/bin:/bin"
check " gives the export line" has "export PATH=\"$work/other:\$PATH\""

cp "$work/release/SHA256SUMS" "$work/sums"
echo "0000000000000000000000000000000000000000000000000000000000000000 $asset" >"$work/release/SHA256SUMS"
check "a checksum mismatch fails" bash -c "! env SIDING_DOWNLOAD_URL=http://127.0.0.1:$port SIDING_INSTALL_DIR='$work/bad' sh install.sh >'$work/out' 2>&1"
check " installs nothing" test ! -e "$work/bad/siding"
check " names the mismatch" has "checksum mismatch"
cp "$work/sums" "$work/release/SHA256SUMS"

check "an unsupported platform fails" bash -c "! env SIDING_UNAME_S=MINGW64_NT SIDING_DOWNLOAD_URL=http://127.0.0.1:$port SIDING_INSTALL_DIR='$work/win' sh install.sh >'$work/out' 2>&1"
check " names the supported ones" has "there are binaries for macOS and Linux"
check "a 32-bit system fails" bash -c "! env SIDING_UNAME_M=i686 SIDING_DOWNLOAD_URL=http://127.0.0.1:$port SIDING_INSTALL_DIR='$work/x86' sh install.sh >'$work/out' 2>&1"
check "no release fails" bash -c "! env SIDING_DOWNLOAD_URL=http://127.0.0.1:$port/nope SIDING_INSTALL_DIR='$work/none' sh install.sh >'$work/out' 2>&1"
check " says no release was found" has "found no release"

[[ "$failed" == 0 ]] || die "install.sh failed its test"
echo "test-install: ok"
87 changes: 87 additions & 0 deletions install.sh
Original file line number Diff line number Diff line change
@@ -0,0 +1,87 @@
#!/bin/sh
# Installs siding: the binary of the latest release for this machine, checked against the
# release's SHA256SUMS, into ~/.local/bin. Run it again to update.
#
# curl -fsSL https://raw.githubusercontent.com/tweinmann/siding/main/install.sh | sh
#
# SIDING_VERSION=v0.5.0 install that release instead of the latest
# SIDING_INSTALL_DIR=<dir> install there instead of ~/.local/bin
# SIDING_DOWNLOAD_URL=<url> download the release files from there (a mirror, or a test)
set -eu

repo="https://github.com/tweinmann/siding"

fail() {
echo "siding install: $*" >&2
exit 1
}

# The platform, as the release names its binaries. SIDING_UNAME_S and SIDING_UNAME_M exist for
# the test only.
os="${SIDING_UNAME_S:-$(uname -s)}"
arch="${SIDING_UNAME_M:-$(uname -m)}"
case "$os" in
Darwin) os=darwin ;;
Linux) os=linux ;;
*) fail "no siding for $os; there are binaries for macOS and Linux" ;;
esac
case "$arch" in
arm64 | aarch64) arch=arm64 ;;
x86_64 | amd64) arch=amd64 ;;
*) fail "no siding for $arch; there are binaries for arm64 and amd64 (x86_64)" ;;
esac
asset="siding-$os-$arch"

if [ -n "${SIDING_DOWNLOAD_URL:-}" ]; then
url="$SIDING_DOWNLOAD_URL"
elif [ -n "${SIDING_VERSION:-}" ]; then
url="$repo/releases/download/$SIDING_VERSION"
else
url="$repo/releases/latest/download"
fi
dir="${SIDING_INSTALL_DIR:-$HOME/.local/bin}"

if command -v curl >/dev/null 2>&1; then
fetch() { curl -fsSL -o "$2" "$1"; }
elif command -v wget >/dev/null 2>&1; then
fetch() { wget -q -O "$2" "$1"; }
else
fail "neither curl nor wget is installed"
fi
if command -v sha256sum >/dev/null 2>&1; then
sum() { sha256sum "$1" | cut -d ' ' -f 1; }
elif command -v shasum >/dev/null 2>&1; then
sum() { shasum -a 256 "$1" | cut -d ' ' -f 1; }
else
fail "neither sha256sum nor shasum is installed, so the download cannot be checked"
fi

tmp="$(mktemp -d)"
trap 'rm -rf "$tmp"' EXIT INT TERM

echo "Downloading $asset from $url"
fetch "$url/SHA256SUMS" "$tmp/SHA256SUMS" ||
fail "found no release at $url; check SIDING_VERSION, or see $repo/releases"
fetch "$url/$asset" "$tmp/$asset" || fail "could not download $url/$asset"

want="$(awk -v f="$asset" '$2 == f || $2 == "*" f { print $1 }' "$tmp/SHA256SUMS")"
[ -n "$want" ] || fail "SHA256SUMS of this release has no line for $asset; nothing was installed"
got="$(sum "$tmp/$asset")"
[ "$got" = "$want" ] || fail "checksum mismatch for $asset (expected $want, got $got); nothing was installed"

mkdir -p "$dir" || fail "cannot create $dir; choose another with SIDING_INSTALL_DIR"
chmod 755 "$tmp/$asset"
# mv replaces the file instead of writing into it, so a running siding is not disturbed.
mv -f "$tmp/$asset" "$dir/siding" || fail "cannot write to $dir; choose another with SIDING_INSTALL_DIR"

echo "Installed $("$dir/siding" version) to $dir/siding"
case ":$PATH:" in
*":$dir:"*) ;;
*)
echo
echo "$dir is not on your PATH. Add it, e.g. in ~/.zshrc or ~/.bashrc:"
echo " export PATH=\"$dir:\$PATH\""
;;
esac
echo
echo "Next: siding setup, then follow \"Get started\" in $repo#get-started"
2 changes: 2 additions & 0 deletions justfile
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,8 @@ test:
go test -race ./...
golangci-lint run ./...
openspec validate --all --strict --no-interactive
# install.sh against a release served on a loopback port; no Docker, no network
hack/test-install.sh

# Rewrite golden files from the current code after an intended change
# (every package with golden files; a package without the -update flag would fail on it)
Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
schema: spec-driven
created: 2026-10-29
80 changes: 80 additions & 0 deletions openspec/changes/archive/2026-10-29-install-script/design.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,80 @@
# Design

## Context

v0.5 builds `siding-<os>-<arch>` and `SHA256SUMS` with `just dist`, and the release workflow
publishes them on a `v*` tag (spec `releases`). GitHub serves the newest release's assets at
the stable URL `https://github.com/<owner>/<repo>/releases/latest/download/<asset>` and a given
release's at `…/releases/download/<tag>/<asset>`, with no API call and no token. Motivation and
scope: see proposal.md.

## Goals / Non-Goals

**Goals:**
- One command installs or updates siding, checks what it downloaded, and needs no `sudo`.
- The script is short enough to read before running it.

**Non-Goals:**
- Homebrew, signed or notarised binaries, Windows, `siding self-update`.
- Installing Docker or git, or running `siding setup`.
- Verifying signatures beyond the checksum from the same release.

## Decisions

### D1. POSIX `sh`, `curl` or `wget`
The script runs with `sh` on macOS and on minimal Linux images; it uses `curl -fsSL`, else
`wget -qO-`, and `sha256sum`, else `shasum -a 256`. Alternative: bash (not on every minimal
image, and `curl … | sh` is the common form).

### D2. The platform
`uname -s` gives `Darwin` or `Linux` (else the script stops), `uname -m` gives `arm64`/`aarch64`
→ `arm64` and `x86_64`/`amd64` → `amd64` (else it stops), naming what it found and what is
supported.

### D3. Download and check
Into a temporary directory removed on exit: the binary and `SHA256SUMS` from
`$SIDING_DOWNLOAD_URL`, which defaults to
`https://github.com/tweinmann/siding/releases/latest/download`, or to
`…/releases/download/$SIDING_VERSION` when that is set. The script compares the binary's sum with
its line in `SHA256SUMS` and stops on a mismatch or a missing line, before anything is
installed. `SIDING_DOWNLOAD_URL` also lets the test serve a local build, and lets a user point at
a mirror. Alternative: the GitHub API for the latest tag (rate-limited without a token, and needs
JSON parsing in `sh`).

### D4. Where it installs
`~/.local/bin` by default, created if missing: no `sudo`, and the directory the XDG convention
and many tools use. `SIDING_INSTALL_DIR` chooses another, e.g. `/usr/local/bin` with `sudo`.
The binary is moved into place with `mv` from the temporary directory in the same step as
`chmod 755`, so a running `siding` is replaced, not overwritten in place. When the directory is
not on the `PATH`, the script prints the `export PATH=…` line for `~/.zshrc` or `~/.bashrc`.
Alternative: `/usr/local/bin` by default (needs `sudo` on Linux and on many Macs).

### D5. Quarantine
`curl` and `wget` do not set macOS's quarantine attribute, so the script needs no `xattr`. The
manual way in the README keeps the `xattr` line for downloads through a browser.

### D6. The test
`hack/test-install.sh` (bash, the `SIDING_DEVCONTAINER` guard, but no Docker) builds this
platform's binary as `just dist` does, with the version `v0.0.0-test`, and its `SHA256SUMS`
into a temporary directory (the script downloads only that one binary), serves it with `python3 -m http.server` on a
free loopback port, and runs `install.sh` with `SIDING_DOWNLOAD_URL` and `SIDING_INSTALL_DIR`
pointing at temporary directories: an install that reports `v0.0.0-test`, an update over it, a
broken checksum that installs nothing, and an install directory missing from the `PATH`. It runs
in `just test`, needs no Docker and no network, and leaves nothing behind. The platform check is
tested with `uname` replaced by a function through `SIDING_UNAME_S`/`SIDING_UNAME_M`, which only
the test sets.

## Risks / Trade-offs

- [`curl | sh` runs code from the network] → the README shows the download-read-run variant; the
script is short, and served from the repository over HTTPS.
- [The checksum comes from the same release as the binary] → it catches broken and truncated
downloads, not a compromised release; signing is a non-goal for now.
- [`~/.local/bin` is not on the `PATH` on a fresh Mac] → the script says so and gives the line.
- [The first release does not exist yet] → until `v0.5.0` is tagged, `latest/download` answers
404 and the script says that no release was found.

## Migration Plan

Nothing to migrate. The README changes with this change; the script works from the first
release, `v0.5.0`, which is tagged after this change is merged.
36 changes: 36 additions & 0 deletions openspec/changes/archive/2026-10-29-install-script/proposal.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,36 @@
# Proposal

## Why

Installing a release takes six manual steps today: find the right file in the browser, download
it and `SHA256SUMS`, check it, `chmod`, move it onto the `PATH`, and on macOS clear the
quarantine flag. Each step is a chance to give up before siding ever ran. This is the first
thing a user does, so it should be one line, before `v0.5.0` is tagged and the manual way
becomes a habit.

## What Changes

- An install script `install.sh` at the repository's root, POSIX `sh`, run as
`curl -fsSL https://raw.githubusercontent.com/tweinmann/siding/main/install.sh | sh`. It
detects the platform, downloads the binary and `SHA256SUMS` of the latest release (or of
`SIDING_VERSION`), refuses on a checksum mismatch, and installs to `~/.local/bin` (or
`SIDING_INSTALL_DIR`) without `sudo`. It says when that directory is not on the `PATH`, and
ends with `siding version` and the next step. Running it again updates siding.
- The README's install step leads with the one-liner, shows how to read the script first, keeps
the manual way as a fallback, and mentions `go install` for Go users.
- `just test` runs a test of the script against a `just dist` build served locally.

## Capabilities

### New Capabilities

None.

### Modified Capabilities
- `releases`: the install instructions lead with the script; the install script itself.

## Impact

- New files: `install.sh`, `hack/test-install.sh`; `justfile` (`test`).
- README: step 1 of "Get started".
- No change to siding's binary, its commands or documents.
Original file line number Diff line number Diff line change
@@ -0,0 +1,50 @@
# Spec Delta

## MODIFIED Requirements

### Requirement: Install instructions
The README SHALL lead with the install script as one command, show how to download and read
the script before running it, and keep the manual way for macOS and Linux: download the binary
for the platform, check it against `SHA256SUMS`, make it executable, put it on the `PATH`, and
on macOS remove the quarantine flag of a binary downloaded in a browser. It SHALL name
`go install` for users with Go.

#### Scenario: Install on a Mac
- **WHEN** a user follows the README on an Apple silicon Mac
- **THEN** `siding version` runs and reports `darwin/arm64` and the release's version

#### Scenario: Without the script
- **WHEN** a user does not want to pipe a script into a shell
- **THEN** the README shows how to download `install.sh`, read it and run it, and the manual steps

## ADDED Requirements

### Requirement: Install script
`install.sh` SHALL install siding with one command on macOS and Linux, on arm64 and amd64:
detect the platform, download the binary and `SHA256SUMS` of the latest release, or of
`SIDING_VERSION`, check the binary, and put it into `~/.local/bin`, or `SIDING_INSTALL_DIR`,
without `sudo`. It MUST install nothing when the check fails.

#### Scenario: One line
- **WHEN** a user on an Apple silicon Mac runs `curl -fsSL https://raw.githubusercontent.com/tweinmann/siding/main/install.sh | sh`
- **THEN** `~/.local/bin/siding` is the release's `siding-darwin-arm64`, and the script prints `siding version` and that `siding setup` comes next

#### Scenario: A checksum mismatch
- **WHEN** the downloaded binary does not match its line in `SHA256SUMS`
- **THEN** the script exits non-zero, names the mismatch, and installs nothing

#### Scenario: Not on the PATH
- **WHEN** the install directory is not on the `PATH`
- **THEN** the script says so and gives the line to add to the shell's profile

#### Scenario: A pinned version
- **WHEN** `SIDING_VERSION=v0.5.0` is set
- **THEN** the script installs that release instead of the latest

#### Scenario: Another platform
- **WHEN** the script runs on Windows or on a 32-bit system
- **THEN** it exits non-zero naming the platform and the supported ones, and installs nothing

#### Scenario: Update
- **WHEN** siding is installed and the script runs again after a newer release
- **THEN** the newer binary replaces the old one
Loading
Loading