Files
paperclip/scripts/test-install-sh-docker.sh
T
Nicky LeachandPaperclip 38d8f37172 fix(build): enforce Node 24 across Paperclip (#11792)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work.
> - Paperclip runs across the CLI, server, adapters, plugins, CI, and
container images.
> - These surfaces declared different Node.js versions from 20 through
24.
> - A newer `@types/node` major can expose APIs that the supported
runtime does not provide.
> - Node.js 20 is no longer a suitable project baseline, and Node.js 24
is the current LTS line.
> - This pull request sets Node.js 24.11.0 as one repository-wide
baseline, adds a drift check, and gives users actionable startup
guidance when their runtime is too old.
> - The benefit is one clear runtime contract for development, release,
installation, and published packages.

## Linked Issues or Issue Description

Refs #2734

Refs #11727

Refs #739

## What Changed

- Require Node.js 24.11.0 or newer in all 42 package manifests and
runtime checks.
- Use Node.js 24 in GitHub Actions, Docker images, smoke images, sandbox
setup, portable installs, and esbuild targets.
- Align every direct `@types/node` declaration on `^24.0.0`.
- Prevent Dependabot from opening major `@types/node` upgrades without a
matching runtime decision.
- Add `.nvmrc` and a CI policy check for Node version drift.
- Update ACP version gates, tests, and user documentation for the new
minimum.
- Print a non-blocking warning on CLI and server startup when Node is
unsupported, with remediation through a version manager or the
documented downloaded `install.sh` workflow.
- Deduplicate that warning when `paperclipai run` boots the CLI and
server in the same process.

## Verification

- `node scripts/check-node-version-policy.mjs`
- `node --check scripts/check-node-version-policy.mjs`
- `node --check cli/esbuild.config.mjs`
- `node --check scripts/generate-npm-package-json.mjs`
- `bash -n scripts/install.sh scripts/test-install-sh-docker.sh
scripts/e2e-install-lifecycle.sh`
- Parsed all 42 package manifests and confirmed `engines.node` is
`>=24.11.0`.
- `git diff --check`
- `vitest run
packages/adapter-utils/src/sandbox-install-command.test.ts` passed with
3 tests.
- `vitest run cli/src/node-version.test.ts` passed with 4 tests.
- Directly exercised the shared warning helper for unsupported-version
messaging and same-process deduplication.
- The focused exe.dev suite could not resolve the locally unbuilt plugin
SDK from this isolated worktree. A full offline workspace install was
also blocked because the package-manager signature verifier requires
registry access. The full suite was not run locally; draft CI performs a
clean install and evaluates the wider impact.

## Risks

- This is a breaking runtime change for users, plugins, and deployments
that still use Node.js 20 or 22.
- Published workspace packages will now produce an engine warning or
failure in strict package managers on older Node.js releases.
- Node.js 24 can reveal dependency, native module, Playwright, or agent
CLI compatibility issues in CI.
- The bootstrap installer now installs Node.js 24 when the current
runtime is older than 24.11.0.
- The portable sandbox fallback is pinned to Node.js 24.11.0 and depends
on that upstream tarball remaining available.
- Unsupported runtimes continue booting after a warning, so a later
incompatibility can still fail at its point of use.
- The CLI and server share the warning policy through the published
`@paperclipai/shared` package; packaging checks must keep that subpath
export available.
- This PR does not commit `pnpm-lock.yaml` because repository policy
assigns lockfile generation to CI.

> For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and
discuss it in `#dev` before opening the PR. Feature PRs that overlap
with planned core work may need to be redirected — check the roadmap
first. See `CONTRIBUTING.md`.

## Model Used

- OpenAI Codex based on GPT-5. The exact deployment ID and context
window are not exposed in this session. Reasoning, repository tools,
shell execution, and GitHub tools were enabled.

## Checklist

- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [x] All Paperclip CI gates are green
- [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge

---------

Co-authored-by: Paperclip <noreply@paperclip.ing>
2026-08-21 10:17:52 -07:00

170 lines
6.2 KiB
Bash
Executable File

#!/usr/bin/env bash
set -euo pipefail
REPO_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
RESULTS_DIR="$(mktemp -d "${TMPDIR:-/tmp}/paperclip-install-sh.XXXXXX")"
KEEP_RESULTS="${KEEP_RESULTS:-0}"
cleanup() {
if [ "$KEEP_RESULTS" = "1" ]; then
printf 'Kept installer test results at %s\n' "$RESULTS_DIR"
return
fi
rm -rf "$RESULTS_DIR"
}
trap cleanup EXIT
command -v docker >/dev/null 2>&1 || {
echo "docker is required" >&2
exit 1
}
run_shellcheck() {
docker run --rm \
-v "$REPO_ROOT:/work:ro" \
-w /work \
koalaman/shellcheck:stable \
scripts/install.sh scripts/test-install-sh-docker.sh scripts/install-sh-fixtures/npx
}
run_with_node() {
local name="$1"
shift
docker run --rm \
-v "$REPO_ROOT/scripts:/paperclip-scripts:ro" \
-v "$RESULTS_DIR:/results" \
-e "PAPERCLIP_INSTALL_TEST_LOG=/results/$name.args" \
-e PATH="/paperclip-scripts/install-sh-fixtures:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin" \
node:24-bookworm-slim \
"$@"
}
assert_line() {
local file="$1"
local expected="$2"
grep -Fx -- "$expected" "$file" >/dev/null || {
printf 'Expected %q in %s\n' "$expected" "$file" >&2
cat "$file" >&2
exit 1
}
}
assert_no_line() {
local file="$1"
local unexpected="$2"
if grep -Fx -- "$unexpected" "$file" >/dev/null; then
printf 'Did not expect %q in %s\n' "$unexpected" "$file" >&2
cat "$file" >&2
exit 1
fi
}
echo "==> shellcheck"
run_shellcheck
echo "==> existing Node"
run_with_node with-node bash /paperclip-scripts/install.sh --no-prompt --no-onboard
assert_line "$RESULTS_DIR/with-node.args" "paperclipai@latest"
assert_line "$RESULTS_DIR/with-node.args" "install"
assert_line "$RESULTS_DIR/with-node.args" "--yes"
assert_line "$RESULTS_DIR/with-node.args" "--registry=https://registry.npmjs.org"
assert_line "$RESULTS_DIR/with-node.args" "NPM_CONFIG_REGISTRY=https://registry.npmjs.org"
assert_line "$RESULTS_DIR/with-node.args" "npm_config_registry=https://registry.npmjs.org"
assert_line "$RESULTS_DIR/with-node.args" "npmrc:registry=https://registry.npmjs.org"
echo "==> hostile npm config isolation"
mkdir -p "$RESULTS_DIR/hostile-home"
printf 'registry=http://attacker-registry.invalid\n' >"$RESULTS_DIR/hostile-home/.npmrc"
docker run --rm \
-v "$REPO_ROOT/scripts:/paperclip-scripts:ro" \
-v "$RESULTS_DIR:/results" \
-e HOME=/results/hostile-home \
-e NPM_CONFIG_REGISTRY=http://attacker-registry.invalid \
-e npm_config_registry=http://attacker-registry.invalid \
-e PAPERCLIP_INSTALL_TEST_LOG=/results/hostile.args \
-e PATH="/paperclip-scripts/install-sh-fixtures:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin" \
node:24-bookworm-slim \
bash /paperclip-scripts/install.sh --no-prompt --no-onboard
assert_line "$RESULTS_DIR/hostile.args" "--registry=https://registry.npmjs.org"
assert_line "$RESULTS_DIR/hostile.args" "NPM_CONFIG_REGISTRY=https://registry.npmjs.org"
assert_line "$RESULTS_DIR/hostile.args" "npm_config_registry=https://registry.npmjs.org"
assert_line "$RESULTS_DIR/hostile.args" "npmrc:registry=https://registry.npmjs.org"
echo "==> --ref master"
if run_with_node ref-master bash /paperclip-scripts/install.sh --ref master --no-onboard; then
echo "Expected --ref to fail until git-ref installation support is integrated" >&2
exit 1
fi
[ ! -e "$RESULTS_DIR/ref-master.args" ] || {
echo "Expected --ref failure before invoking npx" >&2
exit 1
}
echo "==> piped mode requires explicit consent"
if run_with_node piped-rejected bash -c 'cat /paperclip-scripts/install.sh | bash -s -- --no-onboard'; then
echo "Expected piped install without --no-prompt to fail" >&2
exit 1
fi
echo "==> piped --no-prompt"
run_with_node piped bash -c 'cat /paperclip-scripts/install.sh | bash -s -- --no-prompt --no-onboard'
assert_line "$RESULTS_DIR/piped.args" "--yes"
echo "==> piped mode refuses privileged Node bootstrap"
if docker run --rm \
-v "$REPO_ROOT/scripts:/paperclip-scripts:ro" \
-e PATH="/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin" \
ubuntu:24.04 \
bash -c 'cat /paperclip-scripts/install.sh | bash -s -- --no-prompt --no-onboard' \
>"$RESULTS_DIR/piped-no-node.out" 2>&1; then
echo "Expected piped install without Node.js to fail before privileged bootstrap" >&2
exit 1
fi
assert_line "$RESULTS_DIR/piped-no-node.out" "[paperclip] error: Node.js bootstrap is disabled for piped installs; download install.sh, review it, and run 'bash install.sh --no-prompt'"
echo "==> dry run"
run_with_node dry-run bash /paperclip-scripts/install.sh --no-prompt --dry-run --no-onboard
[ ! -e "$RESULTS_DIR/dry-run.args" ] || {
echo "Expected --dry-run to avoid invoking npx" >&2
exit 1
}
echo "==> environment twins"
docker run --rm \
-v "$REPO_ROOT/scripts:/paperclip-scripts:ro" \
-v "$RESULTS_DIR:/results" \
-e PAPERCLIP_INSTALL_TEST_LOG=/results/env.args \
-e PAPERCLIP_INSTALL_VERSION=2026.722.0 \
-e PAPERCLIP_INSTALL_INSTALL_SERVICE=1 \
-e PAPERCLIP_INSTALL_NO_ONBOARD=1 \
-e PAPERCLIP_INSTALL_NO_PROMPT=1 \
-e PATH="/paperclip-scripts/install-sh-fixtures:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin" \
node:24-bookworm-slim \
bash /paperclip-scripts/install.sh
assert_line "$RESULTS_DIR/env.args" "paperclipai@2026.722.0"
assert_line "$RESULTS_DIR/env.args" "--version"
assert_line "$RESULTS_DIR/env.args" "2026.722.0"
assert_no_line "$RESULTS_DIR/env.args" "--repo"
assert_no_line "$RESULTS_DIR/env.args" "--install-service"
assert_line "$RESULTS_DIR/env.args" "service"
echo "==> no Node, apt bootstrap"
docker run --rm \
-v "$REPO_ROOT/scripts:/paperclip-scripts:ro" \
-v "$RESULTS_DIR:/results" \
-e PAPERCLIP_INSTALL_TEST_LOG=/results/no-node.args \
-e PATH="/paperclip-scripts/install-sh-fixtures:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin" \
ubuntu:24.04 \
bash -c 'apt-get update >/dev/null && apt-get install -y ca-certificates curl >/dev/null && bash /paperclip-scripts/install.sh --no-prompt --no-onboard'
assert_line "$RESULTS_DIR/no-node.args" "paperclipai@latest"
node_version="$(cat "$RESULTS_DIR/no-node.args.node")"
node_major="${node_version#v}"
node_major="${node_major%%.*}"
[ "$node_major" -ge 24 ] || {
printf 'Expected Node >= 24, got %s\n' "$node_version" >&2
exit 1
}
echo "Installer Docker checks passed."