From dfde5004bc4f51bace3c1dd6dfaa3cc6b4ac9728 Mon Sep 17 00:00:00 2001 From: Florin Munteanu Date: Wed, 4 Nov 2026 17:36:51 +0200 Subject: [PATCH] Install DevCapsule with one command, on Linux and on Apple Silicon Macs A release now builds devcapsule-linux-arm64 and devcapsule-macos-arm64 on native runners beside devcapsule.pex, records them in the release manifest, and publishes SHA256SUMS and an install.sh with the release's own URL written in. The script picks the executable for the computer, checks every file against SHA256SUMS before installing anything, and on a Mac puts both Linux runtimes in ~/.local/lib/devcapsule. A packaged launcher now looks there when DEVCAPSULE_RUNTIME_PEX is unset, so a Mac needs no profile edit. The install page leads with the one command and keeps the manual Linux x86-64 steps; the macOS page installs from the release and keeps the source build for unreleased commits. Co-Authored-By: Claude Opus 5.5 --- .github/workflows/release-pex.yml | 125 ++++++++++++++-- CURRENT-STATUS.md | 2 +- devcapsule-src/devcapsule/runtime_artifact.py | 27 +++- devcapsule-src/scripts/install.sh | 102 +++++++++++++ devcapsule-src/scripts/release-manifest.py | 21 ++- .../tests/integration/test_install_script.py | 135 ++++++++++++++++++ .../unit/devcapsule/test_runtime_artifact.py | 109 ++++++++++++++ docs/getting-started/install.md | 65 ++++++--- docs/platforms/linux.md | 8 +- docs/platforms/macos.md | 59 ++++---- engineering-docs/development/e2e-tests.md | 2 +- .../2026-11-04-linux-arm64/CURRENT-STATUS.md | 45 ++++-- 12 files changed, 621 insertions(+), 79 deletions(-) create mode 100755 devcapsule-src/scripts/install.sh create mode 100644 devcapsule-src/tests/integration/test_install_script.py create mode 100644 devcapsule-src/tests/unit/devcapsule/test_runtime_artifact.py diff --git a/.github/workflows/release-pex.yml b/.github/workflows/release-pex.yml index 5c17f44f..8b40a280 100644 --- a/.github/workflows/release-pex.yml +++ b/.github/workflows/release-pex.yml @@ -20,8 +20,73 @@ concurrency: cancel-in-progress: false jobs: + # The Linux x86-64 executable, devcapsule.pex, is built and proven below. + # These are the other platforms' executables of the same tag, each built on + # its own architecture: the install script picks the one for the computer, + # and on a Mac also takes both Linux ones as the runtimes its capsules run. + build-other-platforms: + name: Build ${{ matrix.asset }} + runs-on: ${{ matrix.runner }} + strategy: + matrix: + include: + - runner: ubuntu-24.04-arm + scie-platform: linux-aarch64 + asset: devcapsule-linux-arm64 + - runner: macos-15 + scie-platform: macos-aarch64 + asset: devcapsule-macos-arm64 + env: + RELEASE_TAG: ${{ github.event_name == 'push' && github.ref_name || inputs.release_tag }} + defaults: + run: + working-directory: devcapsule-src + + steps: + - name: Check out the release tag + uses: actions/checkout@v4 + with: + ref: ${{ env.RELEASE_TAG }} + fetch-depth: 0 + + - name: Set up Python 3.12 for the backend build + uses: actions/setup-python@v5 + with: + python-version: "3.12" + cache: pip + cache-dependency-path: devcapsule-src/dev-requirements.txt + + - name: Install locked build dependencies + run: | + python -m pip install --upgrade pip + python -m pip install -r dev-requirements.txt + python -m pip install -e . --no-deps + + - name: Build and smoke the self-contained executable + env: + DEVCAPSULE_SOURCE_REPOSITORY: ${{ github.server_url }}/${{ github.repository }} + DEVCAPSULE_SCIE_PLATFORM: ${{ matrix.scie-platform }} + ASSET: ${{ matrix.asset }} + run: | + scripts/build-pex.sh \ + --source-revision "$(git rev-parse HEAD)" \ + --release-mnemonic "$RELEASE_TAG" \ + --output "dist/$ASSET" + "dist/$ASSET" --help >/dev/null + "dist/$ASSET" version --json | tee "$RUNNER_TEMP/version.json" + test "$(python -c 'import json, sys; print(json.load(open(sys.argv[1]))["build_mnemonic"])' "$RUNNER_TEMP/version.json")" = "$RELEASE_TAG" + + - name: Hand the executable to the publishing job + uses: actions/upload-artifact@v4 + with: + name: ${{ matrix.asset }} + path: devcapsule-src/dist/${{ matrix.asset }} + if-no-files-found: error + retention-days: 30 + build-publish-and-prove: name: Build, publish, and prove + needs: build-other-platforms runs-on: ubuntu-24.04 env: RELEASE_TAG: ${{ github.event_name == 'push' && github.ref_name || inputs.release_tag }} @@ -91,10 +156,13 @@ jobs: if grep -Fxq "$RELEASE_TAG" "$RUNNER_TEMP/releases"; then gh release download "$RELEASE_TAG" --dir dist \ --pattern devcapsule.pex --pattern devcapsule.pex.sha256 \ + --pattern devcapsule-linux-arm64 --pattern devcapsule-macos-arm64 \ + --pattern SHA256SUMS --pattern install.sh \ --pattern release-manifest.json - (cd dist && sha256sum --check devcapsule.pex.sha256) - chmod 0755 dist/devcapsule.pex - manifest_args=(--gate "$RUNNER_TEMP/release-gate.json") + (cd dist && sha256sum --check devcapsule.pex.sha256 && sha256sum --check SHA256SUMS) + chmod 0755 dist/devcapsule.pex dist/devcapsule-linux-arm64 dist/devcapsule-macos-arm64 + manifest_args=(--gate "$RUNNER_TEMP/release-gate.json" + --artifact dist/devcapsule-linux-arm64 --artifact dist/devcapsule-macos-arm64) if [ "$RELEASE_PRERELEASE" = false ]; then manifest_args+=(--candidate "$RUNNER_TEMP/accepted-candidate/release-manifest.json") fi @@ -103,6 +171,14 @@ jobs: echo 'exists=true' >> "$GITHUB_OUTPUT" fi + - name: Take the other platforms' executables + if: steps.recover.outputs.exists != 'true' + uses: actions/download-artifact@v4 + with: + pattern: devcapsule-*-arm64 + merge-multiple: true + path: devcapsule-src/dist + - name: Build the self-contained release PEX if: steps.recover.outputs.exists != 'true' env: @@ -114,13 +190,28 @@ jobs: dist/devcapsule.pex --help >/dev/null dist/devcapsule.pex version --json | tee dist/devcapsule-version.json test "$(python -c 'import json; print(json.load(open("dist/devcapsule-version.json"))["build_mnemonic"])')" = "$RELEASE_TAG" + chmod 0755 dist/devcapsule-linux-arm64 dist/devcapsule-macos-arm64 (cd dist && sha256sum devcapsule.pex > devcapsule.pex.sha256) - manifest_args=(--gate "$RUNNER_TEMP/release-gate.json") + (cd dist && sha256sum devcapsule.pex devcapsule-linux-arm64 devcapsule-macos-arm64 > SHA256SUMS) + manifest_args=(--gate "$RUNNER_TEMP/release-gate.json" + --artifact dist/devcapsule-linux-arm64 --artifact dist/devcapsule-macos-arm64) if [ "$RELEASE_PRERELEASE" = false ]; then manifest_args+=(--candidate "$RUNNER_TEMP/accepted-candidate/release-manifest.json") fi python scripts/release-manifest.py "$RELEASE_TAG" "$(git rev-parse HEAD)" "${manifest_args[@]}" + - name: Write the install script for this release + run: | + release_url="$GITHUB_SERVER_URL/$GITHUB_REPOSITORY/releases/download/$RELEASE_TAG" + sed "s|@RELEASE_URL@|$release_url|" scripts/install.sh > "$RUNNER_TEMP/install.sh" + if grep -q '@RELEASE_URL@' "$RUNNER_TEMP/install.sh"; then exit 1; fi + sh -n "$RUNNER_TEMP/install.sh" + if [ "${{ steps.recover.outputs.exists }}" = true ]; then + cmp "$RUNNER_TEMP/install.sh" dist/install.sh + else + install -m 0755 "$RUNNER_TEMP/install.sh" dist/install.sh + fi + - name: Run packaging integration tests against the release PEX env: DEVCAPSULE_PEX_UNDER_TEST: ${{ github.workspace }}/devcapsule-src/dist/devcapsule.pex @@ -142,6 +233,10 @@ jobs: path: | devcapsule-src/dist/devcapsule.pex devcapsule-src/dist/devcapsule.pex.sha256 + devcapsule-src/dist/devcapsule-linux-arm64 + devcapsule-src/dist/devcapsule-macos-arm64 + devcapsule-src/dist/SHA256SUMS + devcapsule-src/dist/install.sh devcapsule-src/dist/release-manifest.json if-no-files-found: error retention-days: 30 @@ -150,8 +245,12 @@ jobs: if: steps.recover.outputs.exists != 'true' && env.RELEASE_PRERELEASE == 'true' run: | gh release create "$RELEASE_TAG" \ + "dist/install.sh#Installer for Linux and Apple Silicon Macs" \ "dist/devcapsule.pex#Self-contained Linux x86-64 CLI" \ + "dist/devcapsule-linux-arm64#Self-contained Linux ARM64 CLI (experimental)" \ + "dist/devcapsule-macos-arm64#Self-contained macOS Apple Silicon CLI (experimental)" \ "dist/devcapsule.pex.sha256#SHA-256 checksum" \ + "dist/SHA256SUMS#SHA-256 checksums of every executable" \ "dist/release-manifest.json#Release inputs and artifact checksums" \ --verify-tag --generate-notes --draft --prerelease="$RELEASE_PRERELEASE" --latest=false @@ -160,8 +259,12 @@ jobs: run: | python scripts/release-docs.py notes "${RELEASE_TAG#v}" > "$RUNNER_TEMP/release-notes.md" gh release create "$RELEASE_TAG" \ + "dist/install.sh#Installer for Linux and Apple Silicon Macs" \ "dist/devcapsule.pex#Self-contained Linux x86-64 CLI" \ + "dist/devcapsule-linux-arm64#Self-contained Linux ARM64 CLI (experimental)" \ + "dist/devcapsule-macos-arm64#Self-contained macOS Apple Silicon CLI (experimental)" \ "dist/devcapsule.pex.sha256#SHA-256 checksum" \ + "dist/SHA256SUMS#SHA-256 checksums of every executable" \ "dist/release-manifest.json#Release inputs and artifact checksums" \ --verify-tag --notes-file "$RUNNER_TEMP/release-notes.md" --draft --prerelease="$RELEASE_PRERELEASE" --latest=false @@ -172,11 +275,16 @@ jobs: gh release download "$RELEASE_TAG" \ --pattern devcapsule.pex \ --pattern devcapsule.pex.sha256 \ + --pattern devcapsule-linux-arm64 \ + --pattern devcapsule-macos-arm64 \ + --pattern SHA256SUMS \ + --pattern install.sh \ --pattern release-manifest.json \ --dir "$published" - (cd "$published" && sha256sum --check devcapsule.pex.sha256) - cmp dist/devcapsule.pex "$published/devcapsule.pex" - cmp dist/release-manifest.json "$published/release-manifest.json" + (cd "$published" && sha256sum --check devcapsule.pex.sha256 && sha256sum --check SHA256SUMS) + for asset in devcapsule.pex devcapsule-linux-arm64 devcapsule-macos-arm64 SHA256SUMS install.sh release-manifest.json; do + cmp "dist/$asset" "$published/$asset" + done chmod 0755 "$published/devcapsule.pex" - name: Publish the complete release @@ -216,6 +324,7 @@ jobs: echo echo "- Tag: \`$RELEASE_TAG\`" echo "- Revision: \`$(git rev-parse HEAD)\`" - echo "- $(cat dist/devcapsule.pex.sha256)" + echo "- Executables:" + sed 's/^/ - /' dist/SHA256SUMS echo "- Built and retested after downloading from GitHub Releases" } >> "$GITHUB_STEP_SUMMARY" diff --git a/CURRENT-STATUS.md b/CURRENT-STATUS.md index 6ed04b08..662d64b0 100644 --- a/CURRENT-STATUS.md +++ b/CURRENT-STATUS.md @@ -21,7 +21,7 @@ coordination branch. Detailed state belongs in each linked status file. | `capsule-webconsole` | 2026-10-09 | Serve a token-gated web console from every capsule: configuration, versions, info, live resources, later records and workflow state | active; work order accepted 2026-10-09; the first iteration, deliverables 1 and 2, is three stacked pull requests, #184, #186 and the runtime-and-base slice, each reviewed by the Codex pair; the owner merges | `ws-capsule-webconsole/first-slice` | [workstream status](engineering-docs/wip/2026-10-09-capsule-webconsole/CURRENT-STATUS.md) | | `wrapped-projects` | 2026-11-02 | Wrap a foreign repository as a submodule of a small wrapper project and work on it in a capsule with three commands; FRC learning project first | active; PR1 (#333) accepted by the owner 2026-11-03, awaiting merge; the project-capabilities design handed to workflow-improvements | `ws-wrapped-projects/wrap` | [workstream status](engineering-docs/wip/2026-11-02-wrapped-projects/CURRENT-STATUS.md) | | `macos-launcher` | 2026-11-03 | Run the DevCapsule launcher natively on Apple Silicon Macs against Docker Desktop, with capsules as `linux-amd64` under emulation | active 2026-11-03; slices 1 to 4 done, the PyCharm smoke passing on an Apple Silicon Mac; waits on publication and the owner's rulings | `ws-macos-launcher/host-port` | [workstream status](engineering-docs/wip/2026-11-03-macos-launcher/CURRENT-STATUS.md) | -| `linux-arm64` | 2026-11-04 | Run capsules as `linux-arm64` as well as `linux-amd64`: natively on Apple Silicon Macs and on ARM Linux hosts | active 2026-11-04; slices 1 to 4 done, six IDEs running natively on Apple Silicon; waits on publication, the owner's arm64 base and rulings | `ws-linux-arm64/capsules` | [workstream status](engineering-docs/wip/2026-11-04-linux-arm64/CURRENT-STATUS.md) | +| `linux-arm64` | 2026-11-04 | Run capsules as `linux-arm64` as well as `linux-amd64`: natively on Apple Silicon Macs and on ARM Linux hosts | active 2026-11-04; slices 1 to 4 merged in #338; the one-line install (per-platform release executables, `install.sh`) awaits its pull request; the owner's arm64 base and rulings follow | `ws-linux-arm64/one-line-install` | [workstream status](engineering-docs/wip/2026-11-04-linux-arm64/CURRENT-STATUS.md) | | `website` | 2026-09-16 | Deliver the website autonomy experiment: repository-owned landing/docs/blog content, independently developable website submodule, local preview and publishing mechanism | paused 2026-09-20 at owner request to switch to maintenance; experiment accepted, A−; blog integrated and published; content/parent-integration follow-ups remain | `ws-website/initial-cut`; renamed from `website/initial-cut`; preparation and backlog-handoff exceptions in status | [workstream status](engineering-docs/wip/2026-09-16-website/CURRENT-STATUS.md) | Paused and blocked workstreams remain open until they conclude successfully or diff --git a/devcapsule-src/devcapsule/runtime_artifact.py b/devcapsule-src/devcapsule/runtime_artifact.py index 476a16c5..abb4d139 100644 --- a/devcapsule-src/devcapsule/runtime_artifact.py +++ b/devcapsule-src/devcapsule/runtime_artifact.py @@ -10,8 +10,16 @@ from devcapsule.compat import CliError from devcapsule.platforms import HostOs, Platform +__all__ = ["DEFAULT_RUNTIME_DIRECTORY", "RUNTIME_PEX_ENV", "executable_platform", "runtime_artifact"] + RUNTIME_PEX_ENV = "DEVCAPSULE_RUNTIME_PEX" +DEFAULT_RUNTIME_DIRECTORY = "~/.local/lib/devcapsule" +"""Where a packaged launcher looks for its runtimes when ``DEVCAPSULE_RUNTIME_PEX`` is unset. + +The release's install script puts a Mac's Linux runtimes here. +""" + _MACH_O_MAGICS = (b"\xcf\xfa\xed\xfe", b"\xce\xfa\xed\xfe", b"\xca\xfe\xba\xbe") _UNKNOWN_REVISION = "unknown" @@ -23,10 +31,11 @@ def runtime_artifact(capsule_platform: Platform) -> Path: (D-0009). A launcher that cannot, such as a macOS executable launching Linux capsules, delivers the runtime ``DEVCAPSULE_RUNTIME_PEX`` names: one executable, or a directory holding one per capsule platform as - ``devcapsule-``. A source-form launcher names its built runtime - the same way. A delivered runtime that is not the launcher's own bytes - must be the launcher's build: the same version, and the same source - revision wherever both record one (R-RUNTIME-001). + ``devcapsule-``. Unset, it delivers the ``devcapsule-`` + in ``DEFAULT_RUNTIME_DIRECTORY`` when there is one. A source-form launcher + names its built runtime with the variable. A delivered runtime that is not + the launcher's own bytes must be the launcher's build: the same version, + and the same source revision wherever both record one (R-RUNTIME-001). """ # scie preserves the executable's path in SCIE; PEX points to the original @@ -38,6 +47,8 @@ def runtime_artifact(capsule_platform: Platform) -> Path: delivered = own elif named: delivered = _named_runtime(Path(named).expanduser(), capsule_platform) + elif own is not None and (installed := _installed_runtime(capsule_platform)) is not None: + delivered = installed else: delivered = own or _resolved(sys.argv[0]) try: @@ -52,7 +63,8 @@ def runtime_artifact(capsule_platform: Platform) -> Path: raise CliError( f"{delivered} is {_describe(executable_platform(delivered))} and cannot run inside " f"{capsule_platform} capsules. Set {RUNTIME_PEX_ENV} to a {capsule_platform} DevCapsule " - f"executable of the same version, or to a directory holding it as devcapsule-{capsule_platform}." + f"executable of the same version, or to a directory holding it as devcapsule-{capsule_platform}, " + f"or put it in {DEFAULT_RUNTIME_DIRECTORY} as devcapsule-{capsule_platform}." ) if delivered != own: _require_same_build(delivered, delivered_build, current_build_info()) @@ -94,6 +106,11 @@ def _runs_in(path: Path, capsule_platform: Platform) -> bool: return runs_on == capsule_platform +def _installed_runtime(capsule_platform: Platform) -> Path | None: + candidate = Path(DEFAULT_RUNTIME_DIRECTORY).expanduser() / f"devcapsule-{capsule_platform}" + return _resolved(str(candidate)) if candidate.is_file() else None + + def _named_runtime(named: Path, capsule_platform: Platform) -> Path: if not named.is_dir(): return _resolved(str(named)) diff --git a/devcapsule-src/scripts/install.sh b/devcapsule-src/scripts/install.sh new file mode 100755 index 00000000..e67812aa --- /dev/null +++ b/devcapsule-src/scripts/install.sh @@ -0,0 +1,102 @@ +#!/bin/sh +# Install DevCapsule from one GitHub release: +# +# curl -fsSL /install.sh | sh +# +# It picks the executable for this computer and, on a Mac, also the Linux +# runtimes its capsules run, which the launcher finds in ~/.local/lib/devcapsule. +# Every file is checked against the release's SHA256SUMS before anything is +# installed. The release workflow writes its own URL over @RELEASE_URL@; +# DEVCAPSULE_RELEASE_URL overrides it, for a mirror or a test. Everything runs +# in main, called on the last line, so a download cut short runs nothing. +set -eu + +RELEASE_URL="@RELEASE_URL@" + +main() { + release_url="${DEVCAPSULE_RELEASE_URL:-$RELEASE_URL}" + case "$release_url" in + https://* | http://* | file://*) ;; + *) die "this install.sh names no release; download it from a DevCapsule release" ;; + esac + bin_dir="$HOME/.local/bin" + runtime_dir="$HOME/.local/lib/devcapsule" + + os="$(uname -s)" + machine="$(uname -m)" + # A shell under Rosetta reports x86_64 on an Apple Silicon Mac. + if [ "$os" = Darwin ] && [ "$(sysctl -n hw.optional.arm64 2>/dev/null || true)" = 1 ]; then + machine=arm64 + fi + case "$os-$machine" in + Linux-x86_64 | Linux-amd64) launcher=devcapsule.pex ;; + Linux-aarch64 | Linux-arm64) launcher=devcapsule-linux-arm64 ;; + Darwin-arm64) launcher=devcapsule-macos-arm64 ;; + Darwin-*) die "DevCapsule runs on Apple Silicon Macs only" ;; + *) die "DevCapsule has no executable for $os $machine" ;; + esac + files="$launcher" + if [ "$os" = Darwin ]; then + files="$files devcapsule.pex devcapsule-linux-arm64" + fi + + command -v curl >/dev/null 2>&1 || die "curl is required" + if command -v sha256sum >/dev/null 2>&1; then + sha256="sha256sum" + elif command -v shasum >/dev/null 2>&1; then + sha256="shasum -a 256" + else + die "sha256sum or shasum is required to verify the download" + fi + + work="$(mktemp -d)" + trap 'rm -rf "$work"' EXIT + trap 'exit 1' INT TERM + cd "$work" + + fetch SHA256SUMS + for file in $files; do + echo "Downloading $file" + fetch "$file" + verify "$file" + done + + if [ "$os" = Darwin ]; then + mkdir -p "$runtime_dir" + install -m 0755 devcapsule.pex "$runtime_dir/devcapsule-linux-amd64" + install -m 0755 devcapsule-linux-arm64 "$runtime_dir/devcapsule-linux-arm64" + echo "Installed the Linux runtimes in $runtime_dir" + fi + mkdir -p "$bin_dir" + install -m 0755 "$launcher" "$bin_dir/devcapsule" + echo "Installed $bin_dir/devcapsule" + "$bin_dir/devcapsule" version + + if [ "$os" = Darwin ] && [ -n "${DEVCAPSULE_RUNTIME_PEX:-}" ]; then + echo "DEVCAPSULE_RUNTIME_PEX is set to $DEVCAPSULE_RUNTIME_PEX, so the launcher uses that instead of" + echo "$runtime_dir. Remove it from your shell profile to use the runtimes just installed." + fi + case ":$PATH:" in + *":$bin_dir:"*) ;; + *) echo "Add $bin_dir to PATH in your shell profile to run devcapsule by name." ;; + esac +} + +die() { + echo "devcapsule install: $*" >&2 + exit 1 +} + +fetch() { + curl --fail --silent --show-error --location --output "$1" "$release_url/$1" \ + || die "could not download $release_url/$1" +} + +verify() { + expected="$(awk -v name="$1" '$2 == name || $2 == "*" name { print $1; exit }' SHA256SUMS)" + [ -n "$expected" ] || die "the release's SHA256SUMS lists no $1" + actual="$($sha256 "$1" | awk '{ print $1 }')" + [ "$actual" = "$expected" ] || die "$1 does not match its SHA-256 checksum; nothing was installed" +} + +main "$@" diff --git a/devcapsule-src/scripts/release-manifest.py b/devcapsule-src/scripts/release-manifest.py index 13dbdfc1..0dab0bad 100644 --- a/devcapsule-src/scripts/release-manifest.py +++ b/devcapsule-src/scripts/release-manifest.py @@ -9,6 +9,7 @@ import subprocess from zipfile import ZipFile import tomllib +from collections.abc import Sequence from pathlib import Path from devcapsule.build_info import read_pex_build_info @@ -16,7 +17,8 @@ from devcapsule.platforms import Platform -def manifest(pex: Path, tag: str, revision: str) -> dict[str, object]: +def manifest(pex: Path, tag: str, revision: str, others: Sequence[Path] = ()) -> dict[str, object]: + """The release record of ``pex`` and of ``others``, the other platforms' executables of its build.""" info = read_pex_build_info(pex) if (info.build_mnemonic, info.version, info.source_revision) != (tag, tag.removeprefix("v").replace("-rc", "rc"), revision): raise ValueError("Release PEX identity disagrees with the selected tag and revision") @@ -31,10 +33,21 @@ def manifest(pex: Path, tag: str, revision: str) -> dict[str, object]: "source-revision": revision, "version": info.version, "base-references": bases, - "artifacts": {pex.name: hashlib.sha256(pex.read_bytes()).hexdigest()}, + "artifacts": { + pex.name: hashlib.sha256(pex.read_bytes()).hexdigest(), + **{other.name: artifact_digest(other, tag, revision) for other in others}, + }, } +def artifact_digest(executable: Path, tag: str, revision: str) -> str: + """The SHA-256 of another platform's executable of the same release build.""" + info = read_pex_build_info(executable) + if (info.build_mnemonic, info.source_revision) != (tag, revision): + raise ValueError(f"{executable.name} identity disagrees with the selected tag and revision") + return hashlib.sha256(executable.read_bytes()).hexdigest() + + def frozen_inputs(pex: Path) -> dict: project = Path(__file__).resolve().parents[1] with ZipFile(pex) as archive: @@ -69,8 +82,10 @@ def main() -> None: parser.add_argument("--verify", action="store_true") parser.add_argument("--gate", type=Path, required=True) parser.add_argument("--candidate", type=Path) + parser.add_argument("--artifact", type=Path, action="append", default=[], + help="Another platform's executable of this build, recorded beside devcapsule.pex") arguments = parser.parse_args() - expected = manifest(Path("dist/devcapsule.pex"), arguments.tag, arguments.revision) + expected = manifest(Path("dist/devcapsule.pex"), arguments.tag, arguments.revision, arguments.artifact) expected["frozen-inputs"] = frozen_inputs(Path("dist/devcapsule.pex")) gate = json.loads(arguments.gate.read_text()) if gate["tag"] != arguments.tag or gate["source-revision"] != arguments.revision: diff --git a/devcapsule-src/tests/integration/test_install_script.py b/devcapsule-src/tests/integration/test_install_script.py new file mode 100644 index 00000000..d3d23283 --- /dev/null +++ b/devcapsule-src/tests/integration/test_install_script.py @@ -0,0 +1,135 @@ +"""Run the release's install script against a release the test writes, with no network. + +The release is a directory of small shell scripts standing in for the +executables, served to the script as a ``file://`` URL. ``uname`` and +``sysctl`` are stubs ahead of the real tools on ``PATH``, so each test chooses +the computer the script installs on, whatever runs the suite. +""" +from __future__ import annotations + +import hashlib +import os +from pathlib import Path +import subprocess + +import pytest + +from devcapsule.platforms import Platform +from devcapsule.runtime_artifact import DEFAULT_RUNTIME_DIRECTORY + +pytestmark = pytest.mark.integration + +INSTALL_SCRIPT = Path(__file__).resolve().parents[2] / "scripts" / "install.sh" +EXECUTABLES = ("devcapsule.pex", "devcapsule-linux-arm64", "devcapsule-macos-arm64") +"""The executables a release publishes and lists in its SHA256SUMS.""" + + +@pytest.fixture +def release(tmp_path: Path) -> Path: + """A release whose executables each print their own name, with a matching SHA256SUMS.""" + release = tmp_path / "release" + release.mkdir() + for name in EXECUTABLES: + (release / name).write_text(f'#!/bin/sh\necho "{name} $*"\n') + _write_checksums(release) + return release + + +def _write_checksums(release: Path) -> None: + lines = [f"{hashlib.sha256((release / name).read_bytes()).hexdigest()} {name}\n" for name in EXECUTABLES] + (release / "SHA256SUMS").write_text("".join(lines)) + + +def _install(tmp_path: Path, release: Path | None, system: str, machine: str, + apple_silicon: bool = False) -> tuple[subprocess.CompletedProcess[str], Path]: + """Run the install script as ``system``/``machine`` with an empty home; return the run and the home.""" + stubs = tmp_path / "stubs" + stubs.mkdir(exist_ok=True) + (stubs / "uname").write_text(f'#!/bin/sh\ncase "$1" in -s) echo {system};; -m) echo {machine};; esac\n') + (stubs / "sysctl").write_text(f"#!/bin/sh\necho {1 if apple_silicon else 0}\n") + for stub in stubs.iterdir(): + stub.chmod(0o755) + home = tmp_path / "home" + home.mkdir() + environment = {key: value for key, value in os.environ.items() + if key not in ("DEVCAPSULE_RELEASE_URL", "DEVCAPSULE_RUNTIME_PEX")} + environment.update(HOME=str(home), PATH=f"{stubs}{os.pathsep}{os.environ['PATH']}") + if release is not None: + environment["DEVCAPSULE_RELEASE_URL"] = release.as_uri() + run = subprocess.run(["sh", str(INSTALL_SCRIPT)], env=environment, capture_output=True, text=True, + check=False, timeout=60) + return run, home + + +def _installed_files(home: Path) -> set[str]: + return {str(path.relative_to(home)) for path in home.rglob("*") if path.is_file()} + + +@pytest.mark.parametrize("system,machine,executable", [ + ("Linux", "x86_64", "devcapsule.pex"), + ("Linux", "aarch64", "devcapsule-linux-arm64"), +]) +def test_a_linux_computer_gets_its_own_executable_and_nothing_else( + tmp_path: Path, release: Path, system: str, machine: str, executable: str, +) -> None: + """On Linux the script installs the executable for the machine as + ~/.local/bin/devcapsule, runs its version command, and installs no runtimes.""" + run, home = _install(tmp_path, release, system, machine) + + assert run.returncode == 0, run.stderr + assert _installed_files(home) == {".local/bin/devcapsule"} + assert (home / ".local/bin/devcapsule").read_text() == (release / executable).read_text() + assert f"{executable} version" in run.stdout + + +def test_an_apple_silicon_mac_gets_the_launcher_and_both_linux_runtimes_where_the_launcher_looks( + tmp_path: Path, release: Path, +) -> None: + """On an Apple Silicon Mac the script installs the macOS launcher and each Linux + executable as devcapsule- in the directory the launcher reads by default, + even from a shell under Rosetta that reports x86_64.""" + run, home = _install(tmp_path, release, "Darwin", "x86_64", apple_silicon=True) + + runtimes = home / Path(DEFAULT_RUNTIME_DIRECTORY).relative_to("~") + assert run.returncode == 0, run.stderr + assert (home / ".local/bin/devcapsule").read_text() == (release / "devcapsule-macos-arm64").read_text() + assert (runtimes / f"devcapsule-{Platform.LINUX_AMD64}").read_text() == (release / "devcapsule.pex").read_text() + assert (runtimes / f"devcapsule-{Platform.LINUX_ARM64}").read_text() == ( + release / "devcapsule-linux-arm64").read_text() + assert all(os.access(home / path, os.X_OK) for path in _installed_files(home)) + + +def test_a_download_that_does_not_match_its_checksum_installs_nothing(tmp_path: Path, release: Path) -> None: + """When one executable differs from the release's SHA256SUMS the script fails, + names the file, and installs nothing at all, not even the files already verified.""" + with (release / "devcapsule-linux-arm64").open("a") as tampered: + tampered.write("# changed\n") + + run, home = _install(tmp_path, release, "Darwin", "arm64", apple_silicon=True) + + assert run.returncode != 0 + assert "devcapsule-linux-arm64 does not match its SHA-256 checksum" in run.stderr + assert _installed_files(home) == set() + + +@pytest.mark.parametrize("system,machine", [("Darwin", "x86_64"), ("FreeBSD", "amd64")]) +def test_a_computer_without_an_executable_is_refused( + tmp_path: Path, release: Path, system: str, machine: str, +) -> None: + """An Intel Mac or an operating system with no executable is refused before any + download, and nothing is installed.""" + run, home = _install(tmp_path, release, system, machine) + + assert run.returncode != 0 + assert run.stderr.startswith("devcapsule install: ") + assert _installed_files(home) == set() + + +def test_the_unreleased_template_names_no_release(tmp_path: Path) -> None: + """The script as it is in the repository, before a release writes its URL in, + refuses to run rather than download from a placeholder.""" + run, home = _install(tmp_path, None, "Linux", "x86_64") + + assert run.returncode != 0 + assert "names no release" in run.stderr + assert _installed_files(home) == set() diff --git a/devcapsule-src/tests/unit/devcapsule/test_runtime_artifact.py b/devcapsule-src/tests/unit/devcapsule/test_runtime_artifact.py new file mode 100644 index 00000000..1246a352 --- /dev/null +++ b/devcapsule-src/tests/unit/devcapsule/test_runtime_artifact.py @@ -0,0 +1,109 @@ +"""Unit tests of ``devcapsule.runtime_artifact``: where a launcher finds the runtime it delivers. + +Every executable here is a PEX archive the test writes, behind the first bytes +of a native header, as a scie is. The launcher is a macOS executable, which runs +in no capsule, so each test chooses which Linux runtime it should deliver. +""" +from __future__ import annotations + +import json +from pathlib import Path +from zipfile import ZipFile + +import pytest + +from devcapsule.build_info import BuildInfo +from devcapsule.compat import CliError +from devcapsule.platforms import Platform +from devcapsule.runtime_artifact import DEFAULT_RUNTIME_DIRECTORY, RUNTIME_PEX_ENV, runtime_artifact + +REVISION = "a" * 40 +"""The source revision of the launcher and of every runtime the tests write.""" + +MACH_O = b"\xcf\xfa\xed\xfe" + bytes(16) +"""The header of a 64-bit Mach-O executable.""" + +ELF_AMD64 = b"\x7fELF\x02\x01\x01" + bytes(11) + (0x3E).to_bytes(2, "little") +"""The header of a 64-bit x86-64 ELF executable.""" + + +def _executable(path: Path, header: bytes) -> Path: + """A DevCapsule 0.1.0 PEX at ``REVISION`` behind ``header``, written at ``path``.""" + path.parent.mkdir(parents=True, exist_ok=True) + with ZipFile(path, "w") as archive: + archive.writestr(".deps/devcapsule-0.1.0-py3-none-any.whl/devcapsule/_build_info.json", json.dumps({ + "schema_version": 2, "version": "0.1.0", "build_mnemonic": "v0.1.0", + "source_repository": "https://github.com/example/devcapsule", "source_revision": REVISION, + "source_url": f"https://github.com/example/devcapsule/commit/{REVISION}", + })) + path.write_bytes(header + path.read_bytes()) + return path + + +@pytest.fixture +def home(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> Path: + """An empty home directory, and the running launcher's build is the executables' build.""" + home = tmp_path / "home" + home.mkdir() + monkeypatch.setenv("HOME", str(home)) + monkeypatch.delenv(RUNTIME_PEX_ENV, raising=False) + monkeypatch.delenv("PEX", raising=False) + monkeypatch.setattr("devcapsule.runtime_artifact.current_build_info", lambda: BuildInfo( + schema_version=2, version="0.1.0", source_repository="https://github.com/example/devcapsule", + source_revision=REVISION, source_url="unknown")) + return home + + +@pytest.fixture +def macos_launcher(home: Path, tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> Path: + """The running launcher is a packaged macOS executable.""" + launcher = _executable(tmp_path / "devcapsule-macos-arm64", MACH_O) + monkeypatch.setenv("SCIE", str(launcher)) + return launcher + + +def _installed(home: Path, platform: Platform) -> Path: + """A runtime for ``platform`` in the default directory under ``home``.""" + directory = home / Path(DEFAULT_RUNTIME_DIRECTORY).relative_to("~") + return _executable(directory / f"devcapsule-{platform}", ELF_AMD64) + + +def test_a_packaged_launcher_delivers_the_runtime_in_the_default_directory(home: Path, macos_launcher: Path) -> None: + """With the variable unset and a runtime installed in the default directory, a + linux-amd64 launch delivers that runtime.""" + installed = _installed(home, Platform.LINUX_AMD64) + + assert runtime_artifact(Platform.LINUX_AMD64) == installed.resolve() + + +def test_the_variable_wins_over_the_default_directory(home: Path, macos_launcher: Path, tmp_path: Path, + monkeypatch: pytest.MonkeyPatch) -> None: + """With a runtime in the default directory and another named by the variable, a + launch delivers the named one.""" + _installed(home, Platform.LINUX_AMD64) + named = _executable(tmp_path / "elsewhere" / "devcapsule-linux-amd64", ELF_AMD64) + monkeypatch.setenv(RUNTIME_PEX_ENV, str(named)) + + assert runtime_artifact(Platform.LINUX_AMD64) == named.resolve() + + +def test_without_a_runtime_the_refusal_names_the_default_directory(home: Path, macos_launcher: Path) -> None: + """With the variable unset and the default directory empty, a launch is refused + with a message naming both the variable and the default directory.""" + with pytest.raises(CliError, match=rf"{RUNTIME_PEX_ENV}.*{DEFAULT_RUNTIME_DIRECTORY} as devcapsule-linux-amd64"): + runtime_artifact(Platform.LINUX_AMD64) + + +def test_a_source_launcher_ignores_the_default_directory(home: Path, tmp_path: Path, + monkeypatch: pytest.MonkeyPatch) -> None: + """A launcher running from source, with a runtime in the default directory and the + variable unset, is refused and told to set the variable: only a packaged + launcher, which the install script put beside its runtimes, uses the directory.""" + _installed(home, Platform.LINUX_AMD64) + monkeypatch.delenv("SCIE", raising=False) + source_entry = tmp_path / "devcapsule-script" + source_entry.write_text("#!/usr/bin/env python3\n") + monkeypatch.setattr("sys.argv", [str(source_entry)]) + + with pytest.raises(CliError, match=RUNTIME_PEX_ENV): + runtime_artifact(Platform.LINUX_AMD64) diff --git a/docs/getting-started/install.md b/docs/getting-started/install.md index 31342016..6790aaa2 100644 --- a/docs/getting-started/install.md +++ b/docs/getting-started/install.md @@ -1,21 +1,21 @@ --- -description: Check prerequisites, download the DevCapsule executable for this release, verify its SHA-256 checksum, and install it under ~/.local/bin. +description: Check prerequisites, then install DevCapsule with one command that downloads the executable for your computer, verifies its SHA-256 checksum, and installs it under ~/.local/bin. weight: 1 -updated: 2026-11-03 +updated: 2026-11-04 --- # Install DevCapsule DevCapsule ships as a single executable for **Linux (`x86_64` / Intel-AMD -64-bit)**. It requires a web browser and a working Docker daemon on the same -machine. It does not run natively on macOS, Windows, or ARM. **On Windows, read -[Windows via WSL2](../platforms/windows-wsl2.md) first** and run every command -below inside your WSL2 Linux terminal. On an Apple Silicon Mac, read -[macOS](../platforms/macos.md) for the experimental launcher you build from -source; the steps below do not apply. +64-bit)**, with experimental executables for **Apple Silicon Macs** and **ARM +Linux (`aarch64`)**. It requires a web browser and a working Docker daemon on +the same machine. **On Windows, read [Windows via WSL2](../platforms/windows-wsl2.md) +first** and run every command below inside your WSL2 Linux terminal. **On a +Mac, read [macOS](../platforms/macos.md) first**: it runs against Docker +Desktop, and what differs from Linux is listed there. ## Check your computer -In a Linux terminal: +In a terminal: ```bash uname -sm @@ -23,19 +23,43 @@ docker info docker buildx version ``` -Expect `Linux x86_64`, Docker server details, and a Buildx version. If Docker -is missing or prints a connection or permission error, complete [Docker Engine -installation](https://docs.docker.com/engine/install/) first. Docker must work -for your ordinary user account—never run `devcapsule` with `sudo`. +Expect `Linux x86_64` (or `Darwin arm64` on a Mac, `Linux aarch64` on ARM +Linux), Docker server details, and a Buildx version. If Docker is missing or +prints a connection or permission error, complete [Docker Engine +installation](https://docs.docker.com/engine/install/) first, or Docker +Desktop on a Mac. Docker must work for your ordinary user account—never run +`devcapsule` with `sudo`. -You also need `curl` and `sha256sum`. Allow several gigabytes of free disk -space for the base image and IDE on your first launch; subsequent launches -reuse those cached layers. +You also need `curl`, and `sha256sum` or `shasum`. Allow several gigabytes of +free disk space for the base image and IDE on your first launch; subsequent +launches reuse those cached layers. -## Download, verify, install +## Install -Paste this block into your terminal to download the release executable, check -its SHA-256 digest, and install it to `~/.local/bin/devcapsule`: +Paste this into your terminal: + +```bash +curl -fsSL {{download_url}}/install.sh | sh +``` + +The script downloads the release's executable for your computer and the +release's `SHA256SUMS`, checks the executable against it, and installs it as +`~/.local/bin/devcapsule`. On a Mac it also installs the Linux executables your +capsules run, in `~/.local/lib/devcapsule`, where the launcher finds them. If a +checksum does not match, the script stops and installs nothing: run it again, +and never install an unverified binary. It ends by printing the installed +version. + +To read the script before it runs, download it first: + +```bash +curl -fsSLO {{download_url}}/install.sh +less install.sh +sh install.sh +``` + +On Linux `x86_64` you can also install by hand. This is the same download and +check the script makes: ```bash ( @@ -51,9 +75,6 @@ its SHA-256 digest, and install it to `~/.local/bin/devcapsule`: ) ``` -Expect `devcapsule.pex: OK`. If checksum verification fails, delete the -temporary file and retry—never install an unverified binary. - Check the installed version: ```bash diff --git a/docs/platforms/linux.md b/docs/platforms/linux.md index 989592b7..c391f172 100644 --- a/docs/platforms/linux.md +++ b/docs/platforms/linux.md @@ -1,7 +1,7 @@ --- description: What DevCapsule needs from a Linux computer, and which distributions and Docker setups are supported. weight: 1 -updated: 2026-10-30 +updated: 2026-11-04 --- # Linux @@ -17,7 +17,11 @@ DevCapsule {{tag}} ships as a single executable for **64-bit Intel/AMD Linux [Install](../getting-started/install.md) starts with three commands to check the architecture, Docker daemon, and Buildx. -ARM Linux (`aarch64` / `linux-arm64`) is not supported in {{tag}}. +ARM Linux (`aarch64` / `linux-arm64`) has an experimental executable in {{tag}}, +which the install command picks on an ARM computer. It has not been tried on an +ARM Linux host yet, and its capsules need an arm64 base you build yourself +until one is published, as [macOS](macos.md#run-a-project-natively-as-linux-arm64) +describes. DevCapsule is developed and tested on Ubuntu-family desktops using Docker Engine from [Docker's official repository](https://docs.docker.com/engine/install/). diff --git a/docs/platforms/macos.md b/docs/platforms/macos.md index c89837fd..fe6f21e7 100644 --- a/docs/platforms/macos.md +++ b/docs/platforms/macos.md @@ -1,16 +1,13 @@ --- -description: An experimental launcher you build from source runs on Apple Silicon Macs against Docker Desktop, with capsules emulated or native. +description: An experimental launcher runs on Apple Silicon Macs against Docker Desktop, with capsules emulated or native. weight: 3 updated: 2026-11-04 --- # macOS -DevCapsule {{tag}} ships no macOS executable. The release executable is for -64-bit Intel/AMD Linux and does not run on macOS. - -The launcher in the source tree runs natively on **Apple Silicon Macs** -(`darwin-arm64`) against **Docker Desktop**, built by you. This is -experimental and not a supported platform in {{tag}}. Intel Macs are untested. +DevCapsule {{tag}} ships an experimental launcher for **Apple Silicon Macs** +(`darwin-arm64`), which runs natively against **Docker Desktop**. It is not a +supported platform in {{tag}}. There is no executable for Intel Macs. A project runs as one of two capsule platforms: @@ -26,13 +23,12 @@ as `linux-amd64`. ## What differs from Linux -- **Two executables, or three.** On Linux the launcher copies itself into the - capsule. A macOS executable cannot run there, so you build the Linux runtime - for each capsule platform you use and put them in one directory that - `DEVCAPSULE_RUNTIME_PEX` names. Each launch delivers the one for its - project's platform and refuses one of another DevCapsule version. Rebuild - them whenever you rebuild the launcher: runtimes of the same version from - another commit are not told apart. +- **Three executables.** On Linux the launcher copies itself into the + capsule. A macOS executable cannot run there, so the launcher delivers the + Linux runtime for the project's platform from `~/.local/lib/devcapsule`, + where the install script puts one for each platform, or from the directory + `DEVCAPSULE_RUNTIME_PEX` names instead. A launch refuses a runtime of + another DevCapsule version, so install all three together. - **Emulation.** Under `linux-amd64`, the first launch of an IDE builds its image under emulation: about ten minutes for PyCharm on a 14-core Mac. Later launches reuse the image. The IDE runs slower than on a native host. @@ -52,11 +48,28 @@ as `linux-amd64`. default `/Users`, `/Volumes`, `/private`, `/tmp` and `/var/folders`. Files the capsule writes there belong to your user. -## Build and install +## Install You need Docker Desktop with several gigabytes free under **Settings → -Resources → Disk usage limit**, and about as much free on the Mac itself, plus -Git and Python 3.12. From a clean checkout of a published commit: +Resources → Disk usage limit**, and about as much free on the Mac itself. +Install with the command on the [install page](../getting-started/install.md): + +```bash +curl -fsSL {{download_url}}/install.sh | sh +``` + +It installs the launcher as `~/.local/bin/devcapsule` and the `linux-amd64` +and `linux-arm64` runtimes in `~/.local/lib/devcapsule`. If you set +`DEVCAPSULE_RUNTIME_PEX` for an earlier build, remove it from your shell +profile: it takes precedence over that directory. Add `$HOME/.local/bin` to +your `PATH`, then build the arm64 base below, or continue with [your first +session](../getting-started/first-session.md) and answer `linux-amd64` when +init asks for the platform. + +### Build from source + +To run a commit that is not released, you need Git and Python 3.12 as well. +From a clean checkout of a published commit: ```bash git clone https://github.com/ccozianu/devcapsule.git @@ -82,27 +95,25 @@ done This writes the macOS launcher and a Linux runtime for each capsule platform, all from the same commit. `--allow-unpublished-revision` skips only the check that the commit is a branch tip; the commit itself must be public, since a base -build installs the web console from it. Install them: +build installs the web console from it. Install them where the launcher looks: ```bash mkdir -p ~/.local/bin ~/.local/lib/devcapsule install -m 0755 dist/devcapsule-macos-arm64 ~/.local/bin/devcapsule install -m 0755 dist/devcapsule-linux-amd64 dist/devcapsule-linux-arm64 ~/.local/lib/devcapsule/ -export DEVCAPSULE_RUNTIME_PEX="$HOME/.local/lib/devcapsule" ~/.local/bin/devcapsule version ``` -Add the `export` line, and `$HOME/.local/bin` on your `PATH`, to your shell -profile. Then build the arm64 base below, or continue with -[your first session](../getting-started/first-session.md) and answer -`linux-amd64` when init asks for the platform. +Rebuild and reinstall all three together: the runtimes record no commit, so +one built from another commit of the same version is not told apart. ## Run a project natively as `linux-arm64` Build the arm64 base once, natively, with the launcher you installed and the -revision it was built from (`devcapsule version` shows it): +revision it was built from, which `devcapsule version` shows: ```bash +revision="$(devcapsule version | sed -n 's/^Source revision: //p')" devcapsule images build --type base --recipe ubuntu-24.04 --platform linux-arm64 \ --tag devcapsule-base-local:arm64 --source-revision "$revision" ``` diff --git a/engineering-docs/development/e2e-tests.md b/engineering-docs/development/e2e-tests.md index 80595fbe..565563a4 100644 --- a/engineering-docs/development/e2e-tests.md +++ b/engineering-docs/development/e2e-tests.md @@ -77,7 +77,7 @@ to installing `xprop` in every image. | `DEVCAPSULE_E2E_BUILD_NETWORK` | `-- --build-network` | The network mode of image builds | | `DEVCAPSULE_SMOKE_SCENARIO` | `-- --scenario` | Catalog ID or JSON path of a recorded IDE scenario to replay | | `DEVCAPSULE_SMOKE_PLATFORM` | `-- --platform` | The capsule platform the IDE smoke creates each project for, such as `linux-arm64` | -| `DEVCAPSULE_RUNTIME_PEX` | you, for a macOS launcher | The Linux runtime it delivers, or a directory of `devcapsule-` runtimes | +| `DEVCAPSULE_RUNTIME_PEX` | you, for a macOS launcher whose runtimes are not in `~/.local/lib/devcapsule` | The Linux runtime it delivers, or a directory of `devcapsule-` runtimes | | `PLAYWRIGHT_BROWSERS_PATH` | you, optionally | Where `ide-smoke -- --display` finds or installs Chromium | ## Evidence diff --git a/engineering-docs/wip/2026-11-04-linux-arm64/CURRENT-STATUS.md b/engineering-docs/wip/2026-11-04-linux-arm64/CURRENT-STATUS.md index 5c1e0a31..bf6c226f 100644 --- a/engineering-docs/wip/2026-11-04-linux-arm64/CURRENT-STATUS.md +++ b/engineering-docs/wip/2026-11-04-linux-arm64/CURRENT-STATUS.md @@ -4,12 +4,12 @@ Mnemonic: `linux-arm64` Start date: 2026-11-04 -State: active; slices 1 to 4 done 2026-11-04, six IDEs running natively; waits on publication and the owner +State: active; slices 1 to 4 merged in #338; the one-line install on `ws-linux-arm64/one-line-install` awaits its pull request -Branch association: `ws-linux-arm64/capsules`, forked from local `main` at b3f10b7d, with -`ws-macos-launcher/host-port` merged in as its foundation +Branch association: `ws-linux-arm64/one-line-install`, forked from `main` at bf7e5d66 after +`ws-linux-arm64/capsules` merged there in #338 -Integration target: `main`, after `macos-launcher`'s pull request +Integration target: `main` Delivery method: pull request, merge commit; the human opens and merges it @@ -33,7 +33,8 @@ In scope, by the human's answers of 2026-11-04: and otherwise as `linux-amd64` under emulation, as today; - a `linux-aarch64` runtime executable for arm64 capsules. -Out of scope: publishing images or executables; release automation. +Out of scope: publishing images; release automation, except the per-platform release +executables and the install script the human directed on 2026-11-04. ## Current State @@ -112,19 +113,37 @@ arm64 on arm"). `Platform.current()` is now the native platform, and init asks t elicitor before the identity questions: Enter, or a run without a terminal, takes it. A project with a lock the host runs is not asked, and a Linux host never is. +**2026-11-04, one-line install.** #338 merged. Reading the install page, the human asked +for one command instead of the nine-line block, working on a Mac too ("we need ot make it +actually work for mac too"), then directed it on a new branch from `main` with its own +pull request: the scope above widened to the release's executables. A release now builds +`devcapsule-linux-arm64` and `devcapsule-macos-arm64` on native runners beside +`devcapsule.pex`, records them in the manifest, and publishes `SHA256SUMS` and an +`install.sh` with its own URL written in. The script picks the executable for the computer, +checks everything against `SHA256SUMS` before installing anything, and on a Mac puts both +Linux runtimes in `~/.local/lib/devcapsule`, where a packaged launcher now looks when +`DEVCAPSULE_RUNTIME_PEX` is unset. Verified here: the script piped into `sh` installed this +Mac's local builds from a `file://` release and the launcher answered `version`; integration +tests run it as each platform behind a stubbed `uname`. The release workflow itself runs +only on a tag. + ## Next Resumable Task -Publish this workstream and `macos-launcher` once the SSH agent holds a key, and hand both -pull requests to the human, the macOS one first. The owner's rulings and the arm64 base's -publication follow. +Hand the one-line install's pull request to the human. The owner's rulings and the arm64 +base's publication follow. ## Open Threads -- The SSH agent on this Mac holds no identity, so the workstream cannot be published or - pushed; registration is local, as is `macos-launcher`'s. -- This branch builds on `ws-macos-launcher/host-port`, which is not yet on `main`. The - registration commit is forked from `main` as topic 7.5 requires, and the macOS branch is - merged after it; this pull request follows that one. +- The SSH agent on this Mac holds no identity, so the coordination branch cannot be + published; branches are pushed over HTTPS with the GitHub CLI's credentials. +- `main` fails its test-conventions check since #338: `tests/test_linux_arm64_matrix.py` + and `tests/test_project_platform_selection.py` are outside the unit mirror without a + heavier suite's marker, and eighteen of their tests lack docstrings. They are this + workstream's; bringing them to the convention is the next slice unless the human + routes it elsewhere. +- The first release built by the new workflow is the first proof of the `ubuntu-24.04-arm` + and `macos-15` builds; a rerun of the workflow for a release made before it would look + for executables that release does not have. - An arm64 base on `docker.io/mycodespaceai`, and its digest in the matrix, need the owner. The pin holds the digest a push of this Mac's exact image keeps; a rebuild must re-pin. - The libsoup 404 on amd64 goes to `maintenance` by intake mail once the coordination branch