diff --git a/.planning/STATE.md b/.planning/STATE.md index ae167ce..a241801 100644 --- a/.planning/STATE.md +++ b/.planning/STATE.md @@ -3,8 +3,8 @@ gsd_state_version: 1.0 milestone: v0.5 milestone_name: GitHub Operator Setup status: Ready for Review -last_updated: "2026-09-02T20:11:53.793Z" -last_activity: 2026-09-02 +last_updated: "2026-09-05T10:10:16.085Z" +last_activity: 2026-09-05 progress: total_phases: 1 completed_phases: 1 @@ -27,7 +27,7 @@ See: .planning/PROJECT.md (updated 2026-07-03) Phase: 19 of 19 complete Plan: 19.1 — Hardened GitHub Actions Setup Status: Ready for review in PR #9 -Last activity: 2026-09-02 — completed quick task 260902-tfw: fail docs deployment when Bunny configuration is absent +Last activity: 2026-09-05 - completed quick task 260905-fld: default platform installer and homepage tabs ## Blockers / Concerns @@ -90,6 +90,7 @@ Last activity: 2026-09-02 — completed quick task 260902-tfw: fail docs deploym | # | Description | Date | Commit | Directory | |---|-------------|------|--------|-----------| | 260902-tfw | Fail docs deployment when Bunny configuration is absent | 2026-09-02 | 2d1e697 | [260902-tfw-make-docs-deployment-fail-when-bunny-con](./quick/260902-tfw-make-docs-deployment-fail-when-bunny-con/) | +| 260905-fld | Default platform installer and homepage tabs; native install/reinstall proof | 2026-09-05 | c415386 | [260905-fld-homepage-platform-installer](./quick/260905-fld-homepage-platform-installer/) | ## Accumulated Context diff --git a/.planning/quick/260905-fld-homepage-platform-installer/260905-fld-PLAN.md b/.planning/quick/260905-fld-homepage-platform-installer/260905-fld-PLAN.md new file mode 100644 index 0000000..57ad49e --- /dev/null +++ b/.planning/quick/260905-fld-homepage-platform-installer/260905-fld-PLAN.md @@ -0,0 +1,29 @@ +--- +status: complete +--- + +# Make installing Loopwire the homepage default + +Tracking: https://github.com/sandwichfarm/loopwire/issues/34 + +## Intent and scope + +Replace the source-first homepage install card with an automatic installer and accessible platform tabs, preserving the existing visual design. Affects platform integration and website/docs only; no audio, desktop runtime, dependency, or release changes. + +## Plan + +1. Extend the canonical signed installer with distro-aware package selection, embedded release public key, explicit progress/error steps, safe repeated installs/upgrades, and portable fallback. Preserve existing flags and signed checksum/archive rejection checks. Keep its public copy synchronized. +2. Add Automatic (default), Arch, Debian/Ubuntu, Fedora, openSUSE, Nix/NixOS, portable Linux, and Source install tabs. Show real published commands, platform/version boundaries, keyboard navigation, selected-command copying, and honest fallback guidance. +3. Update installation docs, README, and unreleased notes. Open actionable GitHub issues for reducible multi-command platform installs, excluding source builds. Do not disguise multiple steps by joining them with shell separators. + +## Verification + +- Regression fixtures first: signed local installs, repeat installs/upgrades, platform/architecture selection, dry-run, missing tools, checksum/signature/download failure, and unsafe archive rejection. Stub package managers; never install packages on this workstation. +- Run the real published tarball through the installer into a temporary prefix, using the embedded key, and exercise installed commands. +- Build the combined website; browser-test tabs, keyboard focus, clipboard success/failure, no-JS fallback, desktop/mobile layout and overflow. Compare screenshots with the existing design and persist visual verdict. +- Run shell syntax/static checks, installer/release verification, docs checks, lint/typecheck, tests, full build/static-site verification, and the standard pnpm check gate. +- Review resulting diff and record evidence and known host/platform gaps in the quick-task summary and STATE.md. + +## Constraints + +Use current published assets and existing packages. No new dependencies, package repositories, host audio changes, or deployment. Native distro packages must match published targets. Non-Linux and unsupported architectures fail with an actionable diagnostic. Release signatures remain required by default. diff --git a/.planning/quick/260905-fld-homepage-platform-installer/260905-fld-SUMMARY.md b/.planning/quick/260905-fld-homepage-platform-installer/260905-fld-SUMMARY.md new file mode 100644 index 0000000..d795cb8 --- /dev/null +++ b/.planning/quick/260905-fld-homepage-platform-installer/260905-fld-SUMMARY.md @@ -0,0 +1,96 @@ +--- +status: complete +--- + +# Make verified installation the first homepage action + +Tracking: [#34](https://github.com/sandwichfarm/loopwire/issues/34) + +Implementation commit: `c415386` on `feature/34-homepage-platform-installer`. + +## Result + +The homepage defaults to `curl -fsSL https://loopwire.app/install.sh | bash`. Nine accessible tabs cover Automatic, +Arch, Ubuntu, Debian, Fedora, openSUSE, Nix/NixOS, portable Linux, and source checkout. Copying follows the selected +panel; keyboard navigation, focus order, mobile layout, clipboard errors, and no-JavaScript fallback are covered. +The obsolete pre-release/deployment notice is removed from the homepage and README. + +The canonical installer now selects supported native packages, an existing Arch helper, Nix, or a portable archive. +It embeds the existing release verification key, reports steps and exact commands, verifies signatures/checksums +before native/portable installation, and preserves earlier portable installations during upgrades. Portable +replacement stages files and rolls back failures; failed recovery retains backups and reports their paths. Explicit +method changes stop when an existing portable launcher could shadow the new package. Nix version/reference changes +that cannot be safely performed are rejected before profile mutation. + +Manual native commands retain seven explicit verification/install steps. Repository follow-ups document what can +reduce them: [APT #35](https://github.com/sandwichfarm/loopwire/issues/35), +[Fedora #36](https://github.com/sandwichfarm/loopwire/issues/36), and +[openSUSE #37](https://github.com/sandwichfarm/loopwire/issues/37). Source build instructions remain available and do +not require a simplification issue. One-time repository trust setup is explicitly separate in those follow-ups. + +## Changed files and simplifications + +- `apps/site/src/pages/index.astro`: shared tab renderer and native command formatter; removed source-first/gated copy. +- `scripts/install.sh`: existing canonical installer expanded with platform selection, embedded key, progress, upgrades and recovery. +- `apps/docs/docs/public/install.sh`: synchronized public copy; the combined build also copies the canonical installer. +- `scripts/test-install-platforms.sh`, `scripts/verify-install.sh`: isolated signed fixtures and failure/recovery/migration regression coverage. +- `scripts/e2e-site-install.mjs`, `package.json`: browser checks using the existing system Playwright convention, with no new dependency. +- `scripts/verify-static-site.mjs`, `scripts/verify-docs.sh`: enforce the current install experience instead of stale release-gating text. +- `README.md`, `apps/docs/docs/guide/install.md`, `apps/docs/docs/developer/e2e.md`, + `apps/docs/docs/release-notes/unreleased.md`: current commands, supported target limits, upgrade behavior, checks and release notes. +- This quick-task plan/summary and `.planning/STATE.md`: durable intent, evidence and completion record. + +No audio/backend/application-state code, package recipes, dependencies, lockfiles, release artifacts or deployment configuration changed. + +## Verification + +- Initial regression checks failed on the old default homepage command and unsupported installer flags before implementation. +- Signed installer/release fixtures pass, including platform/architecture selection, repeat installs, stale-file removal, + missing tools, download/signature/checksum failures, duplicate records, archive paths/links, package failures, + piped stdin, no-terminal behavior, Nix profile selection/conflicts and old portable-install migration. +- Review reproduced failed-rollback data loss and interruption windows. Added regressions now prove that recovery + backups survive failed restoration and signals immediately after library/command backups restore the prior copy. +- The real published x86_64 archive installed twice outside a source checkout using only the embedded verification + key; the installed background launcher, DSP provider, JACK provider and detector help commands all exited zero. +- The built `/install.sh` was fetched through a local HTTP server and piped into Bash, installed the latest signed + release into a temporary prefix, and ran the installed background launcher help successfully. +- The commands rendered in all four native tabs downloaded real published assets and the pinned public key; + signature and checksum verification passed for each exact package. +- Browser checks pass for all nine tabs, command syntax/docs parity, clipboard contents/errors, arrow/Home/End + navigation, focus order, no-JavaScript fallback, and 320/390/768/1440px layouts. Final visual verdict: 96/100. +- ShellCheck 0.11.0, Bash syntax, public-installer/key synchronization and whitespace checks pass. +- The actual Nix 2.28.6 expression parsed eight profile fixtures, including existing, unrelated, duplicate, tagged, + and query-reference entries. Current AUR metadata was inspected and declares both published architectures and + pinned release hashes; the real host dry-run selected the installed yay helper without changing packages. +- `pnpm check` passed all script, requirement, documentation, workflow, runtime, packaging, compiler/lint/typecheck, + test and build gates: 295 TypeScript tests, 22 Rust tests, and 11 GitHub-setup transport tests. Final installer + boundary/formatting updates were additionally checked with installer/release fixtures and ShellCheck; final docs + and markup formatting passed a fresh web build, static-site verification and browser suite. +- All four native targets passed with the exact final installer SHA-256 + `b6cb8e0a902459a320d702adc6fab5cf9ff251b8118e622d898ed77807bfe58f`. + Each verified the release signature twice, completed both installs, made no changes on the second run, and ran + `/usr/bin/loopwire --background --help` and `/usr/bin/loopwire-dsp-provider --help` successfully. + +| Disposable target | Installed package version | Repeat install | +| --- | --- | --- | +| Ubuntu 24.04 | `0.1.0-1ubuntu24.04` | No changes | +| Debian 13 | `0.1.0-1debian13` | No changes | +| Fedora 44 | `0.1.0-1.fc44` | No changes | +| openSUSE Tumbleweed | `0.1.0-1` | No changes | + +The minimal openSUSE image needed `gawk`. Ubuntu's final two-pass test disabled optional apt recommendations in the +container; a separate full-default installation also succeeded before a test-harness problem prevented its later +assertions. The final rerun used immutable per-target harnesses. All smoke containers were removed. + +## Verification limits + +Container native checks exercise package installation/reinstall and installed command help, not a graphical desktop +or live audio routing. AUR installation, a full Nix package build/profile mutation, and native ARM64 execution were +not performed; isolated fixtures cover those selection boundaries, and the Nix parser was exercised with real Nix. +No host package, audio, startup-service, GitHub release, AUR publication or website deployment was performed. + +## Review + +Independent review approved the repaired recovery logic and identified the old-portable-to-Nix shadowing edge case; +that case now has a passing regression and stops before changing the profile. No known unresolved installer defect +remains in the requested scope. diff --git a/README.md b/README.md index bb4b62f..7e58743 100644 --- a/README.md +++ b/README.md @@ -10,7 +10,18 @@ transactions. It keeps capability limits visible instead of pretending the host ## Install -Current contributor path: +Install or upgrade with the platform-detecting installer: + +```bash +curl -fsSL https://loopwire.app/install.sh | bash +``` + +The installer reports each step, verifies signed release checksums, and selects a matching native package, an +existing AUR helper, Nix, or a portable user install. It asks before package-manager changes. See the +[install guide](https://loopwire.app/docs/guide/install.html) for supported distro versions, requirements, +manual platform commands, upgrades, and a dry-run preview. + +Contributors can still build from a checkout: ```bash git clone https://github.com/sandwichfarm/loopwire @@ -19,14 +30,11 @@ pnpm install pnpm check ``` -The curl installer is release-gated until signed public artifacts and Bunny deployment exist. - -Version tags are handled by the protected GitHub Release workflow, which publishes portable tarballs, AppImages, -verified native packages, signed checksums, and a machine-readable asset inventory. No public release exists yet. +The public `v0.1.0` release includes portable tarballs, AppImages, native packages, and signed checksums. ## Basic usage -1. Launch the desktop shell with `pnpm --filter @loopwire/desktop dev`. +1. Launch `loopwire` (or `pnpm --filter @loopwire/desktop dev` from a source checkout). 2. Create a new virtual device in the sidebar. 3. Add sources, an output bus, and a monitor target from the `+` menus. 4. Drag routes between ports and let Loopwire preview or apply the selected backend safely. @@ -48,8 +56,7 @@ The default device starts as Pass-Thru -> Channels 1 & 2, so the first route is Loopwire `v0.1.0` is the first alpha. PipeWire is the first-class path; PulseAudio and JACK have explicit compatibility limits, and ALSA is detection-only. See the [support matrix](https://loopwire.app/docs/guide/support-matrix.html) before -relying on host apply. The curl installer remains release-gated until signed public artifacts are published and -smoke-tested. +relying on host apply. Native packages are direct downloads; APT, DNF/COPR, and OBS repositories are not yet published. ## Development diff --git a/apps/docs/docs/developer/e2e.md b/apps/docs/docs/developer/e2e.md index 3435078..d9006e7 100644 --- a/apps/docs/docs/developer/e2e.md +++ b/apps/docs/docs/developer/e2e.md @@ -76,3 +76,15 @@ The real-shell path only runs where all of these exist: The script checks each precondition and refuses to fake a result when one is missing. + +## Homepage installation tabs + +Run `pnpm build:web` followed by `pnpm e2e:site` to check the published-site output locally. This uses an existing +Playwright installation with Chromium, as the desktop UI harness does. Set `PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH` +if you need a system Chromium executable instead of a cached browser. The harness creates its own loopback server +on an available port and closes it after testing. + +Checks cover the automatic default, every platform tab, keyboard navigation/focus, clipboard success and failure, +mobile overflow, shell command syntax, agreement with the install guide, and the no-JavaScript fallback. It also +rejects the obsolete pre-release deployment notice. This browser check does not execute installation commands or +modify host packages/audio. Run `pnpm verify:install` for isolated signed-installer and package-manager fixtures. diff --git a/apps/docs/docs/guide/install.md b/apps/docs/docs/guide/install.md index 78ec68f..b58f93a 100644 --- a/apps/docs/docs/guide/install.md +++ b/apps/docs/docs/guide/install.md @@ -1,11 +1,73 @@ # Install -Loopwire 0.1.0 is published for early testers. Arch users can choose the stable source-built `loopwire` package or -the prebuilt `loopwire-bin` package; contributors can still work directly from a source checkout. +Install or upgrade Loopwire with one command: + +```bash +curl -fsSL https://loopwire.app/install.sh | bash +``` + +Loopwire `v0.1.0` is published for early testers. Run the installer as your regular user. It names each step, +prints the selected package-manager command before running it, and asks before package-manager changes. It does +not enable startup services or change audio routing. Read [the installer](https://loopwire.app/install.sh) before running it if you +want to inspect what it does. + +The release downloader needs Bash, curl, OpenSSL, and standard GNU tools including `awk`, `sha256sum`, and `tar`. +Minimal images may need these prerequisites installed first. Missing tools produce a named-step error before the +installer changes an existing installation. + +## Automatic platform selection + +| Platform | Default installation path | +| --- | --- | +| Ubuntu 24.04, x86_64 | Signed release deb through APT | +| Debian 13, x86_64 | Signed release deb through APT | +| Fedora 44, x86_64 | Signed release RPM through DNF | +| openSUSE Tumbleweed, x86_64 | Signed release RPM through Zypper | +| Arch Linux, x86_64 or ARM64 | `loopwire-bin` through an existing yay or paru; portable fallback without a helper | +| NixOS | Release-bound Nix package in your user profile | +| Other Linux or unmatched native target | Signed portable archive for x86_64 or ARM64 | + +Automatic preserves an existing portable installation when its launcher and support directory are present under +`~/.local`: it upgrades that copy in place so an old command on `PATH` cannot shadow a new system package. An explicit +switch to native/AUR/Nix stops with migration guidance while that portable copy exists; the installer does not delete it. +On NixOS, reconcile the old portable launcher before installing through Nix, since a generic portable binary is not +supported there. + +Native package selection is limited to the published distro versions. Portable fallback is not a claim that every +Linux distribution has compatible runtime libraries. Non-Linux systems and unsupported architectures are rejected. + +The VitePress public asset and `/install.sh` in the combined website are byte-for-byte copies of `scripts/install.sh`. +The default release downloader verifies `SHA256SUMS.sig` using the embedded release public key, then checks the selected +artifact checksum before installation. AUR and Nix use their existing package verification paths. No separate key +file or source checkout is needed. For a private/local release, pass `--public-key FILE`; `--skip-signature` is limited +to explicitly unsigned portable development installs. + +Preview the selected path without downloads or writes: + +```bash +curl -fsSL https://loopwire.app/install.sh | bash -s -- --dry-run +``` + +Run the same automatic command again to install the current release or upgrade an existing installation. Package +managers own their installed files; portable installs replace owned files and support data, including obsolete +files from earlier versions. Failed download or verification leaves the installed copy intact. Keep your old +version tag if you need to reinstall a previous portable release with `--version vX.Y.Z`. + +Use `--yes` only when you want unattended package-manager changes. It requires root or usable noninteractive sudo; +normal interactive installs read confirmation from the terminal even when the script is piped into Bash. The +installer never adds package repositories, installs AUR helpers, or edits shell configuration. ## Arch User Repository -Build the stable tagged source package: +With an existing yay helper: + +```bash +yay -S --needed loopwire-bin +``` + +With paru, replace `yay` with `paru`. Without a helper, Automatic uses a portable archive. The AUR stable source-built +`loopwire`, prebuilt `loopwire-bin`, and rolling `loopwire-git` variants conflict because they install the same commands; +install only one. To build the stable tagged source package manually: ```bash git clone https://aur.archlinux.org/loopwire.git @@ -13,31 +75,130 @@ cd loopwire makepkg -si ``` -For the faster prebuilt release-artifact package, use `loopwire-bin`. To follow the current default branch, use the -rolling `loopwire-git` package. The three variants conflict because they install the same commands; install only one. +## Native packages + +Automatic performs the download and verification steps for you. For manual installation, run the matching block +below together in an empty directory. Commands are connected with `&&` so failed downloads or checks stop the install. +These are direct `v0.1.0` downloads, not distro repositories. Use Automatic to select the latest available release. + +The RPM files have no embedded RPM signature. The commands authenticate the download using the signed SHA-256 +manifest first, then permit this local RPM for that install; repository dependency checks remain enabled. + +### Ubuntu 24.04 -## Source Install +x86_64 only. ```bash -git clone https://github.com/sandwichfarm/loopwire -cd loopwire -pnpm install -pnpm check +curl -fSLO https://github.com/sandwichfarm/loopwire/releases/download/v0.1.0/loopwire_0.1.0-1ubuntu24.04_amd64.deb && +curl -fSLO https://github.com/sandwichfarm/loopwire/releases/download/v0.1.0/SHA256SUMS && +curl -fSLO https://github.com/sandwichfarm/loopwire/releases/download/v0.1.0/SHA256SUMS.sig && +curl -fsSL https://raw.githubusercontent.com/sandwichfarm/loopwire/7e0c6b17a5b12efc9f62df9a314781ad9fbb20ec/packaging/release-signing-public.pem -o loopwire-release-key.pem && +openssl dgst -sha256 -verify loopwire-release-key.pem -signature SHA256SUMS.sig SHA256SUMS && +sha256sum --check --ignore-missing SHA256SUMS && +sudo apt install ./loopwire_0.1.0-1ubuntu24.04_amd64.deb ``` -## Signed Release Installer +[Repository work to shorten this setup](https://github.com/sandwichfarm/loopwire/issues/35) tracks signed metadata, +release publication, clean-guest install/upgrade verification, and updated instructions. -The public installer is deployed from `scripts/install.sh` and installs the signed `v0.1.0` release artifacts: +### Debian 13 + +x86_64 only. ```bash -curl -fsSL https://loopwire.app/install.sh | bash +curl -fSLO https://github.com/sandwichfarm/loopwire/releases/download/v0.1.0/loopwire_0.1.0-1debian13_amd64.deb && +curl -fSLO https://github.com/sandwichfarm/loopwire/releases/download/v0.1.0/SHA256SUMS && +curl -fSLO https://github.com/sandwichfarm/loopwire/releases/download/v0.1.0/SHA256SUMS.sig && +curl -fsSL https://raw.githubusercontent.com/sandwichfarm/loopwire/7e0c6b17a5b12efc9f62df9a314781ad9fbb20ec/packaging/release-signing-public.pem -o loopwire-release-key.pem && +openssl dgst -sha256 -verify loopwire-release-key.pem -signature SHA256SUMS.sig SHA256SUMS && +sha256sum --check --ignore-missing SHA256SUMS && +sudo apt install ./loopwire_0.1.0-1debian13_amd64.deb +``` + +[Repository work to shorten this setup](https://github.com/sandwichfarm/loopwire/issues/35) tracks signed metadata, +release publication, clean-guest install/upgrade verification, and updated instructions. + +### Fedora 44 + +x86_64 only. + +```bash +curl -fSLO https://github.com/sandwichfarm/loopwire/releases/download/v0.1.0/loopwire-0.1.0-1.fc44.x86_64.rpm && +curl -fSLO https://github.com/sandwichfarm/loopwire/releases/download/v0.1.0/SHA256SUMS && +curl -fSLO https://github.com/sandwichfarm/loopwire/releases/download/v0.1.0/SHA256SUMS.sig && +curl -fsSL https://raw.githubusercontent.com/sandwichfarm/loopwire/7e0c6b17a5b12efc9f62df9a314781ad9fbb20ec/packaging/release-signing-public.pem -o loopwire-release-key.pem && +openssl dgst -sha256 -verify loopwire-release-key.pem -signature SHA256SUMS.sig SHA256SUMS && +sha256sum --check --ignore-missing SHA256SUMS && +sudo dnf --setopt=localpkg_gpgcheck=0 install ./loopwire-0.1.0-1.fc44.x86_64.rpm +``` + +[Repository work to shorten this setup](https://github.com/sandwichfarm/loopwire/issues/36) tracks signed metadata, +release publication, clean-guest install/upgrade verification, and updated instructions. + +### openSUSE Tumbleweed + +x86_64 only. + +```bash +curl -fSLO https://github.com/sandwichfarm/loopwire/releases/download/v0.1.0/loopwire-0.1.0-1.x86_64.rpm && +curl -fSLO https://github.com/sandwichfarm/loopwire/releases/download/v0.1.0/SHA256SUMS && +curl -fSLO https://github.com/sandwichfarm/loopwire/releases/download/v0.1.0/SHA256SUMS.sig && +curl -fsSL https://raw.githubusercontent.com/sandwichfarm/loopwire/7e0c6b17a5b12efc9f62df9a314781ad9fbb20ec/packaging/release-signing-public.pem -o loopwire-release-key.pem && +openssl dgst -sha256 -verify loopwire-release-key.pem -signature SHA256SUMS.sig SHA256SUMS && +sha256sum --check --ignore-missing SHA256SUMS && +sudo zypper install --allow-unsigned-rpm ./loopwire-0.1.0-1.x86_64.rpm +``` + +[Repository work to shorten this setup](https://github.com/sandwichfarm/loopwire/issues/37) tracks signed metadata, +release publication, clean-guest install/upgrade verification, and updated instructions. + +## Nix / NixOS + +With Nix already installed, add the release-bound package to your user profile: + +```bash +nix --extra-experimental-features "nix-command flakes" profile install github:sandwichfarm/loopwire#loopwire-bin +``` + +This enables the required experimental features for this command only. Use Automatic for repeated installs and +upgrades; it detects an existing matching profile entry. On another Linux distribution with Nix installed, choose +Nix explicitly with `curl -fsSL https://loopwire.app/install.sh | bash -s -- --method nix`. +For declarative NixOS setups, add the package to your configuration rather than managing the same package twice. +The flake pins the release version: `--version` applies to native/portable downloads and is rejected for Nix. +If a matching package already uses a different pinned flake reference, the installer stops without changing your +profile; inspect `nix profile list` and intentionally reconcile that entry before switching references. + +## Portable Linux + +Choose the user-scoped archive on a compatible glibc desktop: + +```bash +curl -fsSL https://loopwire.app/install.sh | bash -s -- --method portable +``` + +Commands are installed under `~/.local/bin` and support files under `~/.local/lib/loopwire`. If the bin directory is +not on `PATH`, launch `~/.local/bin/loopwire`; the installer prints guidance without editing your shell files. +The GUI requires GTK 3 and WebKitGTK 4.1 runtime libraries. The portable path does not install missing system +libraries. Use the Nix path on NixOS instead of a generic Linux executable. + +Pass `--prefix DIR` to choose a different bin directory (support files go in its sibling `lib/loopwire`). A custom +prefix or release `--base-url` selects the portable path by default for compatibility with local release tests. +Reruns replace the owned commands and support files without duplicating them or changing your saved routing state. + +## Source install + +```bash +git clone https://github.com/sandwichfarm/loopwire +cd loopwire +pnpm install +pnpm check ``` -The VitePress public asset and live `/install.sh` are byte-for-byte copies of `scripts/install.sh`. The installer -requires the published `SHA256SUMS`, `SHA256SUMS.sig`, and release public key before extracting an artifact. +This contributor path needs Node.js 22.12+, pnpm 11.3+, and the development prerequisites documented in the +[developer guide](../developer/architecture.md). It installs workspace dependencies and verifies the project; +launch the development shell with `pnpm --filter @loopwire/desktop dev`. -The installer must detect OS and architecture, download a release artifact, verify signed checksums, and avoid -persistent system changes unless the user explicitly opts in. +## Installer verification Current installer verification: diff --git a/apps/docs/docs/public/install.sh b/apps/docs/docs/public/install.sh index 1593377..3518e50 100755 --- a/apps/docs/docs/public/install.sh +++ b/apps/docs/docs/public/install.sh @@ -1,269 +1,455 @@ #!/usr/bin/env bash -set -euo pipefail +set -Eeuo pipefail repo="${LOOPWIRE_REPO:-sandwichfarm/loopwire}" version="${LOOPWIRE_VERSION:-latest}" prefix="${PREFIX:-$HOME/.local/bin}" -dry_run="false" +portable_requested="${PREFIX:+true}" base_url_override="${LOOPWIRE_BASE_URL:-}" public_key_file="${LOOPWIRE_RELEASE_PUBLIC_KEY_FILE:-}" skip_signature="${LOOPWIRE_SKIP_SIGNATURE:-false}" +method=auto +method_explicit=false +dry_run=false +assume_yes=false +step=arguments +tmp_dir="" +bin_stage="" +lib_stage="" +lock_dir="" +committing=false +committed=false +changed_commands=() +lib_changed=false +commands=(loopwire loopwire-dsp-provider loopwire-jack-ports loopwire-detect-audio) usage() { cat <<'USAGE' -Install Loopwire from a GitHub release artifact. +Install or upgrade Loopwire for Linux. Usage: - install.sh [--repo owner/name] [--version vX.Y.Z|latest] [--base-url URL] [--prefix DIR] [--public-key FILE] [--skip-signature] [--dry-run] + install.sh [--method auto|portable|native|aur|nix] [--yes] [--dry-run] + [--repo owner/name] [--version vX.Y.Z|latest] [--base-url URL] + [--prefix DIR] [--public-key FILE] [--skip-signature] + +Auto selects matching native packages on Debian 13, Ubuntu 24.04, Fedora 44, +and openSUSE Tumbleweed (x86_64). Arch uses an existing yay/paru helper. +Existing ~/.local portable installations are upgraded in place instead. +NixOS uses the release-bound Nix flake. Other Linux targets use a signed +x86_64/aarch64 tarball; the portable runtime still needs distro GUI libraries. +For Nix, the flake owns the pinned release version; --version is not supported. +Use --method portable for a user-local installation without a package manager. +Explicit --prefix/PREFIX or --base-url defaults to portable unless --method is set. +Native/AUR installs show their command and use terminal package-manager prompts. +--yes accepts those prompts; without a terminal it is required for these methods. +--dry-run prints the plan without downloading or changing any files. Environment: - LOOPWIRE_REPO GitHub repository, default sandwichfarm/loopwire - LOOPWIRE_VERSION Release tag, default latest - LOOPWIRE_BASE_URL Override release asset base URL, useful for local file:// smoke tests + LOOPWIRE_REPO Repository, default sandwichfarm/loopwire + LOOPWIRE_VERSION Release tag, default latest + LOOPWIRE_BASE_URL Asset base URL override, including file:// fixtures LOOPWIRE_RELEASE_PUBLIC_KEY_FILE - Public key used to verify SHA256SUMS.sig + Override the embedded release verification key LOOPWIRE_SKIP_SIGNATURE - Set true only for explicit unsigned local development installs - PREFIX Install directory, default ~/.local/bin + true only for unsigned local development (portable only) + LOOPWIRE_OS_RELEASE_FILE + os-release fixture override, default /etc/os-release + PREFIX Portable command directory, default ~/.local/bin -The installer expects release assets named: - loopwire-linux-x86_64.tar.gz - loopwire-linux-aarch64.tar.gz - -It also expects SHA256SUMS and SHA256SUMS.sig in the release assets. +Release downloads require SHA256SUMS and SHA256SUMS.sig. Portable assets are +loopwire-linux-x86_64.tar.gz and loopwire-linux-aarch64.tar.gz. The GUI launcher can start without Node.js, but loopwire --background, loopwire-dsp-provider, loopwire-jack-ports, and loopwire-detect-audio require node on PATH. USAGE } -while [ "$#" -gt 0 ]; do - case "$1" in - --repo) - repo="${2:?missing value for --repo}" - shift 2 - ;; - --version) - version="${2:?missing value for --version}" - shift 2 - ;; - --base-url) - base_url_override="${2:?missing value for --base-url}" - shift 2 - ;; - --prefix) - prefix="${2:?missing value for --prefix}" - shift 2 - ;; - --public-key) - public_key_file="${2:?missing value for --public-key}" - shift 2 - ;; - --skip-signature) - skip_signature="true" - shift - ;; - --dry-run) - dry_run="true" - shift - ;; - -h | --help) - usage - exit 0 - ;; - *) - echo "Unknown argument: $1" >&2 - usage >&2 - exit 2 - ;; - esac -done +fail() { printf 'Loopwire installer failed during %s: %s\n' "$step" "$*" >&2; exit 1; } +progress() { step="$2"; printf '\n[%s/7] %s\n' "$1" "$step"; } +require_cmd() { command -v "$1" >/dev/null 2>&1 || fail "Required command not found: $1"; } +print_command() { printf 'Command:'; printf ' %q' "$@"; printf '\n'; } -require_cmd() { - if ! command -v "$1" >/dev/null 2>&1; then - echo "Required command not found: $1" >&2 - exit 1 - fi +detect_arch() { + case "$(uname -m)" in + x86_64 | amd64) printf '%s\n' x86_64 ;; + aarch64 | arm64) printf '%s\n' aarch64 ;; + *) fail "Unsupported architecture: $(uname -m). Available: x86_64, aarch64." ;; + esac } -report_background_dependency() { - if command -v node >/dev/null 2>&1; then - echo "Background restore dependency: node found at $(command -v node)" - return +cleanup() { + local status=$? command changed remove_command rollback_failed=false + trap - EXIT ERR + # A second interrupt must not abort recovery halfway through restoring backups. + trap '' INT TERM + if [ "$committing" = true ] && [ "$committed" != true ]; then + printf 'Restoring previous portable installation after failure.\n' >&2 + for command in "${commands[@]}"; do + # A signal can arrive after mv succeeds and before shell flags are updated. + # The backup on disk is authoritative evidence that restoration is needed. + if [ -e "$bin_stage/backup/$command" ] || [ -L "$bin_stage/backup/$command" ]; then + if ! rm -f -- "$prefix/$command" || ! mv -- "$bin_stage/backup/$command" "$prefix/$command"; then + rollback_failed=true + fi + else + remove_command=false + for changed in "${changed_commands[@]}"; do + [ "$command" != "$changed" ] || remove_command=true + done + if [ "$remove_command" = true ] && ! rm -f -- "$prefix/$command"; then rollback_failed=true; fi + fi + done + if [ -e "$lib_stage/backup" ] || [ -L "$lib_stage/backup" ]; then + if ! rm -rf -- "$lib_target" || ! mv -- "$lib_stage/backup" "$lib_target"; then + rollback_failed=true + fi + elif [ "$lib_changed" = true ] && ! rm -rf -- "$lib_target"; then + rollback_failed=true + fi fi - - echo "WARNING: Background restore requires node on PATH." >&2 - echo "Install nodejs before enabling Restore on boot or using bundled provider commands." >&2 -} - -validate_archive_members() { - archive="$1" - listing="$tmp_dir/archive-members.txt" - - tar -tzf "$archive" >"$listing" - if [ ! -s "$listing" ]; then - echo "Release artifact is empty: $(basename "$archive")" >&2 - exit 1 + if [ "$rollback_failed" = true ]; then + status=1 + printf 'Rollback incomplete. Recovery files are retained; do not rerun installation until restored.\n' >&2 + printf 'Command backups: %s/backup\nSupport backup: %s/backup\n' "$bin_stage" "$lib_stage" >&2 + printf 'Restore commands to %s and support files to %s, then remove the retained lock: %s\n' \ + "$prefix" "$lib_target" "$lock_dir" >&2 + else + if [ -n "$bin_stage" ] && ! rm -rf -- "$bin_stage"; then status=1; fi + if [ -n "$lib_stage" ] && ! rm -rf -- "$lib_stage"; then status=1; fi + if [ -n "$lock_dir" ] && ! rmdir -- "$lock_dir"; then status=1; fi fi - - while IFS= read -r entry; do - [ -n "$entry" ] || { - echo "Release artifact contains an empty path." >&2 - exit 1 - } - - case "$entry" in - /*) - echo "Release artifact contains an absolute path: $entry" >&2 - exit 1 - ;; - esac - - case "/$entry/" in - *"/../"*) - echo "Release artifact contains a parent path component: $entry" >&2 - exit 1 - ;; - esac - done <"$listing" + # Download cleanup is independent of recovery; its failure never removes backups. + if [ -n "$tmp_dir" ] && ! rm -rf -- "$tmp_dir"; then + printf 'Could not remove temporary downloads: %s\n' "$tmp_dir" >&2 + status=1 + fi + exit "$status" } +trap cleanup EXIT +trap 'printf "Loopwire installer failed during %s (exit %s).\n" "$step" "$?" >&2' ERR +trap 'exit 130' INT +trap 'exit 143' TERM -detect_arch() { - case "$(uname -m)" in - x86_64 | amd64) - printf '%s\n' "x86_64" - ;; - aarch64 | arm64) - printf '%s\n' "aarch64" - ;; - *) - echo "Unsupported architecture: $(uname -m)" >&2 - exit 1 - ;; +while [ "$#" -gt 0 ]; do + case "$1" in + --repo) repo="${2:?missing value for --repo}"; shift 2 ;; + --version) version="${2:?missing value for --version}"; shift 2 ;; + --prefix) prefix="${2:?missing value for --prefix}"; portable_requested=true; shift 2 ;; + --base-url) base_url_override="${2:?missing value for --base-url}"; shift 2 ;; + --public-key) public_key_file="${2:?missing value for --public-key}"; shift 2 ;; + --method) method="${2:?missing value for --method}"; method_explicit=true; shift 2 ;; + --skip-signature) skip_signature=true; shift ;; + --yes) assume_yes=true; shift ;; + --dry-run) dry_run=true; shift ;; + -h | --help) usage; exit 0 ;; + *) fail "Unknown argument: $1 (use --help)" ;; esac -} - -if [ "$(uname -s)" != "Linux" ]; then - echo "Loopwire installer currently supports Linux only." >&2 - exit 1 -fi - -require_cmd curl -require_cmd tar -require_cmd sha256sum -require_cmd install -require_cmd cp +done +case "$method" in auto | portable | native | aur | nix) ;; *) fail "Unknown method: $method" ;; esac +case "$skip_signature" in true | false) ;; *) fail 'LOOPWIRE_SKIP_SIGNATURE must be true or false' ;; esac +progress 1 'Detecting Linux platform and architecture' +[ "$(uname -s)" = Linux ] || fail 'Linux only: Loopwire does not provide macOS or Windows builds.' arch="$(detect_arch)" -asset="loopwire-linux-${arch}.tar.gz" - -if [ -n "$base_url_override" ]; then - base_url="${base_url_override%/}" -elif [ "$version" = "latest" ]; then - base_url="https://github.com/${repo}/releases/latest/download" -else - base_url="https://github.com/${repo}/releases/download/${version}" +# Read only data fields. Do not execute os-release as shell code. +os_id=unknown +os_version="" +os_release="${LOOPWIRE_OS_RELEASE_FILE:-/etc/os-release}" +if [ -r "$os_release" ]; then + while IFS='=' read -r key value; do + value="${value%\"}"; value="${value#\"}" + value="${value%\'}"; value="${value#\'}" + case "$key" in ID) os_id="$value" ;; VERSION_ID) os_version="$value" ;; esac + done <"$os_release" fi - -echo "Loopwire release source: ${base_url}/${asset}" -echo "Install prefix: ${prefix}" -if [ "$skip_signature" = "true" ]; then - echo "Signature verification: skipped by explicit request" -else - echo "Signature verification: required" +printf 'Platform: %s %s (%s)\n' "$os_id" "$os_version" "$arch" + +progress 2 'Selecting an installation method' +default_portable_prefix="$HOME/.local/bin" +existing_portable=false +if [ -f "$default_portable_prefix/loopwire" ] && [ -x "$default_portable_prefix/loopwire" ] && + [ -d "$HOME/.local/lib/loopwire" ]; then + existing_portable=true fi - -if [ "$dry_run" = "true" ]; then - echo "Dry run complete. No files changed." - exit 0 +native_target="" +manager="" +if [ "$arch" = x86_64 ]; then + case "$os_id:$os_version" in + debian:13) native_target=debian13; manager=apt-get ;; + ubuntu:24.04) native_target=ubuntu24.04; manager=apt-get ;; + fedora:44) native_target=fc44; manager=dnf ;; + opensuse-tumbleweed:*) native_target=opensuse; manager=zypper ;; + esac fi - -if [ -z "$public_key_file" ] && [ -f "packaging/release-signing-public.pem" ]; then - public_key_file="packaging/release-signing-public.pem" +if [ "$method_explicit" = false ] && { [ "$portable_requested" = true ] || [ -n "$base_url_override" ]; }; then + method=portable fi - -if [ "$skip_signature" != "true" ]; then - require_cmd openssl - if [ -z "$public_key_file" ]; then - echo "Signed release verification requires --public-key or LOOPWIRE_RELEASE_PUBLIC_KEY_FILE." >&2 - echo "Use --skip-signature only for explicit unsigned local development installs." >&2 - exit 1 - fi - if [ ! -f "$public_key_file" ]; then - echo "Release public key does not exist: $public_key_file" >&2 - exit 1 +if [ "$method" = auto ]; then + if [ "$os_id" = nixos ]; then + method=nix + elif [ "$existing_portable" = true ] && [ "$prefix" = "$default_portable_prefix" ]; then + method=portable + printf 'Upgrading existing portable installation at %s; keeping the current installation method.\n' "$default_portable_prefix" + elif [ "$os_id" = arch ] && [ "$version" = latest ] && [ "$repo" = sandwichfarm/loopwire ] && + { command -v yay >/dev/null 2>&1 || command -v paru >/dev/null 2>&1; }; then + method=aur + elif [ -n "$native_target" ] && command -v "$manager" >/dev/null 2>&1; then + method=native + else + method=portable + printf 'No matching native package/helper for this platform; using portable release.\n' fi - public_key_file="$(cd "$(dirname "$public_key_file")" && pwd -P)/$(basename "$public_key_file")" fi - -tmp_dir="$(mktemp -d)" -cleanup() { - rm -rf "$tmp_dir" -} -trap cleanup EXIT - -curl -fsSL "${base_url}/SHA256SUMS" -o "$tmp_dir/SHA256SUMS" -if [ "$skip_signature" != "true" ]; then - curl -fsSL "${base_url}/SHA256SUMS.sig" -o "$tmp_dir/SHA256SUMS.sig" +if [ "$os_id" = nixos ] && [ "$method" != nix ]; then + fail 'NixOS requires --method nix; generic Linux binaries need Nix runtime wrapping.' fi -curl -fsSL "${base_url}/${asset}" -o "$tmp_dir/${asset}" - -( - cd "$tmp_dir" - if [ "$skip_signature" != "true" ]; then - openssl dgst -sha256 -verify "$public_key_file" -signature SHA256SUMS.sig SHA256SUMS >/dev/null - fi - awk -v asset="$asset" '$2 == asset { found = 1 } END { exit found ? 0 : 1 }' SHA256SUMS || { - echo "SHA256SUMS does not contain ${asset}." >&2 - exit 1 - } - sha256sum --check --ignore-missing SHA256SUMS - validate_archive_members "$asset" - tar -xzf "$asset" -) - -binary_path="$(find "$tmp_dir" -type f -name loopwire -perm -111 | head -n 1)" -provider_path="$(find "$tmp_dir" -type f -name loopwire-dsp-provider -perm -111 | head -n 1)" -jack_provider_path="$(find "$tmp_dir" -type f -name loopwire-jack-ports -perm -111 | head -n 1)" -detector_path="$(find "$tmp_dir" -type f -name loopwire-detect-audio -perm -111 | head -n 1)" - -if [ -z "$binary_path" ]; then - echo "Release artifact did not contain an executable named loopwire." >&2 - exit 1 +if [ "$skip_signature" = true ] && [ "$method" != portable ]; then + fail '--skip-signature is restricted to --method portable local development installs.' fi - -mkdir -p "$prefix" -install -m 0755 "$binary_path" "$prefix/loopwire" -if [ -n "$provider_path" ]; then - install -m 0755 "$provider_path" "$prefix/loopwire-dsp-provider" +printf 'Selected method: %s\n' "$method" +if [ "$portable_requested" = true ] && [ "$method" != portable ]; then + fail '--prefix/PREFIX applies only to --method portable; package managers own their install paths.' fi -if [ -n "$jack_provider_path" ]; then - install -m 0755 "$jack_provider_path" "$prefix/loopwire-jack-ports" +if [ "$existing_portable" = true ] && [ "$method" = nix ]; then + fail "A portable Loopwire installation exists at $default_portable_prefix and could hide the Nix profile version on PATH." \ + 'Migrate the existing portable installation explicitly before using the Nix method;' \ + 'existing files and the Nix profile are unchanged.' fi -if [ -n "$detector_path" ]; then - install -m 0755 "$detector_path" "$prefix/loopwire-detect-audio" +if [ "$existing_portable" = true ] && { [ "$method" = native ] || [ "$method" = aur ]; }; then + fail "A portable Loopwire installation exists at $default_portable_prefix and could hide the package version on PATH." \ + 'Use --method portable to upgrade it, or migrate that installation explicitly before switching package methods.' fi -libexec_source="$tmp_dir/libexec/loopwire" -if [ -d "$libexec_source" ]; then - libexec_target="$(dirname "$prefix")/lib/loopwire" - mkdir -p "$libexec_target" - cp -R "$libexec_source/." "$libexec_target/" - find "$libexec_target" -type d -exec chmod 0755 {} + - find "$libexec_target" -type f -exec chmod 0644 {} + - if [ -f "$libexec_target/loopwire-gui" ]; then - chmod 0755 "$libexec_target/loopwire-gui" +run_package_command() { + print_command "$@" + [ "$dry_run" = false ] || return 0 + # bash may itself be reading a curl pipe. Package managers must not consume it. + if [ "$assume_yes" = true ]; then + "$@" /dev/null; then + "$@" /dev/null 2>&1; then manager=yay + elif command -v paru >/dev/null 2>&1; then manager=paru + else fail 'Install yay/paru yourself, or select --method portable.'; fi + args=("$manager" -S --needed) + [ "$assume_yes" = false ] || args+=(--noconfirm) + args+=(loopwire-bin) + progress 3 'Using AUR package verification and dependency resolution' + printf 'The installed helper builds loopwire-bin and checks its pinned release hashes.\n' + progress 6 'Installing or upgrading the AUR package' + run_package_command "${args[@]}" +elif [ "$method" = nix ]; then + require_cmd nix + [ -z "$base_url_override" ] && [ "$portable_requested" != true ] || + fail 'Nix uses your Nix profile; --prefix and --base-url apply only to portable installs.' + [ "$version" = latest ] || + fail 'Nix uses the release version pinned by the repository flake; --version is not supported for Nix. Use --method nix without --version.' + flake="github:$repo" + nix_cmd=(nix --extra-experimental-features 'nix-command flakes') + progress 3 'Inspecting the Nix profile for the release-bound flake' + printf 'Nix flake: %s#loopwire-bin (uses the release version and hashes pinned by the flake).\n' "$flake" + if [ "$dry_run" = true ]; then + printf 'Will inspect the current profile, install if absent, or upgrade only the matching Loopwire entry.\n' + print_command "${nix_cmd[@]}" profile install "$flake#loopwire-bin" + else + tmp_dir="$(mktemp -d)" + "${nix_cmd[@]}" profile list --json >"$tmp_dir/profile.json" + # Nix parses its own structured output, without a jq/Node/Python prerequisite. + # shellcheck disable=SC2016 # ${name} is Nix interpolation, not shell expansion. + nix_entry="$(LOOPWIRE_NIX_PROFILE_JSON="$tmp_dir/profile.json" LOOPWIRE_NIX_FLAKE="$flake" \ + "${nix_cmd[@]}" eval --impure --raw --expr ' + let + profile = builtins.fromJSON (builtins.readFile (builtins.getEnv "LOOPWIRE_NIX_PROFILE_JSON")); + elements = profile.elements or {}; + flake = builtins.getEnv "LOOPWIRE_NIX_FLAKE"; + hasPrefix = prefix: value: builtins.substring 0 (builtins.stringLength prefix) value == prefix; + isLoopwire = e: builtins.match "packages\\..*\\.loopwire-bin" (e.attrPath or "") != null; + matches = name: let e = elements.${name}; in + (e.originalUrl or "") == flake && isLoopwire e; + differentReference = name: let e = elements.${name}; ref = e.originalUrl or ""; in + isLoopwire e && (hasPrefix (flake + "/") ref || hasPrefix (flake + "?") ref); + conflicts = builtins.filter differentReference (builtins.attrNames elements); + in if !builtins.isAttrs elements then + throw "Loopwire requires a Nix profile with named entries; upgrade Nix before using this installer." + else if conflicts != [] then "conflict:" + builtins.concatStringsSep ", " conflicts + else builtins.concatStringsSep "\n" (builtins.filter matches (builtins.attrNames elements)) + ')" + case "$nix_entry" in + conflict:*) + fail "Loopwire is already installed from another flake reference (${nix_entry#conflict:})." \ + 'Inspect nix profile list and migrate that entry explicitly before retrying; the existing profile is unchanged.' + ;; + esac + [[ "$nix_entry" != *$'\n'* ]] || fail 'Multiple matching Loopwire profile entries; inspect nix profile list before retrying.' + progress 6 'Installing or upgrading Loopwire in the Nix profile' + if [ -n "$nix_entry" ]; then args=("${nix_cmd[@]}" profile upgrade "$nix_entry") + else args=("${nix_cmd[@]}" profile install "$flake#loopwire-bin"); fi + print_command "${args[@]}" + "${args[@]}" "$public_key_file" <<'PUBLIC_KEY' +-----BEGIN PUBLIC KEY----- +MIIBojANBgkqhkiG9w0BAQEFAAOCAY8AMIIBigKCAYEAzd9A1ugDjETYPd5LnRGM +GHLLd/1UVllNlqSJIhAgg1iZopVFSRTtFeJQGLKQ/J6qvAE7rQQ/vHm7Q/fQCsQr +2USDXom9LBy6HPF1APzZNWLlwmt3555VAqtbi62sRm1bbZSO7gtKQx7vb06TF/CL ++IQjIcP60vmz3Vx1b+qN1qaMeOsXnquAQiiqRce5EA4Ds5Xn/5bk7nbvig//3KHQ +Vi0+BNVfUIzxsgNoxzSZyOt2MG1npfpjLL3Es4f00hPuJrAKMQWOaY3ex92WXxse +7tlfa6krmScafE21fCFxmhj8TTdx+SJjKCiGg8R9YvsPfE8faY+mGWRNvI5O2K26 +fexaV20aRLE/druxGOQSZpNpr7m79LCP6+9JKgWuKCUyicNnrl5VGuEss3vR0wXJ +2ocq/7jCjmMD8Ucm+ejqp3EnXCKFptFh8YFAgPVcF6gTPWl6nylHGdr6nuQQATbh +IxTm9Q9BIciww9Jx1998UpygckxKmMICsypbwhv7zENbAgMBAAE= +-----END PUBLIC KEY----- +PUBLIC_KEY + fi + [ -f "$public_key_file" ] || fail "Release public key does not exist: $public_key_file" + fi + download SHA256SUMS + if [ "$skip_signature" != true ]; then + download SHA256SUMS.sig + openssl dgst -sha256 -verify "$public_key_file" -signature "$tmp_dir/SHA256SUMS.sig" \ + "$tmp_dir/SHA256SUMS" >/dev/null || fail 'Release signature verification failed.' + printf 'Signature verified.\n' + else printf 'WARNING: Signature verification skipped by explicit request.\n' >&2; fi + if [ "$method" = native ]; then + case "$native_target" in + debian13) pattern='^loopwire_[0-9][A-Za-z0-9.+~-]*-1debian13_amd64[.]deb$' ;; + ubuntu24.04) pattern='^loopwire_[0-9][A-Za-z0-9.+~-]*-1ubuntu24[.]04_amd64[.]deb$' ;; + fc44) pattern='^loopwire-[0-9][A-Za-z0-9.+~_-]*-1[.]fc44[.]x86_64[.]rpm$' ;; + opensuse) pattern='^loopwire-[0-9][A-Za-z0-9.+~_-]*-1[.]x86_64[.]rpm$' ;; + esac + asset="$(awk -v pattern="$pattern" '$2 ~ pattern { print $2 }' "$tmp_dir/SHA256SUMS")" + [ -n "$asset" ] && [[ "$asset" != *$'\n'* ]] || + fail 'Signed manifest must contain exactly one matching native package; use --method portable if unavailable.' + fi + # Check only the selected artifact, rejecting absent/duplicate/malformed records. + awk -v asset="$asset" '$2 == asset { n++; if (NF != 2 || length($1) != 64 || $1 ~ /[^0-9a-fA-F]/) bad=1; print } END { exit (n != 1 || bad) }' \ + "$tmp_dir/SHA256SUMS" >"$tmp_dir/selected.sha256" || fail "SHA256SUMS must contain one valid checksum for $asset." + progress 4 'Downloading the selected release artifact' + download "$asset" + progress 5 'Verifying the artifact checksum' + (cd "$tmp_dir" && sha256sum --check selected.sha256) || fail "Checksum verification failed: $asset" + if [ "$method" = native ]; then + privilege=() + if [ "$(id -u)" != 0 ]; then + require_cmd sudo + privilege=(sudo) + [ "$assume_yes" = false ] || privilege+=(-n) + fi + case "$manager" in + apt-get) args=(apt-get install); [ "$assume_yes" = false ] || args+=(-y) ;; + dnf) args=(dnf install); [ "$assume_yes" = false ] || args+=(-y); args+=(--setopt=localpkg_gpgcheck=0) ;; + zypper) args=(zypper); [ "$assume_yes" = false ] || args+=(--non-interactive); args+=(install --allow-unsigned-rpm) ;; + esac + args+=("$tmp_dir/$asset") + progress 6 'Installing or upgrading the verified native package' + printf 'Package manager handles dependencies and repeat installs; no repositories or services are added.\n' + if [ "$manager" != apt-get ]; then + printf 'RPM payloads use the verified release signature and SHA256 checksum instead of an embedded RPM signature.\n' + fi + run_package_command "${privilege[@]}" "${args[@]}" + else + for tool in tar install cp find mv chmod; do require_cmd "$tool"; done + printf 'Checking archive paths and entry types before extraction.\n' + tar -tzf "$tmp_dir/$asset" >"$tmp_dir/members" + [ -s "$tmp_dir/members" ] || fail "Release artifact is empty: $asset" + while IFS= read -r entry; do + case "$entry" in /*) fail "Release artifact contains an absolute path: $entry" ;; esac + case "/$entry/" in *'/../'*) fail "Release artifact contains a parent path component: $entry" ;; esac + case "$entry" in *\\*) fail 'Release artifact contains an escaped or backslash path.' ;; esac + done <"$tmp_dir/members" + tar -tvzf "$tmp_dir/$asset" >"$tmp_dir/types" + if awk 'substr($0,1,1) != "-" && substr($0,1,1) != "d" { bad=1 } END { exit !bad }' "$tmp_dir/types"; then + fail 'Release artifact contains a link or special file; only regular files/directories are allowed.' + fi + mkdir "$tmp_dir/payload" + tar -xzf "$tmp_dir/$asset" --no-same-owner --no-same-permissions -C "$tmp_dir/payload" + [ -f "$tmp_dir/payload/loopwire" ] && [ -x "$tmp_dir/payload/loopwire" ] || + fail 'Release artifact did not contain an executable named loopwire at its root.' + progress 6 'Staging and replacing the portable installation' + mkdir -p -- "$prefix" + prefix="$(cd "$prefix" && pwd -P)" + candidate_lock="$prefix/.loopwire-install.lock" + mkdir "$candidate_lock" 2>/dev/null || fail "Another install may be running; inspect $candidate_lock before removing a stale lock." + lock_dir="$candidate_lock" + lib_target="$(dirname "$prefix")/lib/loopwire" + mkdir -p -- "$(dirname "$lib_target")" + bin_stage="$(mktemp -d "$prefix/.loopwire-stage.XXXXXXXX")" + lib_stage="$(mktemp -d "$(dirname "$lib_target")/.loopwire-stage.XXXXXXXX")" + mkdir "$bin_stage/backup" + for command in "${commands[@]}"; do + if [ -f "$tmp_dir/payload/$command" ]; then + [ -x "$tmp_dir/payload/$command" ] || fail "Bundled command is not executable: $command" + install -m 0755 "$tmp_dir/payload/$command" "$bin_stage/$command" + fi + [ ! -d "$prefix/$command" ] || fail "Refusing to replace a directory at $prefix/$command" + done + if [ -d "$tmp_dir/payload/libexec/loopwire" ]; then + cp -R "$tmp_dir/payload/libexec/loopwire" "$lib_stage/new" + find "$lib_stage/new" -type d -exec chmod 0755 {} + + find "$lib_stage/new" -type f -exec chmod 0644 {} + + [ ! -f "$lib_stage/new/loopwire-gui" ] || chmod 0755 "$lib_stage/new/loopwire-gui" + fi + committing=true + if [ -e "$lib_target" ] || [ -L "$lib_target" ]; then mv -- "$lib_target" "$lib_stage/backup"; fi + lib_changed=true + [ ! -d "$lib_stage/new" ] || mv -- "$lib_stage/new" "$lib_target" + for command in "${commands[@]}"; do + if [ -e "$prefix/$command" ] || [ -L "$prefix/$command" ]; then mv -- "$prefix/$command" "$bin_stage/backup/$command"; fi + changed_commands+=("$command") + [ ! -f "$bin_stage/$command" ] || mv -- "$bin_stage/$command" "$prefix/$command" + done + committed=true + printf 'Loopwire installed to %s/loopwire\n' "$prefix" + printf 'Obsolete Loopwire commands/support files were replaced; unrelated files are preserved.\n' + case ":$PATH:" in *":$prefix:"*) ;; *) printf 'Add %s to PATH to run loopwire by name.\n' "$prefix" ;; esac + if command -v node >/dev/null 2>&1; then + printf 'Background restore dependency: node found at %s\n' "$(command -v node)" + else + printf '%s\n' 'WARNING: Background restore requires node on PATH.' \ + 'Install nodejs before enabling Restore on boot or using bundled provider commands.' >&2 + fi + fi + fi fi -report_background_dependency +if [ "$dry_run" = true ]; then progress 7 'Dry run complete. No files changed.' +else progress 7 'Installation complete. Run loopwire to launch.'; fi diff --git a/apps/docs/docs/release-notes/unreleased.md b/apps/docs/docs/release-notes/unreleased.md index 7f37bd0..3f2bb24 100644 --- a/apps/docs/docs/release-notes/unreleased.md +++ b/apps/docs/docs/release-notes/unreleased.md @@ -7,6 +7,17 @@ These notes describe source-tree progress. They are not a public release announc - The signed installer is now live at `https://loopwire.app/install.sh`; AppImage, deb, and RPM artifacts are available from the `v0.1.0` GitHub Release, with native files documented as direct downloads rather than distro repositories. +## Installation + +- The homepage defaults to a one-command installer with accessible platform tabs, selected-command copying, and + a separate source-build option. The obsolete pre-release gating notice has been removed. +- The signed installer detects supported distributions and architectures, reports each operation, embeds the + release verification key, and handles repeat installs and upgrades. Portable installs stage and verify files before + replacing existing files; native packages use the distro package manager. Automatic preserves earlier portable + installations, and incomplete rollback retains recovery backups with explicit restoration paths. +- Multi-step manual package instructions link to repository work for [APT](https://github.com/sandwichfarm/loopwire/issues/35), + [Fedora](https://github.com/sandwichfarm/loopwire/issues/36), and [openSUSE](https://github.com/sandwichfarm/loopwire/issues/37). + ## Packaging - The AUR now keeps two honest stable recipes: `loopwire` compiles the immutable tagged source archive, while diff --git a/apps/site/src/pages/index.astro b/apps/site/src/pages/index.astro index b787b78..027849a 100644 --- a/apps/site/src/pages/index.astro +++ b/apps/site/src/pages/index.astro @@ -12,6 +12,93 @@ const sourceInstall = `git clone https://github.com/sandwichfarm/loopwire cd loopwire pnpm install pnpm check`; +const releaseBase = "https://github.com/sandwichfarm/loopwire/releases/download/v0.1.0"; +const releaseKey = + "https://raw.githubusercontent.com/sandwichfarm/loopwire/7e0c6b17a5b12efc9f62df9a314781ad9fbb20ec/packaging/release-signing-public.pem"; +const installer = "curl -fsSL https://loopwire.app/install.sh | bash"; +function nativeInstall(asset: string, command: string) { + return [ + `curl -fSLO ${releaseBase}/${asset}`, + `curl -fSLO ${releaseBase}/SHA256SUMS`, + `curl -fSLO ${releaseBase}/SHA256SUMS.sig`, + `curl -fsSL ${releaseKey} -o loopwire-release-key.pem`, + "openssl dgst -sha256 -verify loopwire-release-key.pem -signature SHA256SUMS.sig SHA256SUMS", + "sha256sum --check --ignore-missing SHA256SUMS", + command + ].join(" &&\n"); +} +const installOptions = [ + { + id: "automatic", label: "Automatic", heading: "Install Loopwire", command: installer, + note: "Recommended. Detects your Linux distribution and architecture, verifies the release, and installs or " + + "upgrades Loopwire. Shows each step before it runs.", + detail: "Uses a matching native package, an existing AUR helper, or Nix; otherwise a portable install. Requests " + + "approval for package-manager changes.", + href: "/install.sh", link: "Read the installer" + }, + { + id: "arch", label: "Arch", heading: "Arch Linux · AUR", command: "yay -S --needed loopwire-bin", + note: "Prebuilt stable release for x86_64 and ARM64. Requires yay; if you use paru, replace yay with paru. " + + "Review the package build when prompted.", + detail: "No AUR helper? Use Automatic for a portable install. The loopwire, loopwire-bin, and loopwire-git packages conflict; choose one.", + href: "https://aur.archlinux.org/packages/loopwire-bin", link: "View AUR package" + }, + { + id: "ubuntu", label: "Ubuntu", heading: "Ubuntu 24.04 · x86_64", + command: nativeInstall("loopwire_0.1.0-1ubuntu24.04_amd64.deb", "sudo apt install ./loopwire_0.1.0-1ubuntu24.04_amd64.deb"), + note: "Manual signed v0.1.0 package. Run these steps together in an empty folder; a failed check stops the " + + "install. Automatic handles these steps for you.", + detail: "Other Ubuntu versions and ARM64 use the portable path. A native APT repository is planned to shorten this setup.", + href: "https://github.com/sandwichfarm/loopwire/issues/35", link: "Track simpler APT installs" + }, + { + id: "debian", label: "Debian", heading: "Debian 13 · x86_64", + command: nativeInstall("loopwire_0.1.0-1debian13_amd64.deb", "sudo apt install ./loopwire_0.1.0-1debian13_amd64.deb"), + note: "Manual signed v0.1.0 package. Run these steps together in an empty folder; a failed check stops the " + + "install. Automatic handles these steps for you.", + detail: "Other Debian versions and ARM64 use the portable path. A native APT repository is planned to shorten this setup.", + href: "https://github.com/sandwichfarm/loopwire/issues/35", link: "Track simpler APT installs" + }, + { + id: "fedora", label: "Fedora", heading: "Fedora 44 · x86_64", + command: nativeInstall("loopwire-0.1.0-1.fc44.x86_64.rpm", "sudo dnf --setopt=localpkg_gpgcheck=0 install ./loopwire-0.1.0-1.fc44.x86_64.rpm"), + note: "Manual signed v0.1.0 download. Run these steps together in an empty folder. The signed checksum " + + "authenticates the RPM before DNF installs it.", + detail: "The RPM has no embedded signature; the signature exception applies only to local packages. Automatic " + + "handles verification for you. A signed DNF repository is planned.", + href: "https://github.com/sandwichfarm/loopwire/issues/36", link: "Track simpler Fedora installs" + }, + { + id: "opensuse", label: "openSUSE", heading: "openSUSE Tumbleweed · x86_64", + command: nativeInstall("loopwire-0.1.0-1.x86_64.rpm", "sudo zypper install --allow-unsigned-rpm ./loopwire-0.1.0-1.x86_64.rpm"), + note: "Manual signed v0.1.0 download. Run these steps together in an empty folder. The signed checksum " + + "authenticates the RPM before Zypper installs it.", + detail: "The RPM has no embedded signature; the exception applies to this verified file. Automatic handles " + + "verification for you. A signed repository is planned.", + href: "https://github.com/sandwichfarm/loopwire/issues/37", link: "Track simpler openSUSE installs" + }, + { + id: "nix", label: "Nix / NixOS", heading: "Nix · user profile", + command: 'nix --extra-experimental-features "nix-command flakes" profile install github:sandwichfarm/loopwire#loopwire-bin', + note: "Install the release-bound package into your user profile. Requires Nix; the command enables flakes for this invocation only.", + detail: "For repeat installs and upgrades, use Automatic. Published hashes cover x86_64 and ARM64; native build proof currently covers x86_64.", + href: "/docs/guide/install.html#nix-nixos", link: "Nix install details" + }, + { + id: "portable", label: "Other Linux", heading: "Portable Linux · user install", + command: `${installer} -s -- --method portable`, + note: "Signed x86_64 or ARM64 archive, installed under ~/.local. Run it again to upgrade. Does not need sudo or change your audio configuration.", + detail: "Requires a compatible glibc desktop with GTK/WebKitGTK libraries. Node.js is needed for background " + + "restore and provider commands. On NixOS, use the Nix tab.", + href: "/docs/guide/install.html#portable-linux", link: "Requirements and upgrade details" + }, + { + id: "source", label: "Source", heading: "Build from source", command: sourceInstall, + note: "Contributor checkout. Requires Git, Node.js 22.12+, and pnpm 11.3+. This installs workspace dependencies and runs the project checks.", + detail: "For a native desktop build, follow the developer guide for Rust and Linux build dependencies.", + href: "/docs/developer/architecture.html", link: "Developer guide" + } +]; const capabilities = [ ["PipeWire", "First-class routing path"], ["PulseAudio", "Compatibility adapter"], @@ -56,18 +143,28 @@ const applicationJsonLd = { Releases -
+
+ + {installOptions.map((option, index) => ( + + ))}
-
-

Current source install

-

Pre-release today. Signed public artifacts and the curl installer stay gated until the release workflow, Bunny deploy, and VM proof pass.

-
- + +

-
{sourceInstall}
-

+