Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 4 additions & 3 deletions .planning/STATE.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand Down Expand Up @@ -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

Expand Down
Original file line number Diff line number Diff line change
@@ -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.
Original file line number Diff line number Diff line change
@@ -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.
23 changes: 15 additions & 8 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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.
Expand All @@ -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

Expand Down
12 changes: 12 additions & 0 deletions apps/docs/docs/developer/e2e.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Loading