diff --git a/README.md b/README.md index 4bbc089..d32e0bf 100644 --- a/README.md +++ b/README.md @@ -19,7 +19,7 @@ The package is published to the Debian registry of the forge itself. One-time se curl -fsSL https://forgejo.heavyduty.builders/heavy-duty/stoke/raw/branch/main/scripts/install-apt.sh | bash ``` -or manually: +or manually. First add the forge's registry as an apt source: ```bash sudo install -d /etc/apt/keyrings @@ -27,10 +27,24 @@ curl -fsSL https://forgejo.heavyduty.builders/api/packages/heavy-duty/debian/rep | sudo tee /etc/apt/keyrings/forgejo-heavy-duty.asc >/dev/null echo "deb [signed-by=/etc/apt/keyrings/forgejo-heavy-duty.asc] https://forgejo.heavyduty.builders/api/packages/heavy-duty/debian stable main" \ | sudo tee /etc/apt/sources.list.d/forgejo-heavy-duty.list +``` + +The package depends on `nodejs (>= 22.12)`, which the distro archives of Debian 13 (Node 20) and Ubuntu 24.04 (Node 18) cannot satisfy — on those distros, also add a Node 22 source such as [NodeSource](https://deb.nodesource.com): + +```bash +curl -fsSL https://deb.nodesource.com/gpgkey/nodesource-repo.gpg.key \ + | sudo tee /etc/apt/keyrings/nodesource.asc >/dev/null +echo "deb [signed-by=/etc/apt/keyrings/nodesource.asc] https://deb.nodesource.com/node_22.x nodistro main" \ + | sudo tee /etc/apt/sources.list.d/nodesource.list +``` + +Then install: + +```bash sudo apt-get update && sudo apt-get install stoke ``` -Upgrades then arrive through regular `apt-get upgrade`. +Upgrades then arrive through regular `apt-get upgrade`. `install-apt.sh` performs all of the above, adding the NodeSource repository only when no already-configured apt source offers a new-enough nodejs. Note: apt releases that verify OpenPGP with `sqv` (Debian 13+, apt >= 2.9) currently reject the signature Forgejo generates for its Debian registry (an upstream signing bug). `install-apt.sh` detects this and falls back to a `[trusted=yes]` source — integrity then relies on HTTPS to the forge. The script prefers the signed source, so setups heal automatically once the forge is fixed. diff --git a/scripts/install-apt.sh b/scripts/install-apt.sh index 7823cf6..9e68c5d 100755 --- a/scripts/install-apt.sh +++ b/scripts/install-apt.sh @@ -18,9 +18,12 @@ FORGE_URL="${FORGE_URL:-https://forgejo.heavyduty.builders}" OWNER="${OWNER:-heavy-duty}" DISTRIBUTION="${DISTRIBUTION:-stable}" COMPONENT="${COMPONENT:-main}" +# Where apt configuration lives; overridable so tests can run against a +# throwaway directory instead of the real /etc/apt. +APT_ETC="${STOKE_APT_ETC:-/etc/apt}" -KEYRING="/etc/apt/keyrings/forgejo-$OWNER.asc" -LIST="/etc/apt/sources.list.d/forgejo-$OWNER.list" +KEYRING="$APT_ETC/keyrings/forgejo-$OWNER.asc" +LIST="$APT_ETC/sources.list.d/forgejo-$OWNER.list" SUDO="" if [ "$(id -u)" -ne 0 ]; then @@ -28,25 +31,69 @@ if [ "$(id -u)" -ne 0 ]; then SUDO="sudo" fi -update_only_this_source() { +update_only_source() { $SUDO apt-get update \ - -o Dir::Etc::sourcelist="$LIST" \ + -o Dir::Etc::sourcelist="$1" \ -o Dir::Etc::sourceparts=/dev/null \ -o APT::Get::List-Cleanup=0 } +# stoke needs Node.js >= 22.12 (commander 15), but the distro archives of +# Debian 13 (nodejs 20.x) and Ubuntu 24.04 (nodejs 18.x) cannot satisfy +# that, which would make `apt-get install stoke` fail with an unmet +# dependency. When no configured source offers a new-enough nodejs, add the +# NodeSource repository for Node 22 so the dependency resolves. +NODE_MIN="22.12" +node_candidate_ok() { + local candidate + # LC_ALL=C: the "Candidate:" label is localized. + candidate="$(LC_ALL=C apt-cache policy nodejs 2>/dev/null | sed -n 's/^ Candidate: //p')" + [ -n "$candidate" ] && [ "$candidate" != "(none)" ] || return 1 + dpkg --compare-versions "${candidate#*:}" ge "$NODE_MIN" +} + +ensure_nodejs_source() { + node_candidate_ok && return 0 + # The verdict may just be stale package lists — refresh (best effort, a + # transient failure of an unrelated source must not abort) and re-check + # before adding anything. + echo "No apt source seems to provide nodejs >= $NODE_MIN; refreshing apt metadata ..." + $SUDO apt-get update || true + node_candidate_ok && return 0 + local ns_keyring="$APT_ETC/keyrings/nodesource.asc" + local ns_list="$APT_ETC/sources.list.d/nodesource.list" + if [ -e "$ns_list" ]; then + echo "error: even after refreshing apt metadata, no source provides nodejs >= $NODE_MIN," >&2 + echo "and $ns_list already exists; refusing to overwrite it." >&2 + echo "Point it at a Node >= 22 release (e.g. node_22.x) and re-run." >&2 + exit 1 + fi + echo "Adding NodeSource (Node 22) ..." + curl -fsSL https://deb.nodesource.com/gpgkey/nodesource-repo.gpg.key | $SUDO tee "$ns_keyring" >/dev/null + echo "deb [signed-by=$ns_keyring] https://deb.nodesource.com/node_22.x nodistro main" \ + | $SUDO tee "$ns_list" >/dev/null + # tee inherits our umask; apt's unprivileged _apt user must be able to + # read these. + $SUDO chmod 0644 "$ns_keyring" "$ns_list" + update_only_source "$ns_list" + node_candidate_ok || { echo "error: still no nodejs >= $NODE_MIN available after adding NodeSource" >&2; exit 1; } +} + echo "Adding APT source for $FORGE_URL/$OWNER ..." -$SUDO install -d -m 0755 /etc/apt/keyrings +$SUDO install -d -m 0755 "$APT_ETC/keyrings" curl -fsSL "$FORGE_URL/api/packages/$OWNER/debian/repository.key" | $SUDO tee "$KEYRING" >/dev/null echo "deb [signed-by=$KEYRING] $FORGE_URL/api/packages/$OWNER/debian $DISTRIBUTION $COMPONENT" \ | $SUDO tee "$LIST" >/dev/null +# tee inherits our umask; apt's unprivileged _apt user must be able to +# read these. +$SUDO chmod 0644 "$KEYRING" "$LIST" # Newer apt verifies with sqv (Sequoia), which rejects the signature Forgejo # currently produces for its Debian registry (malformed Ed25519 MPI encoding # in the upstream signing library). Try the properly signed source first so # this heals automatically once the forge is fixed; otherwise fall back to # [trusted=yes] — package integrity then relies on HTTPS to our own forge. -if ! update_only_this_source; then +if ! update_only_source "$LIST"; then echo echo "WARNING: signature verification failed (known Forgejo registry issue" >&2 echo "with sqv-based apt). Falling back to [trusted=yes]; transport" >&2 @@ -54,9 +101,12 @@ if ! update_only_this_source; then echo echo "deb [trusted=yes] $FORGE_URL/api/packages/$OWNER/debian $DISTRIBUTION $COMPONENT" \ | $SUDO tee "$LIST" >/dev/null - update_only_this_source + $SUDO chmod 0644 "$LIST" + update_only_source "$LIST" fi +ensure_nodejs_source + $SUDO apt-get install -y stoke echo diff --git a/test/install-apt.test.js b/test/install-apt.test.js new file mode 100644 index 0000000..51dd362 --- /dev/null +++ b/test/install-apt.test.js @@ -0,0 +1,146 @@ +const { test } = require('node:test'); +const assert = require('node:assert/strict'); +const { spawnSync } = require('node:child_process'); +const fs = require('node:fs'); +const os = require('node:os'); +const path = require('node:path'); + +const SCRIPT = path.join(__dirname, '..', 'scripts', 'install-apt.sh'); + +// Runs install-apt.sh against a throwaway apt directory (STOKE_APT_ETC) with +// every external command stubbed via PATH. Scenario knobs: +// candInitial `apt-cache policy` Candidate before any update +// candAfterUpdate Candidate after any `apt-get update` +// candAfterNodesource Candidate after an update once nodesource.list exists +// The apt-cache stub localizes the "Candidate:" label unless LC_ALL=C is set, +// so every scenario doubles as a regression test for locale-safe parsing. +const cleanups = []; +process.on('exit', () => { for (const dir of cleanups) fs.rmSync(dir, { recursive: true, force: true }); }); + +function runScenario({ candInitial, candAfterUpdate, candAfterNodesource, preexistingNodesourceList }) { + const root = fs.mkdtempSync(path.join(os.tmpdir(), 'stoke-apt-test-')); + cleanups.push(root); + const bin = path.join(root, 'bin'); + const state = path.join(root, 'state'); + const aptEtc = path.join(root, 'etc', 'apt'); + fs.mkdirSync(bin, { recursive: true }); + fs.mkdirSync(state, { recursive: true }); + fs.mkdirSync(path.join(aptEtc, 'sources.list.d'), { recursive: true }); + fs.writeFileSync(path.join(state, 'candidate'), candInitial); + if (preexistingNodesourceList !== undefined) { + fs.writeFileSync(path.join(aptEtc, 'sources.list.d', 'nodesource.list'), preexistingNodesourceList); + } + + const stub = (name, body) => { + const p = path.join(bin, name); + fs.writeFileSync(p, `#!/usr/bin/env bash\n${body}\n`, { mode: 0o755 }); + }; + + // Force the non-root path so every mutation goes through the sudo stub. + stub('id', 'echo 1000'); + stub('sudo', 'exec "$@"'); + stub('curl', 'echo "FAKE-KEY"'); + stub('stoke', 'echo 1.2.0'); + stub('apt-cache', [ + 'cand="$(cat "$STATE_DIR/candidate")"', + '[ "$cand" = "absent" ] && exit 0', + 'label="Candidato"', + '[ "${LC_ALL:-}" = "C" ] && label="Candidate"', + 'printf "nodejs:\\n Installed: (none)\\n %s: %s\\n" "$label" "$cand"', + ].join('\n')); + stub('apt-get', [ + 'echo "apt-get $*" >> "$STATE_DIR/apt-get.log"', + 'for a in "$@"; do', + ' if [ "$a" = update ]; then', + ' if [ -e "$STOKE_APT_ETC/sources.list.d/nodesource.list" ] && [ -n "${CAND_AFTER_NODESOURCE:-}" ]; then', + ' echo "$CAND_AFTER_NODESOURCE" > "$STATE_DIR/candidate"', + ' elif [ -n "${CAND_AFTER_UPDATE:-}" ]; then', + ' echo "$CAND_AFTER_UPDATE" > "$STATE_DIR/candidate"', + ' fi', + ' fi', + 'done', + 'exit 0', + ].join('\n')); + + // Restrictive umask: apt-readable 0644 files must come from the script's + // explicit chmod, not from a lucky default. + const res = spawnSync('bash', ['-c', 'umask 077 && exec bash "$1"', 'bash', SCRIPT], { + encoding: 'utf8', + env: { + ...process.env, + PATH: `${bin}:${process.env.PATH}`, + STOKE_APT_ETC: aptEtc, + STATE_DIR: state, + CAND_AFTER_UPDATE: candAfterUpdate || '', + CAND_AFTER_NODESOURCE: candAfterNodesource || '', + LC_ALL: 'es_ES.UTF-8', // localized environment; the script must force C + }, + }); + + const read = (p) => (fs.existsSync(p) ? fs.readFileSync(p, 'utf8') : null); + const mode = (p) => (fs.existsSync(p) ? fs.statSync(p).mode & 0o777 : null); + return { + res, + aptEtc, + nodesourceList: read(path.join(aptEtc, 'sources.list.d', 'nodesource.list')), + nodesourceListMode: mode(path.join(aptEtc, 'sources.list.d', 'nodesource.list')), + nodesourceKey: read(path.join(aptEtc, 'keyrings', 'nodesource.asc')), + nodesourceKeyMode: mode(path.join(aptEtc, 'keyrings', 'nodesource.asc')), + forgeKeyMode: mode(path.join(aptEtc, 'keyrings', 'forgejo-heavy-duty.asc')), + aptGetLog: read(path.join(state, 'apt-get.log')) || '', + }; +} + +test('suitable nodejs candidate already available: installs without touching NodeSource', () => { + // Epoch-prefixed version also covers the epoch-stripping in the comparison. + const s = runScenario({ candInitial: '1:22.23.1-1nodesource1' }); + assert.equal(s.res.status, 0, s.res.stderr); + assert.equal(s.nodesourceList, null); + assert.match(s.aptGetLog, /install -y stoke/); + assert.equal(s.forgeKeyMode, 0o644, 'forge keyring must be readable by _apt'); +}); + +test('no cached metadata: refreshes apt lists before deciding, no NodeSource needed', () => { + const s = runScenario({ candInitial: 'absent', candAfterUpdate: '22.23.1-1nodesource1' }); + assert.equal(s.res.status, 0, s.res.stderr); + assert.equal(s.nodesourceList, null); + assert.match(s.aptGetLog, /install -y stoke/); +}); + +test('distro nodejs too old: bootstraps NodeSource and installs', () => { + const s = runScenario({ + candInitial: '20.19.2+dfsg-1+deb13u2', + candAfterUpdate: '20.19.2+dfsg-1+deb13u2', + candAfterNodesource: '22.23.1-1nodesource1', + }); + assert.equal(s.res.status, 0, s.res.stderr); + assert.match(s.nodesourceList, /deb \[signed-by=.*nodesource\.asc\] https:\/\/deb\.nodesource\.com\/node_22\.x nodistro main/); + assert.equal(s.nodesourceKey, 'FAKE-KEY\n'); + assert.equal(s.nodesourceKeyMode, 0o644, 'NodeSource keyring must be readable by _apt'); + assert.equal(s.nodesourceListMode, 0o644, 'NodeSource list must be readable by _apt'); + assert.match(s.aptGetLog, /install -y stoke/); +}); + +test('bootstrap failure: NodeSource still lacks a suitable nodejs, exits with error', () => { + const s = runScenario({ + candInitial: '20.19.2+dfsg-1+deb13u2', + candAfterUpdate: '20.19.2+dfsg-1+deb13u2', + candAfterNodesource: '20.19.2+dfsg-1+deb13u2', + }); + assert.notEqual(s.res.status, 0); + assert.match(s.res.stderr, /still no nodejs >= 22\.12/); + assert.doesNotMatch(s.aptGetLog, /install -y stoke/); +}); + +test('pre-existing user-managed nodesource.list is never overwritten', () => { + const marker = '# user-managed entry\n'; + const s = runScenario({ + candInitial: '18.19.1+dfsg-6ubuntu5', + candAfterUpdate: '18.19.1+dfsg-6ubuntu5', + preexistingNodesourceList: marker, + }); + assert.notEqual(s.res.status, 0); + assert.match(s.res.stderr, /refusing to overwrite/); + assert.equal(s.nodesourceList, marker); + assert.doesNotMatch(s.aptGetLog, /install -y stoke/); +});