From a92576483f7e47264517b4e104a69529a09e85af Mon Sep 17 00:00:00 2001 From: tweinmann Date: Thu, 29 Oct 2026 21:11:09 +0000 Subject: [PATCH 1/3] Propose the install script Co-Authored-By: Claude Opus 5.5 --- .../changes/install-script/.openspec.yaml | 2 + openspec/changes/install-script/design.md | 79 +++++++++++++++++++ openspec/changes/install-script/proposal.md | 36 +++++++++ .../install-script/specs/releases/spec.md | 50 ++++++++++++ openspec/changes/install-script/tasks.md | 17 ++++ 5 files changed, 184 insertions(+) create mode 100644 openspec/changes/install-script/.openspec.yaml create mode 100644 openspec/changes/install-script/design.md create mode 100644 openspec/changes/install-script/proposal.md create mode 100644 openspec/changes/install-script/specs/releases/spec.md create mode 100644 openspec/changes/install-script/tasks.md diff --git a/openspec/changes/install-script/.openspec.yaml b/openspec/changes/install-script/.openspec.yaml new file mode 100644 index 0000000..5c99d6d --- /dev/null +++ b/openspec/changes/install-script/.openspec.yaml @@ -0,0 +1,2 @@ +schema: spec-driven +created: 2026-10-29 diff --git a/openspec/changes/install-script/design.md b/openspec/changes/install-script/design.md new file mode 100644 index 0000000..d604ff6 --- /dev/null +++ b/openspec/changes/install-script/design.md @@ -0,0 +1,79 @@ +# Design + +## Context + +v0.5 builds `siding--` 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///releases/latest/download/` and a given +release's at `…/releases/download//`, 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 devcontainer guard of `hack/lib.sh`) builds with +`just dist v0.0.0-test` into a temporary directory, 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. diff --git a/openspec/changes/install-script/proposal.md b/openspec/changes/install-script/proposal.md new file mode 100644 index 0000000..98dd4c5 --- /dev/null +++ b/openspec/changes/install-script/proposal.md @@ -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. diff --git a/openspec/changes/install-script/specs/releases/spec.md b/openspec/changes/install-script/specs/releases/spec.md new file mode 100644 index 0000000..bd35674 --- /dev/null +++ b/openspec/changes/install-script/specs/releases/spec.md @@ -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 diff --git a/openspec/changes/install-script/tasks.md b/openspec/changes/install-script/tasks.md new file mode 100644 index 0000000..b77108f --- /dev/null +++ b/openspec/changes/install-script/tasks.md @@ -0,0 +1,17 @@ +# Tasks + +## 1. The script + +- [ ] 1.1 Write `install.sh` (D1–D5): platform, download with `curl` or `wget`, checksum, install to `~/.local/bin` or `SIDING_INSTALL_DIR`, `SIDING_VERSION`, the `PATH` hint, `siding version` and the next step, a clear message when no release is found; verify with `sh -n` and by the test in 1.2 +- [ ] 1.2 Write `hack/test-install.sh` (D6) and run it from `just test`: install, update, a broken checksum installing nothing, a directory missing from the `PATH`, an unsupported platform; verify that `just test` passes and leaves no temporary directory or server behind + +## 2. Documentation + +- [ ] 2.1 Rewrite step 1 of the README's "Get started": the one-liner, the download-read-run variant, `SIDING_VERSION` and `SIDING_INSTALL_DIR`, the manual way with `xattr` for browser downloads, and `go install`; verify the commands against a `just dist` build served locally +- [ ] 2.2 Add `install.sh` and `hack/test-install.sh` to CLAUDE.md's dev table where commands are listed, if they belong there; verify `openspec validate --all --strict` passes + +## Workflow follow-up + +- Stop and show the result; wait for the maintainer's approval. +- `/opsx:archive` merges the delta into `openspec/specs/`. +- After merging, tag `v0.5.0` and run the one-liner on the Mac against the real release. From 8e340677475f9087e2c10de6cab4160f5124ec96 Mon Sep 17 00:00:00 2001 From: tweinmann Date: Thu, 29 Oct 2026 21:13:14 +0000 Subject: [PATCH 2/3] Add install.sh, its test, and the one-line install in the README Co-Authored-By: Claude Opus 5.5 --- CLAUDE.md | 2 +- README.md | 28 +++++++- hack/test-install.sh | 69 ++++++++++++++++++ install.sh | 87 +++++++++++++++++++++++ justfile | 2 + openspec/changes/install-script/design.md | 5 +- openspec/changes/install-script/tasks.md | 8 +-- 7 files changed, 192 insertions(+), 9 deletions(-) create mode 100755 hack/test-install.sh create mode 100755 install.sh diff --git a/CLAUDE.md b/CLAUDE.md index b5ea09b..506b695 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -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 ` | 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 | diff --git a/README.md b/README.md index c8b295a..1d328da 100644 --- a/README.md +++ b/README.md @@ -65,6 +65,26 @@ 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 +``` + +
+Without the script + Download the binary for your platform and `SHA256SUMS` from the [latest release](https://github.com/tweinmann/siding/releases/latest), then: @@ -72,10 +92,14 @@ Download the binary for your platform and `SHA256SUMS` from the shasum -a 256 -c SHA256SUMS --ignore-missing # sha256sum on Linux chmod +x siding-darwin-arm64 # siding-- 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`. + +
+ The binaries are static and need nothing but Docker and git. To build siding yourself, see [Developing siding](#developing-siding). @@ -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 ` | the release binaries and `SHA256SUMS` in `dist/`, as CI builds them for a `v*` tag | diff --git a/hack/test-install.sh b/hack/test-install.sh new file mode 100755 index 0000000..428cc6e --- /dev/null +++ b/hack/test-install.sh @@ -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 + local name="$1" + shift + if "$@"; then echo "ok $name"; else echo "FAIL $name"; failed=1; fi +} +install() { # install [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" diff --git a/install.sh b/install.sh new file mode 100755 index 0000000..eb19929 --- /dev/null +++ b/install.sh @@ -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= install there instead of ~/.local/bin +# SIDING_DOWNLOAD_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" diff --git a/justfile b/justfile index 614a94d..0b014c4 100644 --- a/justfile +++ b/justfile @@ -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) diff --git a/openspec/changes/install-script/design.md b/openspec/changes/install-script/design.md index d604ff6..f590a9e 100644 --- a/openspec/changes/install-script/design.md +++ b/openspec/changes/install-script/design.md @@ -54,8 +54,9 @@ Alternative: `/usr/local/bin` by default (needs `sudo` on Linux and on many Macs manual way in the README keeps the `xattr` line for downloads through a browser. ### D6. The test -`hack/test-install.sh` (bash, the devcontainer guard of `hack/lib.sh`) builds with -`just dist v0.0.0-test` into a temporary directory, serves it with `python3 -m http.server` on a +`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 diff --git a/openspec/changes/install-script/tasks.md b/openspec/changes/install-script/tasks.md index b77108f..56f20d7 100644 --- a/openspec/changes/install-script/tasks.md +++ b/openspec/changes/install-script/tasks.md @@ -2,13 +2,13 @@ ## 1. The script -- [ ] 1.1 Write `install.sh` (D1–D5): platform, download with `curl` or `wget`, checksum, install to `~/.local/bin` or `SIDING_INSTALL_DIR`, `SIDING_VERSION`, the `PATH` hint, `siding version` and the next step, a clear message when no release is found; verify with `sh -n` and by the test in 1.2 -- [ ] 1.2 Write `hack/test-install.sh` (D6) and run it from `just test`: install, update, a broken checksum installing nothing, a directory missing from the `PATH`, an unsupported platform; verify that `just test` passes and leaves no temporary directory or server behind +- [x] 1.1 Write `install.sh` (D1–D5): platform, download with `curl` or `wget`, checksum, install to `~/.local/bin` or `SIDING_INSTALL_DIR`, `SIDING_VERSION`, the `PATH` hint, `siding version` and the next step, a clear message when no release is found; verify with `sh -n` and by the test in 1.2 +- [x] 1.2 Write `hack/test-install.sh` (D6) and run it from `just test`: install, update, a broken checksum installing nothing, a directory missing from the `PATH`, an unsupported platform; verify that `just test` passes and leaves no temporary directory or server behind ## 2. Documentation -- [ ] 2.1 Rewrite step 1 of the README's "Get started": the one-liner, the download-read-run variant, `SIDING_VERSION` and `SIDING_INSTALL_DIR`, the manual way with `xattr` for browser downloads, and `go install`; verify the commands against a `just dist` build served locally -- [ ] 2.2 Add `install.sh` and `hack/test-install.sh` to CLAUDE.md's dev table where commands are listed, if they belong there; verify `openspec validate --all --strict` passes +- [x] 2.1 Rewrite step 1 of the README's "Get started": the one-liner, the download-read-run variant, `SIDING_VERSION` and `SIDING_INSTALL_DIR`, the manual way with `xattr` for browser downloads, and `go install`; verify the commands against a `just dist` build served locally +- [x] 2.2 Add `install.sh` and `hack/test-install.sh` to CLAUDE.md's dev table where commands are listed, if they belong there; verify `openspec validate --all --strict` passes ## Workflow follow-up From 3ab8b74c2142e338b1c06f6a0eb8053a48b719c8 Mon Sep 17 00:00:00 2001 From: tweinmann Date: Thu, 29 Oct 2026 21:14:21 +0000 Subject: [PATCH 3/3] Archive the install script change and merge its spec Co-Authored-By: Claude Opus 5.5 --- .../2026-10-29-install-script}/.openspec.yaml | 0 .../2026-10-29-install-script}/design.md | 0 .../2026-10-29-install-script}/proposal.md | 0 .../specs/releases/spec.md | 0 .../2026-10-29-install-script}/tasks.md | 0 openspec/specs/releases/spec.md | 42 +++++++++++++++++-- 6 files changed, 39 insertions(+), 3 deletions(-) rename openspec/changes/{install-script => archive/2026-10-29-install-script}/.openspec.yaml (100%) rename openspec/changes/{install-script => archive/2026-10-29-install-script}/design.md (100%) rename openspec/changes/{install-script => archive/2026-10-29-install-script}/proposal.md (100%) rename openspec/changes/{install-script => archive/2026-10-29-install-script}/specs/releases/spec.md (100%) rename openspec/changes/{install-script => archive/2026-10-29-install-script}/tasks.md (100%) diff --git a/openspec/changes/install-script/.openspec.yaml b/openspec/changes/archive/2026-10-29-install-script/.openspec.yaml similarity index 100% rename from openspec/changes/install-script/.openspec.yaml rename to openspec/changes/archive/2026-10-29-install-script/.openspec.yaml diff --git a/openspec/changes/install-script/design.md b/openspec/changes/archive/2026-10-29-install-script/design.md similarity index 100% rename from openspec/changes/install-script/design.md rename to openspec/changes/archive/2026-10-29-install-script/design.md diff --git a/openspec/changes/install-script/proposal.md b/openspec/changes/archive/2026-10-29-install-script/proposal.md similarity index 100% rename from openspec/changes/install-script/proposal.md rename to openspec/changes/archive/2026-10-29-install-script/proposal.md diff --git a/openspec/changes/install-script/specs/releases/spec.md b/openspec/changes/archive/2026-10-29-install-script/specs/releases/spec.md similarity index 100% rename from openspec/changes/install-script/specs/releases/spec.md rename to openspec/changes/archive/2026-10-29-install-script/specs/releases/spec.md diff --git a/openspec/changes/install-script/tasks.md b/openspec/changes/archive/2026-10-29-install-script/tasks.md similarity index 100% rename from openspec/changes/install-script/tasks.md rename to openspec/changes/archive/2026-10-29-install-script/tasks.md diff --git a/openspec/specs/releases/spec.md b/openspec/specs/releases/spec.md index 6125208..b590749 100644 --- a/openspec/specs/releases/spec.md +++ b/openspec/specs/releases/spec.md @@ -33,10 +33,46 @@ binaries and `SHA256SUMS`. A failing check MUST publish nothing. - **THEN** no release is published ### Requirement: Install instructions -The README SHALL say how to install a released binary on macOS and Linux: download it for the -platform, check it against `SHA256SUMS`, make it executable, put it on the `PATH`, and on macOS -remove the quarantine flag of a downloaded, unsigned binary. +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 + +### 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