TylerandClaude Fable 5
fedf1d24c0
Template tests / tests (pull_request) Failing after 31s
Phase 3 of the improvement plan (PR 8 of the sequence): the apt/X11 packaging half of Linux support, in separate Linux-specific files. Replaces the old scripts/package-linux.sh, which the audit flagged as "not production packaging" (it copied the whole dev node_modules — including vulnerable build deps — plus docs/prompts/examples/audit files, hardcoded amd64, declared only xinput, lacked desktop/icon/MIME integration, and could build without node_modules). Production builder (packaging/linux/debian/package.sh): - Stages ONLY runtime files: app code, a fixed Electron runtime, and the production npm deps (enumerated via npm ls --omit=dev). Never copies the development node_modules; guards against electron-builder/app-builder-lib leaking in. Fails if node_modules is absent instead of shipping an unusable artifact. - Detects architecture (dpkg --print-architecture, x64/arm64) rather than hardcoding amd64. Generates DEBIAN/control from control.in with proper runtime Depends, real maintainer, and homepage. - Installs a desktop entry, hicolor icons (16–512), .sfgz/.sfglt MIME registration, the launcher, and the license. postinst makes chrome-sandbox setuid and refreshes desktop/MIME/icon caches; postrm cleans them. - Emits a .deb, a portable tarball that now INCLUDES /usr/bin/stepforge (the old tarball omitted it), and a sha256 sums file. Launcher (packaging/linux/common/launcher.sh): - Runs sandboxed; prefers the user-namespace sandbox, accepts a root-owned setuid helper, and otherwise refuses to launch with an actionable message. --no-sandbox requires an explicit STEPFORGE_ALLOW_NO_SANDBOX opt-in. Never installs anything at runtime. Setup (separate build vs runtime, apt only): - scripts/linux/apt/install-runtime-deps.sh (Chromium/Electron libs, X11 tools, portal/PipeWire) and install-build-deps.sh (dpkg-dev, fakeroot, xvfb). Runtime script installs no build tools. Assets: original StepForge icon — packaging/assets/stepforge.svg plus a generator (scripts/make-icons.js) that renders the PNG set with the repo's own rasterizer/PNG writer (no third-party art). npm run icons regenerates them. Wiring: package.json gains package:linux:deb / package:linux:rpm / icons; build-release.sh uses the production builder and requires node_modules; README points at the apt/dnf guides. Tests: tests/unit/packaging-linux.test.js (structural: files present in their separate locations, old script gone, valid desktop entry, templated arch + runtime Depends, launcher gates --no-sandbox, builder requires node_modules and guards dev-dep leaks, apt build/runtime dep separation, original icon set generates a valid PNG) runs in the normal suite; tests/integration/linux/package-deb.test.sh builds a real .deb and asserts the right files present and the dev tree / build tooling / app docs absent (honest skip only when dpkg-deb/node_modules are genuinely missing). Verified locally: 276 unit tests pass; the integration test builds and validates stepforge_0.3.2_amd64.deb; build-release E2E passes with the new production package. Co-Authored-By: Claude Fable 5 <[email protected]>
68 lines
2.4 KiB
Markdown
68 lines
2.4 KiB
Markdown
# StepForge on apt-based Linux (Debian / Ubuntu)
|
|
|
|
This is the setup and packaging guide for **apt-based** distributions. Fedora
|
|
and other dnf-based systems have a separate guide: [dnf.md](dnf.md).
|
|
|
|
## Install from the .deb
|
|
|
|
```bash
|
|
sudo apt install ./stepforge_<version>_amd64.deb
|
|
```
|
|
|
|
apt pulls the required runtime libraries automatically (they are declared as
|
|
`Depends`). The package installs:
|
|
|
|
- the app and a fixed Electron runtime under `/opt/stepforge`,
|
|
- the `stepforge` launcher at `/usr/bin/stepforge`,
|
|
- a desktop entry, icons, and `.sfgz`/`.sfglt` file associations.
|
|
|
|
Launch it from your application menu or run `stepforge`.
|
|
|
|
### Sandbox
|
|
|
|
The launcher runs **sandboxed**. On most modern kernels the Chromium
|
|
user-namespace sandbox works out of the box; the package's `postinst` also
|
|
makes the setuid `chrome-sandbox` helper usable as a fallback. StepForge will
|
|
**not** silently launch unsandboxed — see the launcher's message if the
|
|
sandbox is unavailable.
|
|
|
|
## Install from the portable tarball
|
|
|
|
```bash
|
|
tar -xzf stepforge_<version>_linux-x64.tar.gz
|
|
# Install the runtime libraries first (see below), then run:
|
|
./usr/bin/stepforge # or move opt/stepforge to /opt and use the launcher
|
|
```
|
|
|
|
The tarball includes the `/usr/bin/stepforge` launcher (unlike older builds).
|
|
Install the runtime libraries with:
|
|
|
|
```bash
|
|
bash scripts/linux/apt/install-runtime-deps.sh
|
|
```
|
|
|
|
## Capture capabilities on apt systems
|
|
|
|
- **X11**: full per-click capture with an accurate marker (needs `xinput`).
|
|
- **Wayland**: screen capture via the XDG Desktop Portal + PipeWire; the
|
|
portal asks permission once per recording. Per-click capture with
|
|
coordinates is not exposed by Wayland, so recording uses a global hotkey or
|
|
interval trigger. StepForge reports the active trigger honestly.
|
|
|
|
Run StepForge and open Settings → Diagnostics to see the detected session
|
|
type, portal/PipeWire status, and the active capture profile.
|
|
|
|
## Build the .deb yourself
|
|
|
|
```bash
|
|
bash scripts/linux/apt/install-build-deps.sh # dpkg-dev, fakeroot, xvfb, …
|
|
nvm install && nvm use # pinned Node 22 (see .nvmrc)
|
|
npm ci
|
|
npm run package:linux:deb # -> build/artifacts/*.deb + tarball + sha256
|
|
```
|
|
|
|
The builder stages **only** runtime files: the app code, a fixed Electron
|
|
runtime, and production npm dependencies. It never copies the development
|
|
`node_modules`, docs, prompts, or examples, and it fails if `node_modules` is
|
|
missing rather than producing an unusable artifact.
|